# twilio/pay ## Overview The `twilio/pay` content type is a message used to complete a financial transaction. It can be used to complete a Pix transaction over WhatsApp. End users can do the following: * Send an order details message with a Pix copy code button that opens the end user's banking app to finish a Pix transaction. * Send order status updates to end users as Pix payments progress through order statuses. ## Supported channels WhatsApp ## Channel specific information ### WhatsApp * Businesses need to have a valid sender in the regions where Pix on WhatsApp is supported (only Brazil) * Businesses will need an existing integration with a bank or payment service provider to generate dynamic Pix codes and do automatic reconciliation when a payment is made (i.e. they must be able to confirm when a payment is made, and track when updates occur). * Inbound meta-data is not returned to Twilio, but rather to your payment processor. * Businesses must be able to update the order status as soon as a payment is made. * Businesses need to send two types of pay content templates: Order Details and Order status messages. * Order Detail messages initiate a Pix transaction and give information about it. * Order Status messages update the end user about the status of the Pix transaction. * WhatsApp has five types of eligible Pix key types: * `EMAIL`: An email chosen by the person or business receiving the payment. * `PHONE`: A phone number chosen by the person or business receiving the payment. In Brazil, numbers start with 55, and are composed of 11 numbers. For example: 5551999953123. * `CPF`: For Brazil, the key is composed of 11 numbers (for example: 00912345612), that represent the person receiving the payment. * `CNPJ`: The key is composed of 14 numbers (for example: 01123444000123), that represent the business receiving the payment. * `EVP`: The key is a random string, composed of a sequence of 32 letters or numbers (for example: 1245sT981234cVxI90lKty89ffff09uS), that is generated by the bank representing the person or business receiving the payment. > \[!NOTE] > > `Twilio/pay` is supported only within a WhatsApp session between a BR sender and a BR to number. ### Message preview | ![WhatsApp chat showing payment template with items Apple, Orange totaling R$5,99 and order status processing.](https://docs-resources.prod.twilio.com/48cb758dbb2964d75f0ef5e8d00db65a0d5c752d42b739f36e30d041ade1b81b.jpg) | ![Charge details with items Apple and Orange, total R$ 5,99, pay with Pix option.](https://docs-resources.prod.twilio.com/638cc9a0a6f529f4a0f07203933f6ab9ed842a5cee2bcc062141452eaf943a85.jpg) | ![pay content template 2- message preview.](https://docs-resources.prod.twilio.com/05a133b2020af5758423e8c69eb94c7d677146e4c59fce47d62295f94740657b.jpg) | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ## Data parameters | Parameter | Type | Required | [Variable support](/docs/content/using-variables-with-content-api) | Description | | ------------------------------ | ------ | -------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | `payment_id` | string | Yes | Yes | Unique identifier for the order/payment provided by the business.
Maximum length: 35 characters | | `body` | string | Yes | Yes | Body text of message.
Maximum length: 1,024 characters | | `merchant_name` | string | Yes | Yes | Name of the merchant, business, or seller. | | `country_code` | string | Yes | Yes | Country code. Currently, only BR is supported. | | `currency_code` | string | Yes | No | Currency code. Currently only BRL is supported. | | `items` | array | Yes | Yes | Stringified array of items: `[label,quantity,id,amount]`. | | `order_expiration` | int | Yes | Yes | When the payment expires in epoch time. This time must be in the future. | | `order_expiration_description` | string | Yes | Yes | Text explanation for when the order will expire.
Maximum length: 120 characters | | `subtotal_amount` | string | Yes | Yes | Total cost of items. | | `total_amount` | string | Yes | Yes | Total cost of items and all fees. Only digital goods are permitted and the subtotal must equal the total. | | `pix` | object | Yes | Yes | Order Status or Order Details. | ### `pix` properties | Property | Parameters | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ORDER_DETAILS` | | | `ORDER_STATUS` | | ## Code examples and responses ### Create an order details message Create an order details message ```bash curl -X POST 'https://content.twilio.com/v1/Content' \ -H 'Content-Type: application/json' \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \ -d '{ "friendly_name": "twilio_pay_order_details", "language": "en", "types": { "twilio/pay": { "payment_id": "12345", "body": "I am a pay template", "merchant_name": "Twilio", "country_code": "BR", "currency_code": "BRL", "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]", "pix": { "type": "ORDER_DETAILS", "code": "insert pix code here", "key": "+5511968526123", "key_type": "PHONE" }, "subtotal_amount": "5.99", "total_amount": "5.99", "order_expiration": "1743800292", "order_expiration_description": "Ends in 15 min" } } }' ``` ```json { "account_sid": "ACXXXXXXXXXXXXXXXXXXX", "date_created": "2025-04-07T23:21:27Z", "date_updated": "2025-04-07T23:21:27Z", "friendly_name": "twilio_pay_order_details", "language": "en", "links": { "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXX/ApprovalRequests/whatsapp", "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXX/ApprovalRequests" }, "sid": "HXXXXXXXXX", "types": { "twilio/pay": { "body": "I am a pay template", "country_code": "BR", "currency_code": "BRL", "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]", "merchant_identifier": null, "merchant_name": "Twilio", "order_expiration": "1743800292", "order_expiration_description": "Ends in 15 min", "payment_id": "12345", "payment_url": null, "pix": { "code": "insert pix code here", "key": "+5511968526123", "key_type": "PHONE", "status": null, "type": "ORDER_DETAILS" }, "subtotal_amount": "5.99", "total_amount": "5.99", "total_label": null } }, "url": "https://content.twilio.com/v1/Content/HXXXXXXXXX", "variables": {} } ``` ### Create an order status message Create an order status message ```bash curl -X POST 'https://content.twilio.com/v1/Content' \ -H 'Content-Type: application/json' \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \ -d '{ "friendly_name": "twilio_pay_order_status", "language": "en", "types": { "twilio/pay": { "payment_id": "123451234512345", "body": "i am a {{1}} pay template", "merchant_name": "Twilio", "country_code": "BR", "currency_code": "BRL", "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]", "pix": { "type": "ORDER_STATUS", "status": "processing" }, "subtotal_amount": "5.99", "total_amount": "5.99" } } }' ``` ```json { "account_sid": "ACXXXXXXXXXXXX", "date_created": "2025-04-07T23:28:22Z", "date_updated": "2025-04-07T23:28:22Z", "friendly_name": "twilio_pay_order_status", "language": "en", "links": { "approval_create": "https://content.twilio.com/v1/Content/HX6ef38a5f4518c9bab2af102403de87b1/ApprovalRequests/whatsapp", "approval_fetch": "https://content.twilio.com/v1/Content/HX6ef38a5f4518c9bab2af102403de87b1/ApprovalRequests" }, "sid": "HXXXXXXXXXXXX", "types": { "twilio/pay": { "body": "i am a {{1}} pay template", "country_code": "BR", "currency_code": "BRL", "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]", "merchant_identifier": null, "merchant_name": "Twilio", "order_expiration": null, "order_expiration_description": null, "payment_id": "123451234512345", "payment_url": null, "pix": { "code": null, "key": null, "key_type": null, "status": "processing", "type": "ORDER_STATUS" }, "subtotal_amount": "5.99", "total_amount": "5.99", "total_label": null } }, "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXX", "variables": {} } ```