Order details and payment

Last update: 6 hours ago by Irais Aguirre

Integration summary
Endpoint: POST https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging
Token: messaging token, in the Authorization: Bearer {{wa-msg-api-token}} header (how to generate it)
Common fields: from, to (phone number or BSUID) and type (details)
type values on this page: "interactive"
Response: the same for every message (see response)

Interactive order details message (order_details) with one or more payment methods for customers in Brazil. All amounts are in Brazilian reais (BRL). All are sent with POST /v1/messaging; headers (Headers), common fields and the response (Response) are in HTTP connection.

Order details

Sends the details of an order and requests payment. The type field must be "interactive" and the content goes in the order_details object with the "review_and_pay" action. Examples for each payment method are in the following sections.

Body

Fields for Order details:

Name	Description	Type	Requirements
from	Phone number (with country code) the message is sent from.	String	Required
to	Recipient's phone number in E.164 format, without the + sign. You can also use the user's BSUID, for example, US.13491208655302741918.	String	Required
type	Message type. Must be "interactive".	String	Required
order_details	Object with the message content and payment details.	Object	Required

Order details object

Name	Description	Type	Requirements
body	Main text of the message.	String	Required
footer	Footer text of the message.	String	Optional
headerImage	Optional image header (`link` or `id`).	Object	Optional
action	Object with the action and its parameters.	Object	Required

Action object

Name	Description	Type	Requirements
name	Action name. Must be "review_and_pay".	String	Required
parameters	Object with the order and payment data.	Object	Required

Parameters object

Name	Description	Type	Requirements
reference_id	Unique order ID. Only English letters, numbers, hyphens, underscores, and periods are allowed.	String	Required
payment_type	Must be "br". This section documents the Brazil-specific payment flow only; other `payment_type` values belong to a separate global payments API that is not documented here.	String	Required
type	Type of goods. Possible values: digital-goods physical-goods	String	Required
payment_settings	List of payment methods. Accepts one or more methods.	Array	Required
currency	Payment currency. Must be "BRL".	String	Required
total_amount.value	Total amount as an integer.	Long	Required
total_amount.offset	Must be 100.	Integer	Required
order	Order breakdown (status, tax, items, and subtotal). Omitted in the simplified payload.	Object	Optional

Note: supported_payment_methods belongs to the separate global payments API and is not valid in this Brazil flow (payment_type=br). This service does not block the combination; Meta rejects it upstream and returns the corresponding Graph API error, which is surfaced back to the caller.

Order object

Name	Description	Type	Requirements
status	Order status. Values: pending, processing, partially_shipped, shipped, completed, canceled.	String	Required when `order` is sent
catalog_id	Catalog identifier.	String	Optional
expiration	Object `{ timestamp, description }`.	Object	Optional
items	List of order items.	List of objects	Required when `order` is sent
subtotal	`amount` object for the subtotal. `value` must be > 0.	Object	Required when `order` is sent
tax	`amount` object for tax.	Object	Optional
shipping	`amount` object for shipping.	Object	Optional
discount	`amount` object for discount.	Object	Optional

items[] object

Name	Description	Type	Requirements
name	Item name.	String	Required
amount	`amount` object for the item. `amount.value` > 0.	Object	Required
quantity	Item quantity.	Integer	Optional
retailer_id	Retailer item identifier.	String	Optional
catalog_id	Catalog identifier.	String	Optional
sale_amount	`amount` object with the sale price.	Object	Optional

amount object

Name	Description	Type	Requirements
value	Amount as integer.	Long	Required (> 0)
offset	Scale factor. Must be 100 when `payment_type` is `br`.	Integer	Required

Payment settings object

Name	Description	Type	Requirements
type	Payment method. Possible values: payment_link: Payment link. pix_dynamic_code: PIX dynamic code. boleto: Boleto.	String	Required
payment_link	Object with the Payment link data.	Object	Required if type is payment_link
pix_dynamic_code	Object with the PIX dynamic code data.	Object	Required if type is pix_dynamic_code
boleto	Object with the Boleto data.	Object	Required if type is boleto

Payment link object

Name	Description	Type	Requirements
uri	URL that opens in the browser when the button is tapped. Must use the https scheme.	String	Required

Pix dynamic code object

