twilio/pay

Overview

Twilio/pay is a message used to complete a financial transaction. It can be used to complete a PIX transaction over WhatsApp.

What is supported for end users

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 (WA)

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 2 types of pay 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 5 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 (example: 00912345612), that represent the person receiving the payment.
- CNPJ: The key is composed of 14 numbers (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 (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

payment_id:

Type: string
Required: yes
Variable Support: yes
Description: Unique identifier for the order/payment provided by the business. Maximum 35 characters.

body:

Type: string
Required: yes
Variable Support: yes
Description: Body text of message. Maximum 1024 characters.

merchant_name:

Type: string
Required: yes
Variable Support: yes
Description: Name of the merchant, business, or seller.

**country_code:

Type: string
Required: yes
Variable Support: no
Description: Country code. Currently only BR is supported.

currency_code:

Type: string
Required: yes
Variable Support: no
Description: Currency code. Currently only BRL is supported.

items:

Type: array
Required: Yes
Variable Support: Yes
Description: Stringified array of items [label,quantity,id,amount].

order_expiration:

Type: int
Required: yes
Variable Support: yes
Description: When the payment expires in epoch time.

order_expiration_description:

Type: string
Required: yes
Variable Support: yes
Description: Text explanation for when the order will expire. Max character limit is 120 characters.

subtotal_amount:

Type: string
Required: yes
Variable Support: yes
Description: total cost of items.

total_amount:

Type: string
Required: yes
Variable Support: yes
Description: Total cost of items and all fees. Only digital goods are permitted and the subtotal must equal the total.

pix:

*Type: object
Required: Yes
Variable Support: Yes
Description: Order Status or Order Details

PIX: Order Details Type: "ORDER_DETAILS"

**parameters
type: ORDER_DETAILS
code: String type. PIX code string.
key_type: String type. One of the following ENUMS
- CPF
- CNPJ
- EMAIL
- PHONE
- EVP key: String type. PIX key

PIX: Order Status Type: "ORDER_STATUS"

parameters
type: ORDER_STATUS
status: String type. Supported statuses
- pending
- processing
- partially-shipped
- shipped
- completed
- canceled

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}