Verify Account

This guide quickly demonstrates how to verify destination accounts whether it exists or not. We will walk you through the basic steps to achieve this goal using your already existing API integration.

Instructions

Follow the steps below:

1. Verify account using the /ws/payout/verify_account end-point

   To verify account, you will use the /ws/payout/verify_account endpoint.

   The following fields are required:

   Field	Description
   integration_key	Your EBANX integration key.
   target	Provider that will process the payment (mercadopago, pix, etc)
   target_account	Destination account to query
   country	The two-letter country code for the customer country. In this case, we'll show the method to br(Brazil)

   The following example shows how to verify a destination account:

   curl -X POST 'https://sandbox.ebanx.com/ws/payout/verify_account' \
       -d 'integration_key=your_test_integration_key' \
       -d 'target=mercadopago' \
       -d 'target_account=janedoe@someone.co' \
       -d 'country=br'

   And a successful query will return a JSON Object with status "valid".

   {
       "status": "valid",
       "message": "Account is valid"
   }

   {
       "status": "valid",
       "message": "Account does not have KYC complete in provider"
   }

   And a unsuccessful query will return a JSON Object with status "invalid", with a message explaining the reason.

   {
       "status": "invalid",
       "message": "Account not able to receive transfers in this country"
   }

   {
       "status": "invalid",
       "message": "Account does not exist in provider"
   }

Errors

If an API call fails, EBANX returns a JSON response with error details.

HTTP Status Code	Description
400	Invalid Request
401	Authentication Error
404	Account Error
424	Provider Unavailable
429	Limit Rate
500	Server Side Error
504	Internal Error

The following key-value pairs exist with each error response body.

{
  "code":"limit_rate_reached",
  "error": "Maximum attempts reached. Please try again in a few minutes."
}

Error codes

The table below lists all possible error codes returned by the Verify Account API.

Code	Error
HP-VT-01	Invalid json expression
HP-VT-02	Empty json payload
HP-VT-03	Empty integration_key value
HP-VT-04	Invalid integration_key value
HP-VT-05	Account is not enabled
HP-VT-06	Target requested not found
HP-VT-07	Target account is empty
HP-VT-08	Invalid country
HP-VT-09	Target not enabled for this country
HP-VT-10	Target requested not available for query
HP-VT-11	Configurations for target are missing for merchant
HP-VT-12	Configurations for target are incomplete
HP-VT-13	Authentication failure
HP-CM-13	Empty bank name
HP-CM-14	Invalid bank name
HP-CM-15	Empty account type
HP-CM-16	Invalid account type
HP-CM-18	Empty bank account
HP-CM-19	Empty bank branch
HP-CM-20	Empty bank details
HP-CM-86	Bank details should be a valid phone number
limit_rate_reached	Maximum attempts reached. Please try again in a few minutes.
error	A server side error occurred

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.