Payment templates

Last update: 6 hours ago by Irais Aguirre

Integration summary
Base URL: https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services (create) and https://{{url}}/whatsapp-bsp-api-endpoint-ws/services (send)
Token: admin token to create (Authorization: Bearer {{admin-token}}) and messaging token to send (Authorization: Bearer {{wa-msg-api-token}}) (how to generate it)
Endpoints on this page:
POST /v1/template: Create a payment request template (admin token)
POST /v1/messaging: Order details template (messaging token, type "template")
POST /v1/messaging: Send a payment request template (messaging token, type "template")
Send response: the same for every message (see response)

You can also send payment methods inside approved templates, either with an order details button or with payment request buttons.

Order details template

Sends an approved template with an order details button. The type field must be "template". It is sent with POST /v1/messaging and the messaging token; headers and the response are in HTTP connection.

Body

Fields for Order details template:

Name	Description	Type	Requirements
type	Message type. Must be "template".	String	Required
template.name	Name of the approved template.	String	Required
template.language	Template language.	String	Required
components.type	Must be "button".	String	Required
components.subtype	Must be "order_details".	String	Required
components.index	Position of the button in the template.	Integer	Required
parameters.type	Must be "action".	String	Required
action.order_details	Object with the same attributes as the Parameters object.	Object	Required

Example

Complete Order details template example:

