The shopping cart is where the information of the products chosen by the customer while browsing a store is gathered. This data may include item prices, shipping value, payment, and delivery methods, among others.

This guide will describe how to add payment information in the shopping cart by the API.

The payment information attachment in the shopping cart does not determine the final order payment method in itself. However, it allows the platform to update any relevant information that may be impacted by the payment method.

The first step is to get the orderFormId of the shopping cart you want to add the merchant context data to. For more information, access the Get cart information by ID guide.

To add payment data to the shopping cart, you need to use the Add payment data endpoint. In this request, you must send the orderFormId through the URL address, as shown by the example below:

https://{accountName}.{environment.com.br}/api/checkout/pub/orderForm/ede846222cd44046ba6c638442c3505a/attachments/paymentData

Additionally, you need to send the request body containing the following payment data information:

• paymentSysytem: payment system ID.
• paymentSystemName: payment system name.
• group: payment system group.
• installments: number of installments.
• installmentsInterestRate: installments interest rate.
• installmentsValue: value of each installment.
• value: total value assigned to this payment.
• referenceValue: reference value used to calculate total order value with interest.
• hasDefaultBillingAddress: indicates whether billing address for this payment is the default address.

See a request body example below:

{
     "payments": [
          {
               "paymentSysytem": 1,
               "paymentSystemName": "Boleto Bancário",
               "group": "bankInvoicePaymentGroup",
               "installments": 3,
               "installmentsInterestRate": 0,
               "installmentsValue": 100,
               "value": 300,
               "referenceValue": 300,
               "hasDefaultBillingAddress": false
          }
     ]
}

After sending the request, the endpoint will return the response body containing the payment data information in the shopping cart, as shown in the example below:

...
"paymentData": {
        "updateStatus": "updated",
        "installmentOptions": [
            {
                "paymentSystem": "1",
                "bin": null,
                "paymentName":  "Boleto Bancário",
                "paymentGroupName": "bankInvoicePaymentGroup",
                "value": 300,
                "installments": [
                    {
                        "count": 3,
                        "hasInterestRate": false,
                        "interestRate": 0,
                        "value": 300,
                        "total": 300,
                        "sellerMerchantInstallments": [
                            {
                                "id": "COSMETICS2",
                                "count": 3,
                                "hasInterestRate": false,
                                "interestRate": 0,
                                "value": 300,
                                "total": 300
                            }
                        ]
                    }
                ]
            }
...

️ For more information about the meaning of each of the fields available in the shopping cart, access the orderForm overview.

The following errors may appear as a message in the response body.

• Message error example (code ORD002): "Invalid order form". The orderFormId information is not valid.

{
    "fields": {},
    "error": {
        "code": "ORD002",
        "message": "Invalid order form",
        "exception": null
    },
    "operationId": "5d9f54e6-7db4-46d6-bca9-deeb278b8b98"
}

• Message error example (code ORD020): "Invalid payment". The referenceValue information has not been sent.

{
    "fields": {},
    "error": {
        "code": "ORD020",
        "message": "Invalid payment",
        "exception": null
    },
    "operationId": "9d14e7af-a63d-4c26-8974-bad734b758da"
}

• Message error example: "The requested URL was not found on the server": check that the URL data is correct.

<body>
	<h1>404 Not Found</h1>
	<p>The requested URL was not found on this server.</p>
</body>