Name	Description	Type	Requirements
code	PIX dynamic code the buyer copies to make the payment.	String	Required
merchant_name	Name of the PIX account holder.	String	Required
key	Merchant's PIX key.	String	Required
key_type	Key type. Possible values: CPF CNPJ EMAIL PHONE EVP	String	Required

Boleto object

Name	Description	Type	Requirements
digitable_line	Digitable line the buyer copies to pay at their bank.	String	Required

Payment link

Shows a button that opens the merchant's payment page in the browser.

Example

Complete Payment link example:

HTTP request with full payload

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "footer": "Pagamento seguro",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "link-br-full-001",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "payment_link",
                        "payment_link": { "uri": "https://minhaloja.com.br/pagar/001" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 },
                "order": {
                    "status": "pending",
                    "tax": { "value": 0, "offset": 100, "description": "Imposto" },
                    "items": [
                        {
                            "retailer_id": "SKU-001",
                            "name": "Bolo de chocolate",
                            "amount": { "value": 50000, "offset": 100 },
                            "quantity": 1
                        }
                    ],
                    "subtotal": { "value": 50000, "offset": 100 }
                }
            }
        }
    }
}'

HTTP request with simplified payload

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "link-br-simple-002",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "payment_link",
                        "payment_link": { "uri": "https://minhaloja.com.br/pagar/001" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 }
            }
        }
    }
}'

PIX dynamic code

Shows a button the buyer uses to copy the PIX code and pay from their banking app.

Example

Complete PIX dynamic code example:

HTTP request with full payload

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "footer": "Pagamento seguro",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "pix-full-001",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "pix_dynamic_code",
                        "pix_dynamic_code": {
                            "code": "00020101021226700014br.gov.bcb.pix2548pix.example.com",
                            "merchant_name": "Minha Loja",
                            "key": "39580525000189",
                            "key_type": "CNPJ"
                        }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 },
                "order": {
                    "status": "pending",
                    "tax": { "value": 0, "offset": 100, "description": "Imposto" },
                    "items": [
                        {
                            "retailer_id": "SKU-001",
                            "name": "Bolo de chocolate",
                            "amount": { "value": 50000, "offset": 100 },
                            "quantity": 1
                        }
                    ],
                    "subtotal": { "value": 50000, "offset": 100 }
                }
            }
        }
    }
}'

HTTP request with simplified payload

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "pix-simple-002",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "pix_dynamic_code",
                        "pix_dynamic_code": {
                            "code": "00020101021226700014br.gov.bcb.pix2548pix.example.com",
                            "merchant_name": "Minha Loja",
                            "key": "39580525000189",
                            "key_type": "CNPJ"
                        }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 }
            }
        }
    }
}'

Boleto

Shows a button the buyer uses to copy the boleto's digitable line and pay it at their bank.

Example

Complete Boleto example:

HTTP request with full payload

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "footer": "Pagamento seguro",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "boleto-br-full-001",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "boleto",
                        "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 },
                "order": {
                    "status": "pending",
                    "tax": { "value": 0, "offset": 100, "description": "Imposto" },
                    "items": [
                        {
                            "retailer_id": "SKU-001",
                            "name": "Bolo de chocolate",
                            "amount": { "value": 50000, "offset": 100 },
                            "quantity": 1
                        }
                    ],
                    "subtotal": { "value": 50000, "offset": 100 }
                }
            }
        }
    }
}'

HTTP request with simplified payload

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "boleto-br-simple-002",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "boleto",
                        "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 }
            }
        }
    }
}'

Multiple payment methods

A single message can offer PIX, Payment link, and Boleto at the same time, along with buttons for websites and phone contact.

Example

Complete Multiple payment methods example:

HTTP request with PIX, Payment link, and Boleto

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "multi-br-001",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "pix_dynamic_code",
                        "pix_dynamic_code": {
                            "code": "00020101021226700014br.gov.bcb.pix2548pix.example.com",
                            "merchant_name": "Minha Loja",
                            "key": "39580525000189",
                            "key_type": "CNPJ"
                        }
                    },
                    {
                        "type": "payment_link",
                        "payment_link": { "uri": "https://minhaloja.com.br/pagar/001" }
                    },
                    {
                        "type": "boleto",
                        "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 }
            }
        }
    }
}'