HTTP request with PIX

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "template",
    "template": {
        "name": "payment_template",
        "language": "es_MX",
        "components": [
            {
                "type": "button",
                "subtype": "order_details",
                "index": 0,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "order_details": {
                                "reference_id": "tpl-pix-001",
                                "payment_type": "br",
                                "type": "digital-goods",
                                "payment_settings": [
                                    {
                                        "type": "pix_dynamic_code",
                                        "pix_dynamic_code": {
                                            "code": "00020101021226700014br.gov.bcb.pix2548pix.example.com",
                                            "merchant_name": "Minha Loja",
                                            "key": "39580525000189",
                                            "key_type": "CNPJ"
                                        }
                                    }
                                ],
                                "currency": "BRL",
                                "total_amount": { "value": 50000, "offset": 100 }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

HTTP request with Boleto

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "template",
    "template": {
        "name": "payment_template",
        "language": "es_MX",
        "components": [
            {
                "type": "button",
                "subtype": "order_details",
                "index": 0,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "order_details": {
                                "reference_id": "tpl-boleto-001",
                                "payment_type": "br",
                                "type": "digital-goods",
                                "payment_settings": [
                                    {
                                        "type": "boleto",
                                        "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                                    }
                                ],
                                "currency": "BRL",
                                "total_amount": { "value": 50000, "offset": 100 }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

HTTP request with Payment link

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "template",
    "template": {
        "name": "payment_template",
        "language": "es_MX",
        "components": [
            {
                "type": "button",
                "subtype": "order_details",
                "index": 0,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "order_details": {
                                "reference_id": "tpl-link-001",
                                "payment_type": "br",
                                "type": "digital-goods",
                                "payment_settings": [
                                    {
                                        "type": "payment_link",
                                        "payment_link": { "uri": "https://minhaloja.com.br/pagar/001" }
                                    }
                                ],
                                "currency": "BRL",
                                "total_amount": { "value": 50000, "offset": 100 }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

Create a payment request template

Creates a template with payment request buttons. The template stays PENDING until it is approved.

Request

Create a payment request template request:


URL	https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/template
Method	POST
Type	application/json

Headers

Create a payment request template headers:

Name	Description	Type	Requirements
Content-Type	application/json	String	Required
Authorization	Admin token. See Generate authentication token.	String	Required

Body

Create a payment request template body fields:

Name	Description	Type	Requirements
wba_id	WhatsApp Business Account ID. Note: this field is sent as `wba_id` (without the second `a`) to match the current DTO. Templates elsewhere in the API use `waba_id`; this inconsistency is pending alignment on the backend.	String	Required
name	Template name. Must be unique within the account.	String	Required
language	Template language.	String	Required
category	Template category. Possible values: UTILITY MARKETING	String	Required
structure.body.text	Main text of the template.	String	Required
buttons.type	Must be "PAYMENT_REQUEST". Can be combined with URL and PHONE_NUMBER buttons.	String	Required
buttons.text	Button label, depending on the payment method: Copy Pix code Copy Boleto code Open payment link	String	Required
payment_setting.type	Payment method. Possible values: pix_dynamic_code boleto payment_link	String	Required
pix_dynamic_code.code	Sample PIX code. The actual value is provided when you send the message.	String	Conditional
boleto.digitable_line	Sample digitable line.	String	Conditional
payment_link.uri	Sample URL.	String	Conditional

Example

Complete Create a payment request template example:

HTTP request with three payment methods

curl -X POST 'https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/template' \
-H 'Authorization: Bearer {{admin-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "wba_id": "100000000000000",
    "name": "payment_template",
    "language": "es_MX",
    "category": "UTILITY",
    "structure": {
        "body": { "text": "Choose your preferred payment method." },
        "buttons": [
            {
                "type": "PAYMENT_REQUEST",
                "text": "Copy Pix code",
                "payment_setting": {
                    "type": "pix_dynamic_code",
                    "pix_dynamic_code": { "code": "00020101021226700014br.gov.bcb.pix2548pix.example.com" }
                }
            },
            {
                "type": "PAYMENT_REQUEST",
                "text": "Copy Boleto code",
                "payment_setting": {
                    "type": "boleto",
                    "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                }
            },
            {
                "type": "PAYMENT_REQUEST",
                "text": "Open payment link",
                "payment_setting": {
                    "type": "payment_link",
                    "payment_link": { "uri": "https://minhaloja.com.br/pagar/001" }
                }
            }
        ]
    }
}'

HTTP request with a payment button combined with other button types

You can combine the payment request button with website (URL) and call (PHONE_NUMBER) buttons.

Note: Meta doesn't accept every combination. In testing, the payment button can't be placed in the middle of three buttons.

curl -X POST 'https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/template' \
-H 'Authorization: Bearer {{admin-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "wba_id": "100000000000000",
    "name": "payment_template_promo",
    "language": "es_MX",
    "category": "MARKETING",
    "structure": {
        "body": { "text": "Pacotes de viagem selecionados de 4 dias agora estão com 50% de desconto!" },
        "buttons": [
            {
                "type": "PAYMENT_REQUEST",
                "text": "Copy Boleto code",
                "payment_setting": {
                    "type": "boleto",
                    "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                }
            },
            { "type": "URL", "text": "Visitar site", "url": "https://minhaloja.com.br" },
            { "type": "PHONE_NUMBER", "text": "Ligue para nós", "phone_number": "+5511900000003" }
        ]
    }
}'

Response

Create a payment request template response:

Name	Description	Type
id	ID of the created template.	String
name	Template name.	String
language	Template language.	String
status	Template status. Stays PENDING until the template is approved.	String
namespace	Template namespace.	String
category	Template category.	String
allowCategoryChange	Whether the category can be changed.	Boolean
wba_id	WhatsApp Business Account ID.	String
code	Response code if an error occurs. For details, see Error codes.	Number
detail	Message describing the response code.	String

Successful response example

{
    "id": "1550894429574477",
    "name": "payment_template",
    "language": "es_MX",
    "status": "PENDING",
    "namespace": "00000000_0000_0000_0000_000000000000",
    "category": "UTILITY",
    "allowCategoryChange": true,
    "wba_id": "100000000000000"
}

Error response example

{
    "code": 2104,
    "detail": "Template already exists with ID: 1550894429574477"
}

Send a payment request template

Sends an approved template with payment request buttons. The type field must be "template". It is sent with POST /v1/messaging and the messaging token; headers and the response are in HTTP connection.

Body

Fields for Send a payment request template:

Name	Description	Type	Requirements
components.type	Must be "button".	String	Required
components.subtype	Must be "payment_request".	String	Required
components.index	Position of the payment button in the template. Possible values: 0, 1, 2.	Integer	Required
parameters.type	Must be "action".	String	Required
action.payment_request	Object wrapping `payment_setting`.	Object	Required
action.payment_request.payment_setting.type	Payment method. Possible values: pix_dynamic_code boleto payment_link	String	Required
action.payment_request.payment_setting.pix_dynamic_code.code	PIX dynamic code for the transaction.	String	Conditional
action.payment_request.payment_setting.boleto.digitable_line	Digitable line for the transaction.	String	Conditional
action.payment_request.payment_setting.payment_link.uri	Payment URL for the transaction.	String	Conditional

Note: In the payment request template, the pix_dynamic_code object supports only the code attribute, unlike the one used in order details messages.

Example

Complete Send a payment request template example:

HTTP request with one payment button

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "template",
    "template": {
        "name": "payment_template_promo",
        "language": "es_MX",
        "components": [
            {
                "type": "button",
                "subtype": "payment_request",
                "index": 0,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "payment_request": {
                                "payment_setting": {
                                    "type": "boleto",
                                    "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                                }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

HTTP request with three payment buttons

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5511900000001",
    "to": "5511900000002",
    "type": "template",
    "template": {
        "name": "payment_template",
        "language": "es_MX",
        "components": [
            {
                "type": "button",
                "subtype": "payment_request",
                "index": 0,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "payment_request": {
                                "payment_setting": {
                                    "type": "pix_dynamic_code",
                                    "pix_dynamic_code": { "code": "00020101021226700014br.gov.bcb.pix2548pix.example.com" }
                                }
                            }
                        }
                    }
                ]
            },
            {
                "type": "button",
                "subtype": "payment_request",
                "index": 1,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "payment_request": {
                                "payment_setting": {
                                    "type": "boleto",
                                    "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                                }
                            }
                        }
                    }
                ]
            },
            {
                "type": "button",
                "subtype": "payment_request",
                "index": 2,
                "parameters": [
                    {
                        "type": "action",
                        "action": {
                            "payment_request": {
                                "payment_setting": {
                                    "type": "payment_link",
                                    "payment_link": { "uri": "https://minhaloja.com.br/pagar/001" }
                                }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'