What can we help you with?
What is necessary to try the API and how do I get the sandbox credentials?
You do not need to be a customer to try our API! Just contact our team at contact@br.ebury.com to get a free-of-charge credential and instant access to our sandbox environment.
What is the API authentication method?
The access to the Ebury Bank API is available using industry standard OAuth2 authentication methods for transparent and secure access to user data.
Token Generator for oAuth2:
In order to have access to your token, you need to make a request to this endpoint using HTTP Basic Authentication
(HTTP/1.0 - 11.1 Basic Authentication Scheme)The token will expire in 24 hours after being generated, we strongly suggest replacing it 1 hour before the expiration time. Making another token request.
Why am I receiving a 401 error during my tests?
Due our authentication method, you need to have access to a token, which is reponsible for check your credentials. If you already got a token and the error persists, please note that a token could be expired. Call authentication service again to receive a new one. Check our API page.
Should I pass empty strings for optional values?
If you don’t want to pass fields that are optional, your handler should not pass empty strings
I’m getting errors while using the REST APIs. What do I do?
You can read about REST API errors in the REST API reference. This list can help you anticipate and account for most errors. You can also learn how to handle common REST Payment API errors.
Who do I contact if I have questions or need support?
You can contact us by e-mail contact@ebury.com or being part of our Slack channel. Our timezone is BRT
What are the status of a typical payment transaction?
- WAITING_CONSUMER: occurs when the payment is waiting some confirmation or authentication by the consumer. Generally, occurs on transactions of debit, on banking slips that is waiting payment or when the issuer has two authentication factors enabled because of risk.
- AUTHORIZED: the payment was authorized by issuer. On that status, the consumer's balance was checked but the payment is not confirmed. The payment is pending of confirmation.You can confirm a payment automatically by the parameter "confirm: true".
- CONFIRMED: the payment was authorized by issuer and is confirmed.
- CANCELED: the payment was canceled.
- DECLINED_BY_ISSUER: the payment was declined by issuer and the reason is described on response
- DECLINED_BY_BUSINESS_RULE: the payment was declined by some business rule from Ebury Bank and the reason is described on response
What are the local payments methods in Brazil?
- Brazilian Bank Slip: Also knows as Boleto Bancario or voucher, is a very popular method that allows sell to consumers without a credit or debit card. It can be paid online or offline, in cash, mobile or online banking using a barcode. It is a method with zero risk of fraud or chargeback and can take until three days to be settled.
- Brazilian Domestic Cards: Only a few percentage of brazilians have cards that works on international transactions. Our platform is ready to offer access to the whole universe of credit and debit cards of brazilians consumers.
- Online Banking (TEF): Also knows online debit, is a method that connects our platform direct to a online bank account with instantaneous response, without dependence of a card. It is a method with zero risk of fraud or chargeback.
Please , note that this support will be available soon.
What are the use cases of late confirmation function?
Represented as the “confirm” property on a payment request, it indicates that payment will check and block the amount on consumer’s balance but is awaiting the confirmation message. It is a useful function when you have to run business rules before product shipping.
What are the card brands and payment types available?
General availability by Card Brand Card Payment Type Mastercard Visa Amex Elo Hipercard Diners Credit card Available Available Available Available Available Available Credit card with installments Available Available Available Available Available Available Credit with authentication Available Available Unavailable Unavailable Unavailable Unavailable Debit with authentication Available Available Unavailable Unavailable Unavailable Unavailable Soft Descriptor Available Available Available Available Available Unavailable We are increasing new card brands and payment types every month.
What are local payment methods available?
We have local support to bank slip (Boleto Bancario). Please check our API guide to know more about it.
Soon, we will have support to Online Debit (Bank Transfers) to main issuers in Brazil.
How a payment cancellation works?
Our platform is ready to process cancellation of payments, including partial amount and with more than one cancellation, limited to total amount from payment. You can decide what rules are better to your business model.
The amount will be available on consumer bank account until 10 business days.
Partial cancellations can only be made from the next day onwards (D+N, where N is greater than 0). The limit for partial cancellations is 1 per day for each transaction (it is an acquirer limitation).
We are able to communicate consumer by e-mail about cancellation rules and events on payments. Please, let us know to activate this feature and communicate with consumer on your behalf.
Card numbers and general information for testing
While testing, use only the test credit card numbers on table bellow. Other numbers produce an error.
The expiration date must be a valid date in the future and the secure code is not validated on test environment.
Observation: To be able to use Debit Card Without Authenticate, it is necessary to have a contract with the card issuer.
Card number and scenarios for test Card Number Payment Type Installments Http Code Result 4556897654968402 Credit 3 200 OK Success 6550393682603873 Credit 1 200 OK Success 6550430681715066 Credit 1 422 Denied 4929785925958759 Credit 3 200 OK Success 4024007129267307 Credit 1 200 OK Success 4024007159375863 Credit 3 200 OK Success 5121116960598636 Credit 3 200 OK Success 342398203700310 Credit 3 200 OK Success 342091561592540 Credit 3 200 OK Success 6011652830881662 Credit 1 200 OK Success 6370950000000006 Credit 1 200 OK Success 6370950000000006 Credit 3 200 OK Success 6370950000000006 Credit 6 200 OK Success 4024007117676337 Credit 3 422 Denied 6370950000000005 Credit 2 422 Denied 4532882971768528 Debit 1 200 OK Success 4716071517283162 Debit 1 422 Denied 5532882971768528 Debit 1 200 OK Success 5716071517283162 Debit 1 422 Denied 5200000000001096 Debit Without Authenticate 1 200 OK Success 4000000000001000 Debit Without Authenticate 1 200 OK Success 2221000601734667 Debit Without Authenticate 1 422 Denied 4000000000001109 Debit Without Authenticate 1 422 Denied National IDs for test Please, as national id is a mandatory field on API, please use one described on table bellow:
47418692021, 31188623001 or 32027006001
Expected scenarios for TSP payments (Sandbox environment)
As TSP is a specialization of payments with card numbers and a service not provided by Ebury Bank, in the sandbox environment, it have to use the below pattern to inform the tokenized card number.
token-brand-card_number
Where:
- token - fixed
- brand - card brand
- card_number - card numbers and their scenarios listed at FAQ #13
All other rules at FAQ #13 are valid.Some examples of tokenized card number following above pattern:
Tokenized card numbers and scenarios for TSP tests Token Payment Type Installments Http Code Result token-elo-4556897654968402 Credit 3 200 OK Success token-elo-4024007129267307 Credit 1 200 OK Success token-elo-6550430681715066 Credit 1 422 Denied token-mastercard-6550393682603873 Credit 1 200 OK Success token-mastercard-6370950000000006 Credit 1 200 OK Success token-mastercard-4024007117676337 Credit 3 422 Denied token-visa-4929785925958759 Credit 3 200 OK Success token-visa-6370950000000006 Credit 1 200 OK Success token-visa-6370950000000006 Credit 3 200 OK Success token-visa-6370950000000005 Credit 2 422 Denied Expected scenarios for Pix payments (Sandbox environment)
Pix payments are asynchronous and depend on the final user to finalize the payment in his own bank. This scenario cannot be replicated in the sandbox environment.
Therefore to simulate some expected scenarios for Pix payments it is necessary to send the last number of the amount field value following the payload below:
{
"amount": 1.01
}
We will be consider behavior as the table below:
Scenario Description Decimal Number Status after creation Status after 3 seconds QR Code generated sucessfully and after the creation approved *.*1 WAITING_CONSUMER CONFIRMED Transaction denied on creation *.*2 DECLINED_BY_ISSUER DECLINED_BY_ISSUER Transaction denied after the creation *.*3 WAITING_CONSUMER CANCELED QR Code generated succesfully and payment does not receive any updates after *.*4 WAITING_CONSUMER WAITING_CONSUMER Expected scenarios for Slip payments (Sandbox environment)
Slip payments are asynchronous and depend on the final user to finalize the payment in his own bank. This scenario cannot be replicated in the sandbox environment.
Therefore to simulate some expected scenarios for Slip payments it is necessary to send the last number of the amount field value following the payload below:
{
"amount": 1.01
}
We will be consider behavior as the table below:
Scenario Description Decimal Number Status after creation Status after 3 seconds Bank slip generated sucessfully and after the creation was paid *.*1 WAITING_CONSUMER CONFIRMED Bank slip denied on creation *.*2 DECLINED_BY_BUSINESS_RULES DECLINED_BY_BUSINESS_RULES Bank slip expired after the creation *.*3 WAITING_CONSUMER CANCELED Expected scenarios for Electronic Bank Transfer payments (Sandbox environment)
Electronic Bank Transfer payments are asynchronous and depend on the final user to finalize the payment in his own bank. This scenario cannot be replicated in the sandbox environment.
Therefore to simulate some expected scenarios for Electronic Bank Transfer payments it is necessary to send the last number of the amount field value following the payload below:
{
"amount": 1.01
}
We will be consider behavior as the table below:
Scenario Description Decimal Number Status after creation Status after 3 seconds TED generated sucessfully and after the creation was paid *.*1 WAITING_CONSUMER CONFIRMED TED expired after the creation *.*3 WAITING_CONSUMER CANCELED Expected scenarios for payments with 3DS authentication (Sandbox environment)
In payments with 3DS authentication, it is necessary to send the ECI field, which indicates the authentication result of the cardholder's card, and according to it, it is decided whether the transaction will be approved or not.
Therefore, to simulate some expected scenarios for payments with 3DS authentication, let's consider the behavior according to the table below:
ECI code Transaction Meaning Http Code Result 02 or 05 Success in 3DS authentication by the Issuing Bank 200 Success 01 or 06 Success in 3DS authentication by Brand 200 Success 00 or 07 Authentication failed for various card-related reasons 422 Denied 04 Data Only - No Authentication 200 Success Expected scenarios for Nupay payments (Sandbox environment)
Nupay payments are asynchronous and depend on the final user to finalize the payment. This scenario cannot be replicated in the sandbox environment.
Therefore to simulate some expected scenarios for Nupay payments it is necessary to send the two last numbers of the amount field value following the payload below
{
"amount": 1.01
}
We will be consider behavior as the table below:
Scenario Description Decimal Number Status after creation Status after 3 seconds Payment created successfully in app and approved by client *.01 WAITING_CONSUMER CONFIRMED Transaction denied on creation *.02 DECLINED_BY_ISSUER DECLINED_BY_ISSUER Transaction denied after the creation *.03 WAITING_CONSUMER CANCELED Payment generated successfully in app and payment does not receive any updates after *.04 WAITING_CONSUMER WAITING_CONSUMER Transaction denied on creation because is canceled by Nubank (national id is not client) *.11 DECLINED_BY_ISSUER DECLINED_BY_ISSUER Payment created successfully in app and canceled by Nubank (national id is not client) *.12 WAITING_CONSUMER CANCELED Payment created successfully in app and canceled after client not confirm (timeout) *.19 WAITING_CONSUMER CANCELED Cards verification (Sandbox environment)
In card verification, All test cards listed at FAQ #13 are valid. Otherwise, the responses are based on the last number of the card sent in request.
The card brand in response will be always MASTERCARD.
We will be consider behavior as the table below:
Scenario Description Last card number Response in status The card present in Card number and scenarios for test table - VERIFIED The card was checked and denied 0 DENIED The card was not checked 1 NOT_VERIFIED The card was checked successfull 2 VERIFIED The card was checked successfull with tokenize 2 VERIFIED + Card Token Error on checking card other value ERROR