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

Channel specific information

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.

(information)

Info

Twilio/pay is supported only within a WhatsApp session.

Message preview

Data parameters

Parameter	Type	Required	Variable support	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.
`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`	`type`: `ORDER_DETAILS` `code`: Pix code string. `key_type`: One of the following enums: `CPF` `CNPJ` `EMAIL` `PHONE` `EVP` `key`: String type. Pix key.
`ORDER_STATUS`	`type`: `ORDER_STATUS` `status`: One of the following statuses: pending processing partially-shipped shipped completed canceled

Code examples and responses

Create an order details message

1curl -X POST 'https://content.twilio.com/v1/Content' \
2-H 'Content-Type: application/json' \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4-d '{
5    "friendly_name": "twilio_pay_order_details",
6    "language": "en",
7    "types": {
8        "twilio/pay": {
9            "payment_id": "12345",
10            "body": "I am a pay template",
11            "merchant_name": "Twilio",
12            "country_code": "BR",
13            "currency_code": "BRL",
14            "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]",
15            "pix": {
16                    "type": "ORDER_DETAILS",
17                    "code": "insert pix code here",
18                    "key": "+5511968526123",
19                    "key_type": "PHONE"
20                },
21            "subtotal_amount": "5.99",
22            "total_amount": "5.99",
23            "order_expiration": "1743800292",
24            "order_expiration_description": "Ends in 15 min"
25        }
26    }
27}'

Output

1{
2    "account_sid": "ACXXXXXXXXXXXXXXXXXXX",
3    "date_created": "2025-04-07T23:21:27Z",
4    "date_updated": "2025-04-07T23:21:27Z",
5    "friendly_name": "twilio_pay_order_details",
6    "language": "en",
7    "links": {
8        "approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXX/ApprovalRequests/whatsapp",
9        "approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXX/ApprovalRequests"
10    },
11    "sid": "HXXXXXXXXX",
12    "types": {
13        "twilio/pay": {
14            "body": "I am a pay template",
15            "country_code": "BR",
16            "currency_code": "BRL",
17            "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]",
18            "merchant_identifier": null,
19            "merchant_name": "Twilio",
20            "order_expiration": "1743800292",
21            "order_expiration_description": "Ends in 15 min",
22            "payment_id": "12345",
23            "payment_url": null,
24            "pix": {
25                "code": "insert pix code here",
26                "key": "+5511968526123",
27                "key_type": "PHONE",
28                "status": null,
29                "type": "ORDER_DETAILS"
30            },
31            "subtotal_amount": "5.99",
32            "total_amount": "5.99",
33            "total_label": null
34        }
35    },
36    "url": "https://content.twilio.com/v1/Content/HXXXXXXXXX",
37    "variables": {}
38}

Create an order status message

1curl -X POST 'https://content.twilio.com/v1/Content' \
2-H 'Content-Type: application/json' \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4-d '{
5    "friendly_name": "twilio_pay_order_status",
6    "language": "en",
7    "types": {
8        "twilio/pay": {
9            "payment_id": "123451234512345",
10            "body": "i am a {{1}} pay template",
11            "merchant_name": "Twilio",
12            "country_code": "BR",
13            "currency_code": "BRL",
14            "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]",
15            "pix": {
16                    "type": "ORDER_STATUS",
17                    "status": "processing"
18                },
19            "subtotal_amount": "5.99",
20            "total_amount": "5.99"
21        }
22    }
23}'

Output

1{
2    "account_sid": "ACXXXXXXXXXXXX",
3    "date_created": "2025-04-07T23:28:22Z",
4    "date_updated": "2025-04-07T23:28:22Z",
5    "friendly_name": "twilio_pay_order_status",
6    "language": "en",
7    "links": {
8        "approval_create": "https://content.twilio.com/v1/Content/HX6ef38a5f4518c9bab2af102403de87b1/ApprovalRequests/whatsapp",
9        "approval_fetch": "https://content.twilio.com/v1/Content/HX6ef38a5f4518c9bab2af102403de87b1/ApprovalRequests"
10    },
11    "sid": "HXXXXXXXXXXXX",
12    "types": {
13        "twilio/pay": {
14            "body": "i am a {{1}} pay template",
15            "country_code": "BR",
16            "currency_code": "BRL",
17            "items": "[{\"label\":\"Apple\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"3.00\"},{\"label\":\"Orange\",\"quantity\":\"1\",\"id\":\"apple\",\"amount\":\"2.99\"}]",
18            "merchant_identifier": null,
19            "merchant_name": "Twilio",
20            "order_expiration": null,
21            "order_expiration_description": null,
22            "payment_id": "123451234512345",
23            "payment_url": null,
24            "pix": {
25                "code": null,
26                "key": null,
27                "key_type": null,
28                "status": "processing",
29                "type": "ORDER_STATUS"
30            },
31            "subtotal_amount": "5.99",
32            "total_amount": "5.99",
33            "total_label": null
34        }
35    },
36    "url": "https://content.twilio.com/v1/Content/HXXXXXXXXXX",
37    "variables": {}
38}

twilio/pay

Overview

Supported channels

Channel specific information

WhatsApp

Info

Message preview

Data parameters

pix properties

Code examples and responses

Create an order details message

Output

Create an order status message

Output

`pix` properties