Skip to main content

​
Offsite Pix payments

Updated: Nov 14, 2025 Payments API also enables businesses to collect payments from their customers via WhatsApp using dynamic Pix codes. When using this integration, WhatsApp only facilitates the communication between merchants and buyers. Merchants are responsible for integrating with a bank or PSP in order to generate dynamic Pix codes, and confirm their payment.

​
Before you start

Familiarize yourself with the Orders API. Orders are the entrypoint for collecting payments in WhatsApp. You will need an existing integration with a bank or PSP to generate dynamic Pix codes and do automatic reconciliation when a payment is made. You must be able to update the order status as soon as a payment is made.

​
Integration steps

The following sequence diagram shows the typical integration with Pix. Image

​
1. Send an Order Details message

Follow the full integration guide in the Orders API page. If Pix is available on this order, you will need to provide a pix_dynamic_code to the payment_settings attribute.

​
Parameters object

Field NameOptional?TypeDescription
payment_settingsOptionalPayment Settings ObjectList of payment related configuration objects.

​
Payment settings

Field NameOptional?TypeDescription
typeRequiredStringMust be pix_dynamic_code.
pix_dynamic_codeRequiredDynamic Pix ObjectDynamic Pix Code object that will be used to render the option to buyers during the checkout flow.

​
Dynamic Pix code object

Field NameOptional?TypeDescription
codeRequiredStringThe dynamic Pix code which will be copied by the buyer.
merchant_nameRequiredStringAccount holder name. Displayed in-app for the buyer for informational purposes.
keyRequiredStringPix key. Displayed in-app for the buyer for informational purposes.
key_typeRequiredStringPix key type. One of CPF, CNPJ, EMAIL, PHONE or EVP.

​
Payload example

POST: /v1/messages
\{
 "recipient_type": "individual",
 "to": "[recipient-wa-id]",
 "type": "interactive",
 "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": "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
         }
       }
     }
   }
 }
}

​
2. Send an order status update

Once the payment is confirmed, you must send an order status update. Follow the integration guide in the Orders API page. Did you find this page helpful? Thumbs up icon Thumbs down icon ON THIS PAGE Before you start Integration steps 1. Send an Order Details message Parameters object Payment settings Dynamic Pix code object Payload example 2. Send an order status update