Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Brazil in-store card payments

Learn how to make card payments, including with installments, in Brazil.

In Brazil, shoppers commonly use a card that has both a debit and a credit functionality, and most credit cards accept installment payments. Consequently, when paying by card, shoppers are asked to make some choices:

  • Do they want to pay by debit or credit?
  • If credit, do they want to make a one-off payment of the total amount or do they want to pay in installments?
  • If installments, how many installments?

When a shopper pays in installments, the cost is split into 2 to 12 equal monthly payments. These payments are charged to the shopper's credit card every 30 days until their purchase has been paid in full. This is popular with shoppers because they receive goods or services immediately, but spread the cost over multiple months.

Here we explain how to make Brazilian in-store card payments:

Card payment with a Terminal API integration

The flow for a card payment in Brazil with a Terminal API integration is as follows:

  1. Your store staff asks the shopper how they prefer to pay:

    • Debit or credit.
    • If credit: one-off payment or installments.
    • If installments: number of installments.

  2. Your store staff enters this information into your cash register.

    You need to make sure the cash register software is able to collect this information.

  3. Your cash register passes this information in the payment request.
  4. The shopper presents their card and enters their PIN or signature on the terminal.
  5. When the transaction is approved, you receive a response containing receipt data.

Before you begin

Before you make a Terminal API payment in Brazil, make sure you have designed your Adyen point of sale integration. This includes:

  1. Signing up for an Adyen test account.
  2. Determining your Adyen account structure and creating accounts for your physical stores.
  3. Ordering a terminal.
  4. Boarding the terminal to associate it with a physical store.
  5. Determining whether your integration will use a local or cloud-based architecture.
  6. Reading and understanding the Terminal API fundamentals.
  7. For a integration that uses asynchronous cloud communications, making sure you have set up display notifications. This is how your integration will receive the payment result.

Make the payment

The payment request to the Terminal API needs to contain a flag to indicate a debit or credit card payment. When paying by credit in installments, the request also needs to contain an object to define the installments.

