How to use Payments API

This document has a Portuguese version.

Pre-requisites

• Your number must be a Brazilian WABA (WhatsApp Business Account).

• Your WABA must be onboarded via 360Dialog.

• You must have:

  • A payment gateway already implemented (to generate PIX).

  • A bot integrated with WhatsApp (to manage conversations).

  • Your API key and webhook properly set up.

Steps to implement

The steps below work with an open conversation window. To initiate a conversation, please, check other examples below.

We'll illustrate how to use PIX as a payment method, but it's important to remember that you can also use another payment method (boleto, payment link, one-click payment).

1

Send a product catalog

When end-user is ready for product selection, send a message with product catalog. Endpoint: https://waba-v2.360dialog.io/messages

Example:

**************Send PRODUCT CATALOGUE***************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "{RECIPIENT_USER_PHONE_NO_HERE}",
    "type": "interactive",
    "interactive": {
        "type": "list",
        "header": {
            "type": "text",
            "text": "Obrigado por participar desta DEMO"
        },
        "body": {
            "text": "O objetivo é demonstrar como integrar pagamentos no Brasil usando PIX como Gateway de Pagamento"
        },
        "footer": {
            "text": ""
        },
        "action": {
            "button": "Buy an Item",
            "sections": [
                {
                    "title": "Items",
                    "rows": [
                        {
                            "id": "item-chocolate-10",
                            "title": "Chocolate (R$ 10)",
                            "description": "Chocolate Ao Leite Recheio Oreo Lacta Pacote 90g"
                        },
                        {
                            "id": "item-coffee-20",
                            "title": "Café (R$ 20)",
                            "description": "Café Torrado E Moído A Vácuo 3 Corações Gourmet Pacote 250g"
                        }
                    ]
                }
            ]
        }
    }
}

2

Generate and send the payment details with order details

Once the user selects a product and places the order, send the product summary along with payment details containing a PIX Code, boleto number, payment link or one-click payment details.

1. The business (client or partner) can generate the PIX (check at the next section of this page) or payment details internally at their end using their payment gateway implementation, and use the information directly in the message API, so it reaches the end user.

2. The client/partner is free to have their own order statuses as per their internal order management system and use the same in order details message. For example, once the user places the order, you can maintain order in pending or confirmed, or any state that is applicable to your internal systems.

3. The user will see a WhatsApp message with order info and a PIX code to copy or display the other payment details.

Payments API Brazil: Payment option PIX

Make sure to use a unique reference_id for each order_details message.

This ID should be consistent across the PIX code or payment details generation and the WhatsApp message 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.

• For complete implementation details, please refer to the official Meta documentation.

Example:

PIX

**************Send PRODUCT DETAILS with DYNAMIC PIX PAYMENT CODE***************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "{RECIPIENT_USER_PHONE_NO_HERE}",
    "type": "interactive",
    "interactive": {
        "type": "order_details",
        "body": {
            "text": "Detalhes do seu pedido"
        },
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "r123456789",
                "type": "digital-goods",
                "payment_type": "br",
           
                "payment_settings": [
                    {
                        "type": "pix_dynamic_code",
                        "pix_dynamic_code": {
                            "code": "{YOUR_DYNAMIC_PIX_CODE_HERE}",
                            "merchant_name": "Account holder name",
                            "key": "50561267000126",
                            "key_type": "CNPJ"
                        }
                    }
                ],
                "currency": "BRL",
                "total_amount": {
                    "value": 1000,
                    "offset": 100
                },
                "order": {
                    "status": "pending",
                    "tax": {
                        "value": 0,
                        "offset": 100,
                        "description": "imposto"
                    },
                    "items": [
                        {
                            "retailer_id": "1234567",
                            "name": "Chocolate (R$ 10)",
                            "amount": {
                                "value": 1000,
                                "offset": 100
                            },
                            "quantity": 1
                        }
                    ],
                    "subtotal": {
                        "value": 1000,
                        "offset": 100
                    }
                }
            }
        }
    }
}

Boleto

Payment link

One-click payment

3

User completes payment

