Payments API - Brazil
Payments API enable businesses to accept payments from their customers via WhatsApp. Businesses send order_details messages [Orders API] to their customers, then get notified about payment status updates via webhook notifications.
Based on the selected usecase, businesses can collect payment from the customers using one of the following integrations:
- [Dynamic Pix Codes]
- [Payment Links]
- [Boleto]
- [One-click offsite card payment]
- [Order Details Template]
How It Works
First, the business composes and sends an order_details message, which is a new type of interactive message. It contains the same 4 main components: header, body, footer, and action. Inside the action component, the business includes all the information needed for the customer to complete their payment.
Each order_details message must contain a unique reference_id provided by the business. This reference id is used throughout the flow to track the order.
Once the message is sent, the business waits for a payment or transaction status update. The type of the update depends on the integration type (e.g.: [Pix], [Payment Links], etc.). WhatsApp does NOT support payment reconciliations. The business must reconcile the payment with their payment service provider (PSP) using the reference_id of the order.
Sending order messages
Both message types contain the same 4 main components of an interactive message: header, body, footer, and action. The parameters in the action component will vary based on the message type.
Remember to set the type to interactive.
| Field Name |
Optional? |
Type |
Description |
| type |
Required |
String |
Must be order_details. |
| header |
Optional |
Object |
Thumbnail image for order details message. It has the following fields:type: Must be image.image: See [Image Object]If the header is not present, Biz-API finds the first product with an image and uses that for the thumbnail image. |
| body |
Required |
Object |
An object with the body of the message. The object contains the following field:text string: The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters. |
| footer |
Optional |
Object |
An object with the footer of the message. The object contains the following field:text string: Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters. |
| action |
Required |
Action Object |
See [Action Object] below. |
Image Object
| Field Name |
Optional? |
Type |
Description |
| link |
Required |
String |
Url of the image. |
| provider |
Optional |
String |
Name of the url provider. |
Action Object
| Field Name |
Optional? |
Type |
Description |
| name |
Required |
String |
Must be review_and_pay. |
| parameters |
Required |
Parameters Object |
See [Parameters Object]. |
Parameters Object
| Field Name |
Optional? |
Type |
Description |
| reference_id |
Required |
String |
Unique identifier for the order or invoice provided by the business. This cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters.The reference_id must be unique for each order_details message for the same business. If the partner would like to send multiple order_details messages for the same order, invoice, etc. it is recommended to include a sequence number in the reference_id to ensure reference_id uniqueness. |
| type |
Required |
String |
Must be one of digital-goods or physical-goods. |
| payment_type |
Required |
String |
Must be br. |
| payment_settings |
Optional |
[Payment Settings Object] |
List of payment related configuration objects. |
| currency |
Required |
String |
ISO 4217 currency code for the order. Must be BRL (Brazilian Real). |
| total_amount |
Required |
Amount Object |
See [Amount Object].total_amount.value must be equal to order.subtotal.value + order.tax.value + order.shipping.value - order.discount.value |
| order |
Required |
Order Object |
See [Order Object]. |
Payment Settings
| Field Name |
Optional? |
Type |
Description |
type |
Required |
String |
One of pix_dynamic_code, payment_link, boleto,offsite_card_pay |
One of the following objects: pix_dynamic_code, payment_link, boleto,offsite_card_pay |
Required |
Object |
Payment instructions which will be displayed to buyers during the checkout process. |
Order Object
| Field Name |
Optional? |
Type |
Description |
| status |
Required |
String |
Status of the order. Only supported value here is pending. |
| catalog_id |
Optional |
String |
Unique identifier of the Facebook catalog being used by the business. |
| expiration |
Optional |
Expiration Object |
Expiration for that order. The CTA for payment will be disabled after expiry on the user end. See [Expiration Object]. |
| items |
Required |
List of Item Objects |
List must have at least one item. See [Item Object]. |
| subtotal |
Required |
Amount Object |
See [Amount Object].The value must be equal to sum of (item.amount.value or item.sale_amount.value) * item.quantity.The following fields are part of the subtotal object:offset string Required. Must be 100 for BRL.value string Required. Positive integer representing the amount value multiplied by offset. For example, S$12.34. has value 1234 |
| tax |
Required |
Amount With Description Object |
The tax information for this order. Even though the object is required, the amount can be zero. When zero is used, the tax line is not rendered in the client. See [Amount With Description Object] |
| shipping |
Optional |
Amount With Description Object |
See [Amount Object]. |
| discount |
Optional |
Discount Object |
The discount for the order. See [Discount object]. |
Expiration Object
| Field Name |
Optional? |
Type |
Description |
| timestamp |
Required |
String |
UTC time in seconds. Minimum threshold is 300 seconds. |
| description |
Required |
String |
Text explanation for when the order will expire. Max character limit is 120 characters. |
Item Object
| Field Name |
Optional? |
Type |
Description |
| retailer_id |
Required |
String |
Content ID for an item in the order from your catalog. |
| name |
Required |
String |
The item’s name to be displayed to the user. Cannot exceed 60 characters. |
| amount |
Required |
Amount Object |
The price per item. See [Amount Object]. |
| quantity |
Required |
Integer |
Number of items in this order. |
| sale_amount |
Optional |
Amount Object |
The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount. See [Amount Object]. |
Discount Object
| Field Name |
Optional? |
Type |
Description |
| value |
Required |
Integer |
Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234. |
| offset |
Required |
Integer |
Must be 100 for BRL. |
| description |
Optional |
String |
Max character limit is 60 characters. |
| discount_program_name |
Optional |
String |
Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. |
Amount Object
| Field Name |
Optional? |
Type |
Description |
| value |
Required |
Integer |
Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234. |
| offset |
Required |
Integer |
Must be 100 for BRL. |
Amount Object (With Description)
| Field Name |
Optional? |
Type |
Description |
| value |
Required |
Integer |
Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234. |
| offset |
Required |
Integer |
Must be 100 for BRL. |
| description |
Optional |
String |
Max character limit is 60 characters. |
Dynamic Pix Codes
If Pix is available on this order, you will need to provide a pix_dynamic_code to the payment_settings attribute.
Pararmeters Object
| Field Name |
Optional? |
Type |
Description |
payment_settings |
Optional |
[Payment Settings Object] |
List of payment related configuration objects. |
Payment Settings
| Field Name |
Optional? |
Type |
Description |
type |
Required |
String |
Must be pix_dynamic_code. |
pix_dynamic_code |
Required |
[Dynamic Pix Object] |
Dynamic Pix Code object that will be used to render the option to buyers during the checkout flow. |
Dynamic Pix Code Object
| Field Name |
Optional? |
Type |
Description |
code |
Required |
String |
The dynamic Pix code which will be copied by the buyer. |
merchant_name |
Required |
String |
Account holder name. Displayed in-app for the buyer for informational purposes. |
key |
Required |
String |
Pix key. Displayed in-app for the buyer for informational purposes. |
key_type |
Required |
String |
Pix key type. One of CPF, CNPJ, EMAIL, PHONE or EVP. |
eg
{
"appkey": "xxx",
"business_phone": "xxx",
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "xxx",
"type": "interactive",
"interactive": {
"type": "order_details",
"body": {
"text": "pay now pix"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "0d014eb497214359817181f51093737eec",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "pix_dynamic_code",
"pix_dynamic_code": {
"code": "xxx20101021226700014br.gov.bcb.pix2548pix.example.com...",
"merchant_name": "Account holder name",
"key": "xxx525000189",
"key_type": "CNPJ"
}
}
],
"currency": "BRL",
"total_amount": {
"value": 50000,
"offset": 100
},
"order": {
"status": "pending",
"tax": {
"value": 0,
"offset": 100,
"description": "optional text"
},
"items": [
{
"retailer_id": "1234567",
"name": "Cake",
"amount": {
"value": 50000,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 50000,
"offset": 100
}
}
}
}
}
}
Payment Links
If Payment Link payment is available on this order, you will need to provide a payment_link to the payment_settings attribute.
Pararmeters Object
| Field Name |
Optional? |
Type |
Description |
payment_settings |
Optional |
[Payment Settings Object] |
List of payment related configuration objects. |
Payment Settings
| Field Name |
Optional? |
Type |
Description |
type |
Required |
String |
Must be payment_link. |
payment_link |
Required |
[Payment Link Object] |
Payment Link object that will be used to render the option to buyers during the checkout flow. |
Payment Link Object
| Field Name |
Optional? |
Type |
Description |
uri |
Required |
String |
The Payment Link's uri which will be opened in the web browser, when user taps on the Payment Link CTA button. |
eg
{
"appkey": "xxx",
"business_phone": "xxx",
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "xxx",
"type": "interactive",
"interactive": {
"type": "order_details",
"body": {
"text": "Pay now link"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "0d014eb497214359817181f51093737c",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "payment_link",
"payment_link": {
"uri": "https://my-payment-link-url"
}
}
],
"currency": "BRL",
"total_amount": {
"value": 50000,
"offset": 100
},
"order": {
"status": "pending",
"tax": {
"value": 0,
"offset": 100,
"description": "optional text"
},
"items": [
{
"retailer_id": "1234567",
"name": "Cake",
"amount": {
"value": 50000,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 50000,
"offset": 100
}
}
}
}
}
}
Boleto
If Boleto payment is available on this order, you will need to provide a boleto object in the payment_settings attribute.
Pararmeters Object
| Field Name |
Optional? |
Type |
Description |
payment_settings |
Optional |
[Payment Settings Object] |
List of payment related configuration objects. |
Payment Settings
| Field Name |
Optional? |
Type |
Description |
type |
Required |
String |
Must be boleto. |
boleto |
Required |
[Boleto Object] |
Boleto object that will be used to render the option to buyers during the checkout flow. |
Boleto Object
| Field Name |
Optional? |
Type |
Description |
digitable_line |
Required |
String |
The Boleto digitable line / code which will be copied to the clipboard, when user taps on the Boleto CTA button. |
eg
{
"appkey": "xxx",
"business_phone": "xxx",
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "xxx",
"type": "interactive",
"interactive": {
"type": "order_details",
"body": {
"text": "Pay now Boleto"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "0d014eb497214359817181f51093737ckk",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "boleto",
"boleto": {
"digitable_line": "xxx6944140000002628346101018898510000008848"
}
}
],
"currency": "BRL",
"total_amount": {
"value": 50000,
"offset": 100
},
"order": {
"status": "pending",
"tax": {
"value": 0,
"offset": 100,
"description": "optional text"
},
"items": [
{
"retailer_id": "1234567",
"name": "Cake",
"amount": {
"value": 50000,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 50000,
"offset": 100
}
}
}
}
}
}
One-click offsite card payment
If One-Click Payments is available on this order, you will need to provide a offsite_card_pay object in the payment_settings attribute.
Pararmeters Object
| Field Name |
Optional? |
Type |
Description |
payment_settings |
Optional |
[Payment Settings Object] |
List of payment related configuration objects. |
Payment Settings
| Field Name |
Optional? |
Type |
Description |
type |
Required |
String |
Must be offsite_card_pay. |
offsite_card_pay |
Required |
[Offsite Card Pay Object] |
Offsite Card Pay object that will be used to render the option to buyers during the checkout flow. |
Offsite Card Pay Object
| Field Name |
Optional? |
Type |
Description |
last_four_digits |
Required |
String |
The last four digits of the card, which will be displayed to the user for confirmation before they accept the payment (by tapping the "Send payment" CTA button). |
credential_id |
Required |
String |
The ID of the credential associated with the card. After the user taps the "Send Payment" CTA button, the merchant will receive a webhook from Meta notifying that confirmation from the user. The payload of that webhook will contain this credential_id, which the merchant will use to determine the card or credential for payments. |
eg
{
"appkey": "xxx",
"business_phone": "xxx",
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "xxx",
"type": "interactive",
"interactive": {
"type": "order_details",
"body": {
"text": "Pay one-click"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "0d014eb497214359817181f5109",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "offsite_card_pay",
"offsite_card_pay": {
"last_four_digits": "5235",
"credential_id": "1234567"
}
}
],
"currency": "BRL",
"total_amount": {
"value": 50000,
"offset": 100
},
"order": {
"status": "pending",
"tax": {
"value": 0,
"offset": 100,
"description": "optional text"
},
"items": [
{
"retailer_id": "1234567",
"name": "Cake",
"amount": {
"value": 50000,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 50000,
"offset": 100
}
}
}
}
}
}
Order Status
To send an order_status message, businesses must assemble an interactive object of type order_details with the following components:
Interactive Object
| Field Name |
Optional? |
Type |
Description |
| type |
Required |
String |
Must be order_status. |
| header |
Optional |
Object |
Optional object for the message's header for the message. |
| body |
Required |
Object |
An object with the body of the message. The object contains the following field:text string: The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters. |
| footer |
Optional |
Object |
An object with the footer of the message. The object contains the following field:text string: Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters. |
| action |
Required |
Action Object |
See [Action Object] below. |
Action Object
| Field Name |
Optional? |
Type |
Description |
| name |
Required |
String |
Must be review_order. |
| parameters |
Required |
Parameters Object |
See [Parameters Object]. |
Parameters Object
| Field Name |
Optional? |
Type |
Description |
| reference_id |
Required |
String |
The unique ID provided in the order_details message. |
| order |
Required |
Order Object |
See [Order Object]. |
| payment |
Optional |
Payment Object |
See [Payment Object]. |
Order Object
| Field Name |
Optional? |
Type |
Description |
| status |
Required |
String |
The new order status. [See supported order status]. |
| description |
Optional |
String |
Optional text for sharing status related information in order-details page. Could be useful while sending cancellation. Length should not exceed 120 characters. |
Payment Object
| Field Name |
Optional? |
Type |
Description |
| status |
Required |
String |
The new payment status. [See supported payment status]. |
| timestamp |
Optional |
Integer |
Optional epoch timestamp in seconds |
Supported Order Status
Currently we support the following order status values:
| Value |
Description |
pending |
Order is pending / not processed yet. |
processing |
Merchant/partner is fulfilling the order, performing service, etc. |
partially-shipped |
Part of the products in order have been shipped by the merchant. |
shipped |
All the products in order have been shipped by the merchant. |
completed |
The order is completed and no further action is expected from the user or the partner/merchant. |
canceled |
The parner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message. |
Supported Payment Status
Currently we support the following payment status values:
| Value |
Description |
pending |
Payment is pending. |
captured |
Payment was successfully captured. Receiving this payment status will update the order bubble to include the "paid" label (with green checkmark). |
failed |
Payment failed. |
eg
{
"appkey": "xxx",
"business_phone": "xxx",
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "xxx",
"type": "interactive",
"interactive": {
"type": "order_status",
"body": {
"text": "order thing"
},
"footer": {
"text": "pick up"
},
"action": {
"name": "review_order",
"parameters": {
"reference_id": "0d014eb497214359817181f51093737c",
"order": {
"status": "processing"
},
"payment": {
"status": "captured",
"timestamp": 1752809289
}
}
}
}
}
Order Details Template
create template
{
"appkey": "xxx",
"messaging_product": "whatsapp",
"business_phone": "xxx",
"category": "MARKETING",
"name": "order_status_new",
"language": "pt_BR",
"display_format": "ORDER_DETAILS",
"components": [
{
"format": "TEXT",
"type": "HEADER",
"text": "Header text"
},
{
"text": "Hello.this is you order.pleast check and pay.",
"type": "BODY"
},
{
"text": "check&pay",
"type": "FOOTER"
},
{
"buttons": [
{
"text": "Copy Pix code",
"type": "ORDER_DETAILS"
}
],
"type": "BUTTONS"
}
]
}