Payments
1. 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 econnect@ebury.com to get a free-of-charge credential and instant access to our sandbox environment.
2. 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.
3. 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.
4. 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
5. 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.
6. Who do I contact if I have questions or need support?
You can contact us by e-mail econnect@ebury.com or being part of our Slack channel. Our timezone is BRT
7. 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
8. 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.
9. 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.
10. 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.
11. 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.
12. 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.
13. What are the available options for allocating fees for payment links, and how does the choice affect the possibility of partial cancellation via PIX?
We offer two options for allocating fees in payment links:
Consumer Fee Allocation: In this method, we calculate the net amount to be received by the merchant, and the remaining amount (including fees) is paid by the consumer. For this consumer fee allocation method, we do not offer the option of partial payment via PIX.
Merchant Fee Allocation: In this modality, the merchant assumes the cost of the fees.
Therefore, the partial PIX cancellation functionality is not available when the fee allocation option is directed to the consumer.
14. 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
15. 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 token-visa-6370950000000012 Credit 1 200 OK Success token-visa-6370950000000012 Credit 2 200 OK Success token-visa-6370950000000012 Credit 3 200 OK Success token-visa-6370950000000012 Credit 4 200 OK Success token-visa-6370950000000012 Credit 5 200 OK Success token-visa-6370950000000012 Credit 6 200 OK Success token-visa-6370950000000012 Credit 7 200 OK Success token-visa-6370950000000012 Credit 8 200 OK Success token-visa-6370950000000012 Credit 9 200 OK Success token-visa-6370950000000012 Credit 10 200 OK Success token-visa-6370950000000012 Credit 11 200 OK Success token-visa-6370950000000012 Credit 12 200 OK Success token-visa-6370950000000112 Credit 1 422 Denied token-visa-6370950000000112 Credit 2 422 Denied token-visa-6370950000000112 Credit 3 422 Denied token-visa-6370950000000112 Credit 4 422 Denied token-visa-6370950000000112 Credit 5 422 Denied token-visa-6370950000000112 Credit 6 422 Denied token-visa-6370950000000112 Credit 7 422 Denied token-visa-6370950000000112 Credit 8 422 Denied token-visa-6370950000000112 Credit 9 422 Denied token-visa-6370950000000112 Credit 10 422 Denied token-visa-6370950000000112 Credit 11 422 Denied token-visa-6370950000000112 Credit 12 422 Denied 16. 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 BRL amount “cent” 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 17. 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 BRL amount “cent” 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 18. 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 BRL amount “cent” 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 19. 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 20. 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 BRL amount “cent” 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 21. 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 22. What are the types of report available?
There are three types of reports that we provide through our REST API and/or via our web portals. Each report contains specific details offering payments, conciliation and transaction statements insights.
Below you will find the available reports, along with their descriptions and the list of available fields to help you better understand the structure and usage of each report.
PAYIN-CONCILIATION
This report provides details about payments released for conciliation, including settlements, chargebacks and refunds. It helps merchants align transactions with financial records and ensure data accuracy.
It is generated automatically on a daily basis, around 4:00 AM UTC, and contains all events and updates that occurred during the previous day.
Field Description total_settlement_amount Total sum of settled transactions’ gross amounts total_settlement_net_amount Total sum of settled transactions’ net amounts iof_total Total IOF amount of all transactions settlement_iof_total Total IOF amount of settled transactions settlement_currency Currency used for settled transactions settlement_date Date when the transaction was settled transfer_date Date when the transaction was transferred PAYMENTS SECTION payment_id Unique payment transaction identifier merchant_id Unique merchant identifier correlation_id Correlation identifier order_id Unique Order identifier currency_code Currency used for settled transaction settlement_amount Settled transaction's net amount transaction_fee_fixed Fixed fee deducted from the transaction transaction_fee_variable Variable fee deducted from the transaction iof_by_merchant Merchar IOF to be deducted from the transaction amount_iof IOF amount deducted from the transaction amount_iof_br IOF amount deducted from the transaction in BRL amount_br_wo_iof Transaction amount without IOF in BRL amount_br Transaction amount with IOF deducted in BRL payment_type_code Payment transaction type identifier code anticipation_fee Fee amount charged for transaction's anticipation installments_total_no Total number of payment transaction's installments transaction_date Date and time when the transaction was created CHARGEBACKS SECTION payment_id Unique payment transaction identifier merchant_id Unique merchant identifier correlation_id Correlation identifier order_id Unique Order identifier debit_credit Indicates whether the transaction is debit or credit settlement_currency_code Currency used for the transaction chargeback_amount_br Chargeback amount in BRL chargeback_settlement_amount Payment transaction's settlement amount payment_type_code Payment transaction type code acquirer Acquiring bank or processor handling the chargeback chargeback_date Date when the chargeback was registered chargeback_reason_code Code indicating the reason for the chargeback chargeback_description Description indicating the reason for the chargeback purchase_date Date when the payment transaction was created REFUNDS SECTION payment_id Unique payment transaction identifier merchant_id Unique merchant identifier correlation_id Correlation identifier order_id Unique Order identifier settlement_currency_code Currency used for the transaction settlement_amount Settled transaction's net amount amount_br Settled transaction's amount in BRL refund_amount Refund gross amount refund_net_amount Refund net amount payment_type_code Payment transaction type identifier code refund_request_date Date when the refund was requested fx_rate Exchange rate applied to the refund installments Number of installments refunded PAYMENT-VIEW
This report provides a clear overview of payments, including identification data, payer details, transaction amounts, statuses, and key dates, making it easier to track and validate individual payments.
It can be requested either through the API or via the Portal by selecting a start and end date (up to a maximum range of 31 days). The report always retrieves the most recent status of each transaction within the selected period.
Field Description date Date when payment was created correlation_id Unique correlation identifier document Customer document number name Customer name gross_amount Gross amount of the payment transaction in local currency gross_foreign_amount Gross amount of the payment transaction in foreign currency net_amount Net amount of the payment transaction in local currency net_foreign_amount Net amount of the payment transaction in foreign currency payment_date Date when payment was confirmed status Last status of the payment transaction payment_id Payment transaction identifier STATEMENT-TRANSACTIONS-BY-REMITTANCE
This report provides a detailed view of transactions grouped by remittance. It contains transaction amounts, card details, statuses, and exchange rate information, allowing merchants to review and reconcile remittances with greater accuracy.
Field Description id Payment transaction identifier nsu Unique sequential number identifying(NSU) date Date when the transaction was created name Customer name net_amount Net amount of the payment transaction in local currency foreign_net_amount Net amount of the payment transaction in foreign currency gross_amount Gross amount of the payment transaction in local currency foreign_gross_amount Gross amount of the payment transaction in foreign currency type Payment transaction type installments_total Total number of the payment transaction's installments installments_current Current payment transaction's installment number card_number Masked card number card_brand Card brand transaction_status Current payment transaction's status chargeback_status Payment transactionm chargeback status payment_status Current payment transaction status correlation_id Correlation identifier exchange_rate Exchange rate applied exchange_rate_currency Currency of the exchange rate applied