Now user can copy the PIX code, or boleto's payment number and navigate outside Whatsapp to their payment app and complete the payment

Please note that META does not have a way to track this payment status currently as the payment is happening on different bank apps and the payment gateway account is linked to the client/partner internal systems.

4

Update the user with order status

• Once the end user attempts payment, you will receive the payment status update from your payment gateway

• Basis the payment status received, you can update the status of the order in your order management system

• Once the payment status is received from the payment gateway and internal order management steps/status updates are completed, you can send an update to the user using an order_status message:

**************Send ORDER STATUS***************************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": ""{RECIPIENT_USER_PHONE_NO_HERE}"",
    "type": "interactive",
    "interactive": {
        "type": "order_status",
        "body": {
            "text": "Detalhes do seu pedido"
        },
        "footer" : {
            "text": "Reference: 123456789"
        },
        "action": {
            "name": "review_order",
            "parameters": {
                "reference_id": "123456789",
                "order": {
                    "status": "{ORDER_STATUS_HERE}"
                }
            }
        }
    }
}

You can send updates as often as needed, based on your internal order workflow.

PIX Payments

Sending PIX without open conversation (using templates)

If you need to send the PIX code directly to the end-user number without an open conversation window, it is also possible, but keep in mind that you will need to create a template and add the order_details message within the template.

1. Create a UTILITY or MARKETING template either via API or via WhatsApp Manager.

   1. To create via API, please read this documentation.

2. Use the pre-created order_details version.

3. Enter the desired template name.

4. Please fill in template components such as Header, Body and optional footer text and submit.

5. Once submitted, templates will be categorized as per the guidelines and undergo the approval process, please refrain from having marketing content as part of template components.

6. The template will be approved or rejected after the template components are verified by the system.

7. Once approved template status will be changed to ACTIVE.

Please be informed that template's status can change automatically from ACTIVE to PAUSED or DISABLED based on customer feedback. We recommend that you monitor status changes and take appropriate actions whenever such change occurs.

After that, you can send the template message including the order_details information with the PIX code. For all the details, please verify the official documentation here.

Example: sending order details with dynamic PIX payment code

**************Send ORDER DETAILS with DYNAMIC PIX PAYMENT CODE***************************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<end_user_number>",
  "type": "template",
  "template": {
    "name": "<template_name>",
    "language": {
      "policy": "deterministic",
      "code": "<template_language>"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "order_details",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "order_details": {
                "reference_id": "unique-reference-id",
                "type": "digital-goods",
                "payment_type": "br",
                "payment_settings": [
                  {
                    "type": "pix_dynamic_code",
                    "pix_dynamic_code": {
                      "code": "<pix_code_here>",
                      "merchant_name": "<company_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
                  }
                }
              }
            }
          }
        ]
      }
    ]
  }
}

Generating a static Pix code

As you observed above, you must configure a payment setting that includes your Pix code. If you are unsure how to generate a static Pix code to implement in your solution, we used a public GitHub repository to obtain one. For more information, you can access the repository here.

Postman collection

We built a Postman collection that you can use to test the requests, replacing the current variables with their corresponding values from your business. Please, download it below and import it into your collection:

9KB

Native Payment - PIX.postman_collection.json

Open

Postman collection

---

Portuguese version

Pré-requisitos

• Seu número deve ser um WABA brasileiro (Conta Comercial do WhatsApp).

• Sua WABA deve estar integrada via 360Dialog.

• Você deve ter:

  • Um gateway de pagamento já implementado (para gerar PIX).

  • Um bot integrado ao WhatsApp (para gerenciar as conversas).

  • Sua chave de API e webhook devidamente configurados.

Etapas para implementar

As etapas abaixo funcionam com uma janela de conversa aberta. Para iniciar uma conversa, verifique outros exemplos mais abaixo.

Vamos exemplificar utilizando o PIX como meio de pagamento, mas é importante lembrar que você pode utilizar outra forma de pagamento também (boleto, link de pagamento, pagamento um-clique).

1

Enviando um catálogo de produtos

Quando o usuário final estiver pronto para escolher produtos, envie uma mensagem com o catálogo de produtos.

