What can we help you with?

  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 contact@br.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 contact@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 TypeMastercardVisaAmexEloHipercardDiners
    Credit cardAvailableAvailableAvailableAvailableAvailableAvailable
    Credit card with installmentsAvailableAvailableAvailableAvailableAvailableAvailable
    Credit with authenticationAvailableAvailableUnavailableUnavailableUnavailableUnavailable
    Debit with authenticationAvailableAvailableUnavailableUnavailableUnavailableUnavailable
    Soft DescriptorAvailableAvailableAvailableAvailableAvailableUnavailable

    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. 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 NumberPayment TypeInstallmentsHttp CodeResult
    4556897654968402Credit3200 OKSuccess
    6550393682603873Credit1200 OKSuccess
    6550430681715066Credit1422Denied
    4929785925958759Credit3200 OKSuccess
    4024007129267307Credit1200 OKSuccess
    4024007159375863Credit3200 OKSuccess
    5121116960598636Credit3200 OKSuccess
    342398203700310Credit3200 OKSuccess
    342091561592540Credit3200 OKSuccess
    6011652830881662Credit1200 OKSuccess
    6370950000000006Credit1200 OKSuccess
    6370950000000006Credit3200 OKSuccess
    6370950000000006Credit6200 OKSuccess
    4024007117676337Credit3422Denied
    6370950000000005Credit2422Denied
    4532882971768528Debit1200 OKSuccess
    4716071517283162Debit1422 Denied
    5532882971768528Debit1200 OKSuccess
    5716071517283162Debit1422 Denied
    5200000000001096Debit Without Authenticate1200 OKSuccess
    4000000000001000Debit Without Authenticate1200 OKSuccess
    2221000601734667Debit Without Authenticate1422 Denied
    4000000000001109Debit Without Authenticate1422 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

  14. 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
    TokenPayment TypeInstallmentsHttp CodeResult
    token-elo-4556897654968402Credit3200 OKSuccess
    token-elo-4024007129267307Credit1200 OKSuccess
    token-elo-6550430681715066Credit1422Denied
    token-mastercard-6550393682603873Credit1200 OKSuccess
    token-mastercard-6370950000000006Credit1200 OKSuccess
    token-mastercard-4024007117676337Credit3422Denied
    token-visa-4929785925958759Credit3200 OKSuccess
    token-visa-6370950000000006Credit1200 OKSuccess
    token-visa-6370950000000006Credit3200 OKSuccess
    token-visa-6370950000000005Credit2422Denied
  15. 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 DescriptionDecimal NumberStatus after creationStatus after 3 seconds
    QR Code generated sucessfully and after the creation approved*.*1WAITING_CONSUMERCONFIRMED
    Transaction denied on creation*.*2DECLINED_BY_ISSUERDECLINED_BY_ISSUER
    Transaction denied after the creation*.*3WAITING_CONSUMERCANCELED
    QR Code generated succesfully and payment does not receive any updates after*.*4WAITING_CONSUMERWAITING_CONSUMER
  16. 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 DescriptionDecimal NumberStatus after creationStatus after 3 seconds
    Bank slip generated sucessfully and after the creation was paid*.*1WAITING_CONSUMERCONFIRMED
    Bank slip denied on creation*.*2DECLINED_BY_BUSINESS_RULESDECLINED_BY_BUSINESS_RULES
    Bank slip expired after the creation*.*3WAITING_CONSUMERCANCELED
  17. 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 DescriptionDecimal NumberStatus after creationStatus after 3 seconds
    TED generated sucessfully and after the creation was paid*.*1WAITING_CONSUMERCONFIRMED
    TED expired after the creation*.*3WAITING_CONSUMERCANCELED
  18. 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 codeTransaction MeaningHttp CodeResult
    02 or 05Success in 3DS authentication by the Issuing Bank200Success
    01 or 06Success in 3DS authentication by Brand200Success
    00 or 07Authentication failed for various card-related reasons422Denied
    04Data Only - No Authentication200Success
  19. 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 DescriptionDecimal NumberStatus after creationStatus after 3 seconds
    Payment created successfully in app and approved by client*.01WAITING_CONSUMERCONFIRMED
    Transaction denied on creation*.02DECLINED_BY_ISSUERDECLINED_BY_ISSUER
    Transaction denied after the creation*.03WAITING_CONSUMERCANCELED
    Payment generated successfully in app and payment does not receive any updates after*.04WAITING_CONSUMERWAITING_CONSUMER
    Transaction denied on creation because is canceled by Nubank (national id is not client)*.11DECLINED_BY_ISSUERDECLINED_BY_ISSUER
    Payment created successfully in app and canceled by Nubank (national id is not client)*.12WAITING_CONSUMERCANCELED
    Payment created successfully in app and canceled after client not confirm (timeout)*.19WAITING_CONSUMERCANCELED
  20. 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 DescriptionLast card numberResponse in status
    The card present in Card number and scenarios for test table-VERIFIED
    The card was checked and denied0DENIED
    The card was not checked1NOT_VERIFIED
    The card was checked successfull2VERIFIED
    The card was checked successfull with tokenize2VERIFIED + Card Token
    Error on checking cardother valueERROR
Copyright © 2024 Ebury Bank