Adding payment information to the cart

The shopping cart gathers information on the products the customer chooses while browsing a store, such as prices, shipping costs, payment methods, delivery methods, etc. This data may include item prices, shipping value, payment, and delivery methods, among others.

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

The payment information attached to the shopping cart does not determine the final order payment method. However, it allows the platform to update any relevant information that might be affected by the payment method.

Getting shopping cart information

The first step is to get the orderFormId of the shopping cart to which you want to add the payment information. For more information, read the Getting cart information by ID guide.

Adding payment information to the shopping cart

To add payment information 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 in the example below:

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

Additionally, you must send the request body containing the following payment information:

paymentSystem: Payment system ID.
paymentSystemName: Payment system name.
group: Payment system group.
installments: Number of installments.
installmentsInterestRate: Installment interest rate.
installmentsValue: Amount of each installment.
value: Total payment amount.
referenceValue: Base value used to calculate total order amount with interest.
hasDefaultBillingAddress: Indicates whether the billing address for this order is the default address.

See a request body example below:


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

If you are using a gift card as a payment method, the request body can be similar to this:


_16{
_16     "giftCards": [
_16          {
_16            "redemptionCode": "480030010012333619",
_16            "provider": "CartaoPresente",
_16            "value": 15289,
_16            "balance": 100000,
_16            "name": null,
_16            "caption": null,
_16            "id": "480030010012333619",
_16            "inUse": true,
_16            "isSpecialCard": false,
_16            "groupName": null
_16        }
_16     ]
_16}

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


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

️ For more information on the meaning of each field available in the shopping cart, see the orderForm overview.

Error codes

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

400 - Bad Request

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


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

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


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

404 - Not Found

Message error example: "The requested URL was not found on the server": Check if the URL is correct.


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