When you make a POST request to the Terminal API to initiate a payment:

  1. Start constructing your PaymentRequest by specifying:

    • MessageHeader: This follows the standard MessageHeader structure, explained in Terminal API fundamentals, which includes:

      • ProtocolVersion: 3.0
      • MessageCategory: Payment. This indicates you are initiating a payment request.
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID for this transaction attempt. This needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal. This indicates which terminal the payment will be routed to.

    • PaymentRequest: The request body for the payment request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this payment request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the payment request, in UTC format.
      • PaymentTransaction.AmountsReq.Currency: The currency of the transaction. Must be BRL.
      • PaymentTransaction.AmountsReq.RequestedAmount: The transaction amount.

  2. Add a flag to specify whether the shopper wants to pay by debit or credit:

    • TransactionConditions.DebitPreferredFlag:
      • true: Makes a debit card payment.
      • false: Makes a credit card payment.

    For a debit payment or a one-off credit payment, no further parameters are required.

  3. If the shopper is paying by credit in installments, define the installments by adding:

    • PaymentData: The installment details. This contains:

      • PaymentType: Instalment
      • Instalment.InstalmentType: EqualInstalments
      • Instalment.SequenceNumber: 1
      • Instalment.Period: 1
      • Instalment.PeriodUnit: Monthly
      • Instalment.TotalNbOfPayments: The number of installments. The minimum is 2, the maximum 12.

  4. Submit your POST request to a Terminal API endpoint.

    Here are some sample requests for a debit card payment, a credit card payment without installments, and a credit card payment with 12 installments.

    Debit card payment

    {
      "SaleToPOIRequest":{
        "MessageHeader":{
          "ProtocolVersion":"3.0",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "MessageType":"Request",
          "ServiceID":"2307d64b8",
          "SaleID":"Demo",
          "POIID":"P400Plus-275040710"
        },
        "PaymentRequest":{
          "SaleData":{
            "SaleTransactionID":{
              "TransactionID":"TID-2018-07-23-21:43:03",
              "TimeStamp":"2018-07-23T21:43:03"
            },
            "SaleReferenceID":"TID-2018-07-23-21:43:03",
            "SaleToAcquirerData":""
          },
          "PaymentTransaction":{
            "AmountsReq":{
              "Currency":"BRL",
              "RequestedAmount":12000
            },
            "TransactionConditions":{
              "DebitPreferredFlag":true
            }
          }
        }
      }
    }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    PaymentRequest paymentRequest = new PaymentRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    saleData.setSaleReferenceID("TID-2018-07-23-21:43:03");
    saleData.setSaleToAcquirerData("");
    paymentRequest.setSaleData(saleData);
    
    PaymentTransaction paymentTransaction = new PaymentTransaction();
    AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("BRL");
    amountsReq.setRequestedAmount( BigDecimal.valueOf(12000) );
    paymentTransaction.setAmountsReq(amountsReq);
    
    TransactionConditions transactionConditions = new TransactionConditions();
    transactionConditions.setDebitPreferredFlag( Boolean.TRUE );
    paymentTransaction.setTransactionConditions(transactionConditions);
    paymentRequest.setPaymentTransaction(paymentTransaction);
    saleToPOIRequest.setPaymentRequest(paymentRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

    Credit card payment without installments

    {
      "SaleToPOIRequest":{
        "MessageHeader":{
          "ProtocolVersion":"3.0",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "MessageType":"Request",
          "ServiceID":"2307d64b8",
          "SaleID":"Demo",
          "POIID":"P400Plus-275040710"
        },
        "PaymentRequest":{
          "SaleData":{
            "SaleTransactionID":{
              "TransactionID":"TID-2018-07-23-21:43:03",
              "TimeStamp":"2018-07-23T21:43:03"
            },
            "SaleReferenceID":"TID-2018-07-23-21:43:03",
            "SaleToAcquirerData":""
          },
          "PaymentTransaction":{
            "AmountsReq":{
              "Currency":"BRL",
              "RequestedAmount":12000
            },
            "TransactionConditions":{
              "DebitPreferredFlag":false
            }
          }
        }
      }
    }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    PaymentRequest paymentRequest = new PaymentRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    saleData.setSaleReferenceID("TID-2018-07-23-21:43:03");
    saleData.setSaleToAcquirerData("");
    paymentRequest.setSaleData(saleData);
    
    PaymentTransaction paymentTransaction = new PaymentTransaction();
    AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("BRL");
    amountsReq.setRequestedAmount( BigDecimal.valueOf(12000) );
    paymentTransaction.setAmountsReq(amountsReq);
    
    TransactionConditions transactionConditions = new TransactionConditions();
    transactionConditions.setDebitPreferredFlag( Boolean.FALSE );
    paymentTransaction.setTransactionConditions(transactionConditions);
    paymentRequest.setPaymentTransaction(paymentTransaction);
    saleToPOIRequest.setPaymentRequest(paymentRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

    Credit card payment with 12 installments

    {
      "SaleToPOIRequest":{
        "MessageHeader":{
          "ProtocolVersion":"3.0",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "MessageType":"Request",
          "ServiceID":"2307d64b8",
          "SaleID":"Demo",
          "POIID":"P400Plus-275040710"
        },
        "PaymentRequest":{
          "SaleData":{
            "SaleTransactionID":{
              "TransactionID":"TID-2018-07-23-21:43:03",
              "TimeStamp":"2018-07-23T21:43:03"
            },
            "SaleReferenceID":"TID-2018-07-23-21:43:03",
            "SaleToAcquirerData":""
          },
          "PaymentTransaction":{
            "AmountsReq":{
              "Currency":"BRL",
              "RequestedAmount":12000
            },
            "TransactionConditions":{
              "DebitPreferredFlag":false
            }
          }
        },
        "PaymentData":{
          "PaymentType":"Instalment",
          "Instalment":{
            "InstalmentType":"EqualInstalments",
            "SequenceNumber":1,
            "Period":1,
            "PeriodUnit":"Monthly",
            "TotalNbOfPayments":12
          }
        }
      }
    }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    PaymentRequest paymentRequest = new PaymentRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    saleData.setSaleReferenceID("TID-2018-07-23-21:43:03");
    saleData.setSaleToAcquirerData("");
    paymentRequest.setSaleData(saleData);
    
    PaymentTransaction paymentTransaction = new PaymentTransaction();
    AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("BRL");
    amountsReq.setRequestedAmount( BigDecimal.valueOf(12000) );
    paymentTransaction.setAmountsReq(amountsReq);
    
    TransactionConditions transactionConditions = new TransactionConditions();
    transactionConditions.setDebitPreferredFlag( Boolean.FALSE );
    paymentTransaction.setTransactionConditions(transactionConditions);
    paymentRequest.setPaymentTransaction(paymentTransaction);
    saleToPOIRequest.setPaymentRequest(paymentRequest);
    
    PaymentData paymentData = new PaymentData();
    paymentData.setPaymentType( PaymentType.INSTALMENT );
    Instalment instalment = new Instalment();
    instalment.getInstalmentType.add( InstalmentType.EQUAL_INSTALMENTS );
    instalment.setSequenceNumber(1);
    instalment.setPeriod(1);
    instalment.setPeriodUnit( PeriodUnitType.MONTHLY );
    instalment.setTotalNbOfPayments(12);
    paymentData.setInstalment(instalment);
    saleToPOIRequest.setPaymentData(paymentData);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);
  5. Receive the payment result.
    If the payment is successful, the terminal screen shows the payment is approved and you receive a Terminal API response. This response contains:

    • PaymentReceipt: Dynamically generated receipt data that you can use for printing (or emailing) receipts. Both the merchant receipt and the shopper receipt have additional required keys:

      • productType: Indicates if the shopper paid by debit, credit, or credit in a specified number of installments.
      • cnpj: Identification number issued for the Brazilian National Registry of Legal Entities.

    • If the shopper paid by credit in installments, the response also includes:
      • PaymentResult.PaymentType: Instalment
      • PaymentResult.Instalment: Object containing the same installment details that you defined in the PaymentData of your PaymentRequest.

    Response for a credit card payment with 12 installments

    {
        "SaleToPOIResponse":{
            "MessageHeader":{...},
            "PaymentResponse":{
                "PaymentReceipt":[
                    {
                        "OutputContent":{
                            "OutputFormat":"Text",
                            "OutputText":[
                                ...
                                {
                                    "EndOfLineFlag":true,
                                    "Text":"key=productType&name=productType&value=Credit%20in%2012%20Installments"
                                },
                                {
                                    "EndOfLineFlag":true,
                                    "Text":"key=cnpj&name=cnpj&value=00.000.000%2F0000-00"
                                },
                                ...
                            ]
                        },
                        "DocumentQualifier":"CashierReceipt"
                    },
                    {
                        "OutputContent":{
                            "OutputFormat":"Text",
                            "OutputText":[
                                ...
                                {
                                    "EndOfLineFlag":true,
                                    "Text":"key=productType&name=productType&value=Credit%20in%2012%20Installments"
                                },
                                {
                                    "EndOfLineFlag":true,
                                    "Text":"key=cnpj&name=cnpj&value=00.000.000%2F0000-00"
                                },
                                ...
                            ]
                        },
                        "DocumentQualifier":"CustomerReceipt"
                    }
                ],
                "POIData":{...},
                "PaymentResult":{
                    "PaymentType":"Instalment",
                    ...
                    "Instalment":{
                        "InstalmentType":"EqualInstalments",
                        "SequenceNumber":1,
                        "Period":1,§
                        "PeriodUnit":"Monthly",
                        "TotalNbOfPayments":12
                    },
                    ...
                },
                "SaleData":{...},
                "Response":{"Result": "Success"...}
            }
        }
    }

Card payment from a Standalone terminal

If you're using our Standalone solution, you can initiate transactions directly from a Standalone terminal.

Before you begin

Before you make a card payment with a Standalone terminal, make sure you have completed the following steps:

  1. Signing up for an Adyen test account.
  2. Determining your Adyen account structure and creating accounts for your physical stores.
  3. Ordering a terminal with a built-in printer.
  4. Boarding the terminal to associate it with a physical store.
  5. Setting up the terminal as a Standalone terminal.

Make the payment

To make a card payment from a Standalone terminal:

  1. Ask the shopper how they prefer to pay:

    • Debit or credit.
    • If credit: one-off payment or installments.
    • If installments: number of installments.

  2. On the terminal screen, select Start.
  3. On the terminal keypad, enter the transaction value and press .
  4. Let the shopper present their card on the terminal.
  5. Follow the instructions on the terminal to enter the information obtained from the shopper about how they prefer to pay.
  6. Let the shopper enter their PIN or signature on the terminal.

If the payment is successful, the terminal screen shows the payment is approved. The terminal also prints a merchant receipt and a shopper receipt (in that order).

Reconciling installments

If a shoppers pays in installments, the first installment is immediately charged to the shopper's credit card, and all future installments will be charged automatically.
You receive the funds for each installment as it is settled. There is a settlement delay of 30 days.

We also offer advancements if you need funds sooner. There is an additional fee for this service. Contact your Adyen Account Manager for details.

If you use Standalone terminals, you will need to manually reconcile your point of sale transactions against your sales and returns.

For more information on how installments are settled and reconciled, see Reconcile installment payments.

See also