Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Brazil installments

Flag the payment as debit or credit, and make credit card installment payments.

In Brazil, shoppers commonly use a combo 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?

Here we explain how to flag in-store card payments as credit or debit, and how to make credit card installment payments:

With a Terminal API integration

The flow 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 to the terminal and completes the payment.
  5. When the transaction is approved, you receive a response containing receipt data.

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.

To initiate the payment:

  1. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:
      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the cash register.
      POIID -white_check_mark- The unique ID of the terminal that you want to send this request to. Format: [device model]-[serial number].
    • PaymentRequest: The request body. This must include:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your unique reference for this request. In your Customer Area and Adyen reports, this will show as the merchant reference for the transaction.
      • TimeStamp: date and time of the request in UTC format.
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: the transaction currency.
      • RequestedAmount: The final 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.

    Here are some sample requests:

    {
      "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);
  4. Check the payment result.
    If the payment is successful, the terminal display 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.

    Here is a sample 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"...}
            }
        }
    }

From a standalone terminal

If you're using our Standalone solution in Brazil, the installments flow is as follows:

  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. Select Start on the terminal display, or select the Confirm key on the keypad.
  3. Enter the transaction value and confirm to continue.
  4. Let the shopper insert their card into the card reader of the terminal.

    Choosing debit or credit and choosing installments is only possible when the shopper inserts their card.
    If the shopper makes a contactless transaction, a combo card will default to a credit payment without installments.

  5. Follow the instructions on the terminal to enter how the shopper prefers to pay.
  6. Let the shopper complete the payment on the terminal. They may need to enter their PIN or signature to verify the payment.

If the payment is successful, the terminal shows that the payment is approved, and prints a merchant receipt and then a shopper receipt.

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