Endpoint: https://waba-v2.360dialog.io/messages

Exemplo:

**************ENVIAR CATÁLOGO DE PRODUTOS***************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "{RECIPIENT_USER_PHONE_NO_HERE}",
    "type": "interactive",
    "interactive": {
        "type": "list",
        "header": {
            "type": "text",
            "text": "Obrigado por participar desta DEMO"
        },
        "body": {
            "text": "O objetivo é demonstrar como integrar pagamentos no Brasil usando PIX como Gateway de Pagamento"
        },
        "footer": {
            "text": ""
        },
        "action": {
            "button": "Buy an Item",
            "sections": [
                {
                    "title": "Items",
                    "rows": [
                        {
                            "id": "item-chocolate-10",
                            "title": "Chocolate (R$ 10)",
                            "description": "Chocolate Ao Leite Recheio Oreo Lacta Pacote 90g"
                        },
                        {
                            "id": "item-coffee-20",
                            "title": "Café (R$ 20)",
                            "description": "Café Torrado E Moído A Vácuo 3 Corações Gourmet Pacote 250g"
                        }
                    ]
                }
            ]
        }
    }
}

2

Gerando e enviando os detalhes de pagamento com os detalhes do pedido

Depois que o usuário escolher um produto e fizer o pedido, envie um resumo com os detalhes e o código PIX, código de barras, link de pagamento ou detalhes do pagamento em um-clique.

1. O negócio (cliente ou parceiro) pode gerar o PIX (veja a próxima seção desta página), ou detalhes de pagamento internamente usando sua própria implementação de gateway de pagamento, e usar essas informações diretamente na API de mensagens para que chegue ao usuário final.

2. O cliente/parceiro pode ter seus próprios status de pedido, conforme seu sistema interno de gestão. Por exemplo, após o pedido, o status pode ser "pendente", "confirmado" ou outro.

3. O usuário verá uma mensagem de WhatsApp message com as informações do pedido e o Pix para copiar ou os detalhes de pagamento do método escolhido.

Payments API Brazil: Payment option PIX

Garanta o uso de um reference_id para cada order_details mensagem.

Esse ID deve ser o mesmo na geração do código PIX (ou detalhes de pagamento) e na mensagem do WhatsApp, para permitir o rastreamento correto do status do pagamento.

• Se você for enviar várias mensagens order_details para o mesmo pedido, recomenda-se incluir um número sequencial no reference_id.

• Para detalhes completos da implementação, consulte a documentação do Meta.

Exemplo:

PIX

**************ENVIAR DETALHES DO PRODUTO COM CÓDIGO PIX DINÂMICO***************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "{RECIPIENT_USER_PHONE_NO_HERE}",
    "type": "interactive",
    "interactive": {
        "type": "order_details",
        "body": {
            "text": "Detalhes do seu pedido"
        },
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "r123456789",
                "type": "digital-goods",
                "payment_type": "br",
           
                "payment_settings": [
                    {
                        "type": "pix_dynamic_code",
                        "pix_dynamic_code": {
                            "code": "{YOUR_DYNAMIC_PIX_CODE_HERE}",
                            "merchant_name": "Account holder name",
                            "key": "50561267000126",
                            "key_type": "CNPJ"
                        }
                    }
                ],
                "currency": "BRL",
                "total_amount": {
                    "value": 1000,
                    "offset": 100
                },
                "order": {
                    "status": "pending",
                    "tax": {
                        "value": 0,
                        "offset": 100,
                        "description": "imposto"
                    },
                    "items": [
                        {
                            "retailer_id": "1234567",
                            "name": "Chocolate (R$ 10)",
                            "amount": {
                                "value": 1000,
                                "offset": 100
                            },
                            "quantity": 1
                        }
                    ],
                    "subtotal": {
                        "value": 1000,
                        "offset": 100
                    }
                }
            }
        }
    }
}

Boleto

Link de Pagamento

Pagamento em um-clique

3

Usuário realiza o pagamento

Agora, o usuário poderá copiar o código PIX, código de barras, ou selecionar o método escolhido, sair do WhatsApp e usar seu app de banco para concluir o pagamento.

