Payments Brazil
Payments API enable businesses to accept payments from their customers via WhatsApp.
Pre-Requisites
- Your number must be a Brazilian WABA (WhatsApp Business Account).
- Your customer needs to have a Brazilian phone number to process the payment. Without it, the payment will be rejected by Meta due to an undeliverable message, as the message format is not supported.
Note
You must have a Meta Product Catalog linked to your WABA account.
Payments API Implementation Steps
Your customers begin by browsing and selecting products from your WhatsApp catalog. Once they finalize their order and submit it, their selection is sent to your system.
Next, you should provide them with an order summary, including details like items, quantities, prices, and the total amount. Along with this summary, share the payment information, such as a PIX code, boleto number, payment link, or a one-click payment option.
Sending the order_details message
The order_details message can be sent as either an interactive message or a template message. It may include a header, body, action, and footer, but only the body and action are required. The action section will contain the necessary order details that your customers need to complete their payment.
Requirements:
Information
You must provide a unique reference_id for each order to avoid duplicates and to allow accurate internal tracking of payment statuses.
If you plan to send multiple order_details messages for the same order or invoice, we recommend including a sequence number in the reference_id to ensure uniqueness.
- Currency must be set to BRL (Brazilian Real).
- The total_amount must be subtotal + tax + shipping - discount.
- The action component must be set to review_and_pay.
- Payment Settings: You must specify how you want to receive funds. Supported types in Brazil include:
- Pix: The fastest way to pay using dynamic code, your cusotmers will need to change to their bank app to use the Pix code to with the the payment process.
- Boleto: A standard Brazilian payment slip.
- Payment Links: A secure link that takes you to a payment page to complete the payment.
- One-click payments: Offsite card pay will be used.
Interactive order_details message examples
For interactive order_details message you can add two diferent payment methods in the same message, check the example below.
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"body": {
"text": "Your message content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "unique-reference-id",
"type": "digital-goods", //digital-goods or physical-goods
"payment_type": "br",
"payment_settings": [
{
"type": "pix_dynamic_code",
"pix_dynamic_code": {
"code": "00020101021226700014br.gov.bcb.pix2548pix.example.com...",
"merchant_name": "Account holder name",
"key": "39580525000189",
"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
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
]
}
]
}
}
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"body": {
"text": "Your message content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "unique-reference-id",
"type": "digital-goods",
"payment_type": "br",
"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": "optional text"
},
"items": [
{
"retailer_id": "1234567",
"name": "Cake",
"amount": {
"value": 50000,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 50000,
"offset": 100
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
]
}
]
}
}
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"body": {
"text": "Your message content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "unique-reference-id",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "payment_link",
"payment_link": {
"uri": "https://sandbox.juspay.io/v2/pay/start/test/mozsRnRYPs4ApqgYBmr?cardIssuerBankName%3DPIX_QR%26cardType%3DRTP%26paymentMethod%3DPIX_QR%26paymentMethodType%3DRTP"
}
}
],
"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
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
]
}
]
}
}
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "test_date_currency",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "button",
"sub_type": "order_details",
"index": 0,
"parameters": [
{
"type": "action",
"action": {
"order_details": {
"reference_id": "434",
"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
}
}
}
}
}
]
}
]
}
}
}
]
}
}
]
}
}
{
"messages": {
"msg": [
{
"RichContent": {
"conversation": [
{
"interactive": {
"type": "order_details",
"body": {
"text": "Your message content"
},
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "unique-reference-id",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "payment_link",
"payment_link": {
"uri": "https://sandbox.juspay.io/v2/pay/start/test/mozsRnRYPs4ApqgYBmr?cardIssuerBankName%3DPIX_QR%26cardType%3DRTP%26paymentMethod%3DPIX_QR%26paymentMethodType%3DRTP"
}
},
{
"type": "boleto",
"boleto": {
"digitable_line": "03399026944140000002628346101018898510000008848"
}
},
{
"type": "pix_dynamic_code",
"pix_dynamic_code": {
"code": "00020101021226700014br.gov.bcb.pix2548pix.example.com...",
"merchant_name": "Account holder name",
"key": "39580525000189",
"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
}
}
}
}
}
}
]
},
"allowedChannels": [
"WhatsApp"
],
"body": {
"content": "text"
},
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
]
}
]
}
}
Example of two payment methos in the same interactive message.
Template order_details
Creating an order_details template
Order details templates on WhatsApp allow businesses to share detailed order information with customers in an interactive and engaging format. These templates can be created either through WhatsApp Manager or via Template Creation APIs, depending on the business's preferred method. Below are step-by-step instructions for both approaches.
Information
Order details templates can be categorized as Utility or Marketing. Please follow the link before for the guidelines. Click here
Creating an Order Details Template on WhatsApp Manager
To create an order details template, businesses must have a business portfolio linked to a WhatsApp Business Account. Follow these steps in WhatsApp Manager under Account Tools:
- Create Template: Click on Create Template.
- Select Category: Choose either Utility or Marketing to access the Order Details template format option.
- Choose Template Format: Select the Order Details template format and click Next.
- Enter Template Name and Locale: Provide the desired template name and supported locale.
- For multiple locales, create corresponding template variants and complete the details for each locale.
- Fill Template Components: Add components such as Header, Body, and optional Footer text.
- For the Header, select one of three media types: Text, Image, or Document. Use Document to include PDF files in the header.
- Submit Template: Click Submit to finalize the template.
- Approval Process: Templates are categorized according to guidelines and undergo verification.
- Template Status: Once approved, the template status changes to ACTIVE.
Creating an Order Details Template Using Template Creation APIs
For businesses preferring to create templates programmatically, WhatsApp provides Template Creation APIs. These APIs allow businesses to design templates with the same components and guidelines as those created in WhatsApp Manager. Below is an overview of the process:
In addition to specifying the name and language, templates include general components such as HEADER, BODY, FOOTER, and a fixed BUTTON with the type ORDER_DETAILS.
Refer to the templates API documentation for detailed syntax, required categories, and component specifications. Ensure compliance with the guidelines outlined above for successful template creation and approval. API Template creation
POST https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
{
"name": "<TEMPLATE_NAME>",
"language": "<LANGUAGE_CODE>",
"category": "UTILITY or MARKETING",
"display_format": "ORDER_DETAILS",
"components": [
{
"type": "HEADER",
"format": "TEXT" OR "IMAGE" OR "DOCUMENT",
"text": "<HEADER_TEXT>"
},
{
"type": "BODY",
"text": "<BODY_TEXT>"
},
{
"type": "FOOTER",
"text": "<FOOTER_TEXT>"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "ORDER_DETAILS",
"text": "<COPY_PIX_CODE>"
}
]
}
]
}
Sending a order_details template example
The order details message template enhances the call-to-action button by incorporating interactive components, enabling the sharing of order details and offering a more engaging experience than text-only templates.
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "order_details_cart",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "button",
"sub_type": "order_details",
"index": 0,
"parameters": [
{
"type": "action",
"action": {
"order_details": {
"reference_id": "434",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "pix_dynamic_code",
"pix_dynamic_code": {
"code": "00020101021226700014br.gov.bcb.pix2548pix.example.com...",
"merchant_name": "Account holder name",
"key": "39580525000189",
"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
}
}
}
}
}
]
}
]
}
}
}
]
}
}
]
}
}
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "order_details_cart",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "button",
"sub_type": "order_details",
"index": 0,
"parameters": [
{
"type": "action",
"action": {
"order_details": {
"reference_id": "434",
"type": "digital-goods",
"payment_type": "br",
"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": "optional text"
},
"items": [
{
"retailer_id": "1234567",
"name": "Cake",
"amount": {
"value": 50000,
"offset": 100
},
"quantity": 1
}
],
"subtotal": {
"value": 50000,
"offset": 100
}
}
}
}
}
]
}
]
}
}
}
]
}
}
]
}
}
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "order_details_cart",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "button",
"sub_type": "order_details",
"index": 0,
"parameters": [
{
"type": "action",
"action": {
"order_details": {
"reference_id": "434",
"type": "digital-goods",
"payment_type": "br",
"payment_settings": [
{
"type": "payment_link",
"payment_link": {
"uri": "https://sandbox.juspay.io/v2/pay/start/test/mozsRnRYPs4ApqgYBmr?cardIssuerBankName%3DPIX_QR%26cardType%3DRTP%26paymentMethod%3DPIX_QR%26paymentMethodType%3DRTP"
}
}
],
"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
}
}
}
}
}
]
}
]
}
}
}
]
}
}
]
}
}
Once an order is created and paid by the customer you should send a message indicating to your customer that the order is in status processing with the order_status message.
Example of payment link template message
Sending the order_status message
The order_status messages are used to notify customers when businesses update the status of an order. These updates can be triggered either by changes in the WhatsApp payment status notification or through the business's internal processes.
- Supported Order Statuses:
- pending: The default state when the order is created.
- processing: Use this when you receive the payment from your customers.
- shipped / partially-shipped: Use this for physical goods in transit.
- completed: The final state once the service is rendered or the item is delivered.
- canceled: Only available if the payment hasn't been captured yet.
- Supported Payment Statuses:
- pending: Payment is pending.
- captured: This automatically adds a "Paid" label with a green checkmark to the customer’s order bubble.
- failed: Notifies the customer the transaction did not go through.
Updating Payment Status
When your system receives a payment notification (via your payment provider or webhook), you should send an order_status update with the payment field.
Best practices
To manage time-sensitive offers or stock availability, utilize the expiration object. Once the expiration time is reached, the "Pay" button will automatically be disabled for the user, ensuring accurate and timely transactions.
For Body Text, leverage markdown formatting in the body text to emphasize critical information. For example:
“Please complete your Pix payment within 15 minutes.”
Interactive order_status message example
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"reference": "231593197",
"richContent": {
"conversation": [
{
"interactive": {
"type": "order_status",
"body": {
"text": "your-mandatory-text-body-content"
},
"footer": {
"text": "your-optional-text-footer-content"
},
"action": {
"name": "review_order",
"parameters": {
"reference_id": "unique-reference-id",
"order": {
"status": "processing"
},
"payment": {
"status": "captured",
"timestamp": 1722445231
}
}
}
}
}
]
}
}
]
}
}
Updated about 15 hours ago