A Meta não tem como rastrear esse pagamento, já que ocorre fora do WhatsApp e está vinculado aos sistemas internos do cliente/parceiro via gateway de pagamento.

4

Atualizando o status do pedido ao usuário

• Depois que o pagamento for tentado pelo usuário, o cliente/parceiro recebe a atualização de status via gateway de pagamento.

• Com base nisso, atualize o pedido internamente e envie uma mensagem de order_status ao usuário:

**************ENVIAR STATUS DO PEDIDO***************************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": ""{RECIPIENT_USER_PHONE_NO_HERE}"",
    "type": "interactive",
    "interactive": {
        "type": "order_status",
        "body": {
            "text": "Detalhes do seu pedido"
        },
        "footer" : {
            "text": "Reference: 123456789"
        },
        "action": {
            "name": "review_order",
            "parameters": {
                "reference_id": "123456789",
                "order": {
                    "status": "{ORDER_STATUS_HERE}"
                }
            }
        }
    }
}

Você pode enviar quantas atualizações forem necessárias, conforme seu fluxo interno.

Pagamentos com PIX

Enviando PIX sem janela de conversa aberta (usando templates)

Se você quiser enviar um código PIX para o usuário sem conversa aberta, isso também é possível. Para isso, você precisará:

1. Crie um template do tipo UTILITY (Utilidade) ou MARKETING (Marketing), seja via API ou pelo WhatsApp Manager.

   1. Para criar via API, veja a documentação Create order_details template message via API.

2. Use a versão pré-criada de order_details.

3. Digite o nome desejado para o template.

4. Preencha os componentes do template, como Cabeçalho (Header), Corpo (Body) e, opcionalmente, Rodapé (Footer), e envie.

5. Após o envio, os templates serão categorizados conforme as diretrizes e passarão por um processo de aprovação. Evite incluir conteúdo de marketing nos componentes do template.

6. O template será aprovado ou rejeitado após a verificação dos componentes pelo sistema.

7. Uma vez aprovado, o status do template será alterado para ATIVO (ACTIVE).

Atenção: o status do template pode mudar automaticamente de ATIVO (ACTIVE) para PAUSADO (PAUSED) ou DESATIVADO (DISABLED) com base no feedback dos usuários. Recomendamos monitorar essas mudanças e tomar as ações apropriadas sempre que necessário.

Depois disso, você poderá enviar a mensagem do template incluindo as informações de order_details com o código PIX.

Para todos os detalhes, consulte a documentação oficial.

Exemplo: enviando detalhes do pedido com código de pagamento PIX dinâmico

**************ENVIAR DETALHES DO PEDIDO COM CÓDIGO DE PAGAMENTO PIX DINÂMICO***************************
URL: https://waba-v2.360dialog.io/messages
Sample Request Body:
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<end_user_number>",
  "type": "template",
  "template": {
    "name": "<template_name>",
    "language": {
      "policy": "deterministic",
      "code": "<template_language>"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "order_details",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "order_details": {
                "reference_id": "unique-reference-id",
                "type": "digital-goods",
                "payment_type": "br",
                "payment_settings": [
                  {
                    "type": "pix_dynamic_code",
                    "pix_dynamic_code": {
                      "code": "<pix_code_here>",
                      "merchant_name": "<company_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
                  }
                }
              }
            }
          }
        ]
      }
    ]
  }
}

Gerando um código PIX estático

Como visto acima, é necessário configurar a mensagem com um código PIX. Se você não sabe como gerar um código PIX estático, há um repositório público no GitHub que pode ajudar. Veja aqui.

Coleção no Postman

Criamos uma coleção Postman para que você possa testar os requests. Basta substituir as variáveis pelos valores do seu negócio e importar a coleção para seu Postman:

9KB

Native Payment - PIX.postman_collection.json

Open

Postman collection

---

Extra resources

Check here Meta documentations on the subject:

Payments API - Brazildevelopers.facebook.com

Offsite Pix paymentsdevelopers.facebook.com

Send order details template messagedevelopers.facebook.com