Plantillas de pago

Last update: 4 days ago by Irais Aguirre

Resumen para integración
URL base: https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services (crear) y https://{{url}}/whatsapp-bsp-api-endpoint-ws/services (enviar)
Token: de administración para crear (Authorization: Bearer {{admin-token}}) y de mensajería para enviar (Authorization: Bearer {{wa-msg-api-token}}) (cómo generarlo)
Endpoints en esta página:
POST /v1/template: Crear plantilla de solicitud de pago (token de administración)
POST /v1/messaging: Plantilla de detalles del pedido (token de mensajería, type "template")
POST /v1/messaging: Enviar plantilla de solicitud de pago (token de mensajería, type "template")
Respuesta de envío: la misma para todos los mensajes (ver respuesta)

Los métodos de pago también pueden enviarse dentro de plantillas aprobadas, ya sea con un botón de detalles del pedido o con botones de solicitud de pago.

Plantilla de detalles del pedido

Envía una plantilla aprobada con un botón de detalles del pedido. El campo type debe ser "template". Se envía con POST /v1/messaging y token de mensajería; los encabezados y la respuesta están en Conexión HTTP.

Cuerpo

Campos de Plantilla de detalles del pedido:

Nombre	Descripción	Tipo	Requerimientos
type	Tipo de mensaje. Debe ser "template".	String	Obligatorio
template.name	Nombre de la plantilla aprobada.	String	Obligatorio
template.language	Lenguaje de la plantilla.	String	Obligatorio
components.type	Debe ser "button".	String	Obligatorio
components.subtype	Debe ser "order_details".	String	Obligatorio
components.index	Posición del botón dentro de la plantilla.	Integer	Obligatorio
parameters.type	Debe ser "action".	String	Obligatorio
action.order_details	Objeto con los mismos atributos del objeto parameters.	Objeto	Obligatorio

Ejemplo

Ejemplo completo de Plantilla de detalles del pedido:

Petición HTTP con 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 }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

Petición HTTP con 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 }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

Petición HTTP con Enlace de Pago

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 }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

Crear plantilla de solicitud de pago

Crea una plantilla con botones de solicitud de pago. La plantilla queda en estado PENDING hasta que sea aprobada.

Petición

Petición de Crear plantilla de solicitud de pago:


URL	https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/template
Método	POST
Tipo	application/json

Encabezados

Encabezados de Crear plantilla de solicitud de pago:

Nombre	Descripción	Tipo	Requerimientos
Content-Type	application/json	String	Obligatorio
Authorization	Token de administración. Consulta Generar Token de Autenticación.	String	Obligatorio

Cuerpo

Campos del cuerpo de Crear plantilla de solicitud de pago:

Nombre	Descripción	Tipo	Requerimientos
wba_id	Identificador de la cuenta empresarial de WhatsApp. Nota: este campo se envía como `wba_id` (sin la segunda `a`) para coincidir con el DTO actual. Otras plantillas de la API usan `waba_id`; esta inconsistencia está pendiente de alinearse en el backend.	String	Obligatorio
name	Nombre de la plantilla. Debe ser único en la cuenta.	String	Obligatorio
language	Lenguaje de la plantilla.	String	Obligatorio
category	Categoría de la plantilla. Los valores pueden ser: UTILITY MARKETING	String	Obligatorio
structure.body.text	Texto principal de la plantilla.	String	Obligatorio
buttons.type	Debe ser "PAYMENT_REQUEST". Puede combinarse con botones de tipo URL y PHONE_NUMBER.	String	Obligatorio
buttons.text	Etiqueta del botón según el método de pago: Copy Pix code Copy Boleto code Open payment link	String	Obligatorio
payment_setting.type	Método de pago. Los valores pueden ser: pix_dynamic_code boleto payment_link	String	Obligatorio
pix_dynamic_code.code	Código de muestra de PIX. El valor real se envía al momento de enviar el mensaje.	String	Condicional
boleto.digitable_line	Línea digitable de muestra.	String	Condicional
payment_link.uri	Dirección de muestra.	String	Condicional

Ejemplo

Ejemplo completo de Crear plantilla de solicitud de pago:

Petición HTTP con tres métodos de pago

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": "Elige tu método de pago preferido." },
        "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" }
                }
            }
        ]
    }
}'

Petición HTTP con botón de pago combinado con otros tipos

El botón de solicitud de pago puede combinarse con botones de sitio web (URL) y de llamada (PHONE_NUMBER).

Nota: Meta no acepta todas las combinaciones. En pruebas, el botón de pago no puede quedar en medio de tres botones.

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" }
        ]
    }
}'

Respuesta

Respuesta de Crear plantilla de solicitud de pago:

Nombre	Descripción	Tipo
id	Identificador de la plantilla creada.	String
name	Nombre de la plantilla.	String
language	Lenguaje de la plantilla.	String
status	Estado de la plantilla. Queda en PENDING hasta que sea aprobada.	String
namespace	Espacio de nombres de la plantilla.	String
category	Categoría de la plantilla.	String
allowCategoryChange	Indica si se permite el cambio de categoría.	Boolean
wba_id	Identificador de la cuenta empresarial de WhatsApp.	String
code	Código de respuesta en caso de error. Para mayor detalle, ver sección Códigos de Error	Number
detail	Mensaje descriptivo del código de respuesta recibido.	String

Ejemplo respuesta exitosa

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

Ejemplo respuesta errónea

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

Enviar plantilla de solicitud de pago

Envía una plantilla aprobada con botones de solicitud de pago. El campo type debe ser "template". Se envía con POST /v1/messaging y token de mensajería; los encabezados y la respuesta están en Conexión HTTP.

Cuerpo

Campos de Enviar plantilla de solicitud de pago:

Nombre	Descripción	Tipo	Requerimientos
components.type	Debe ser "button".	String	Obligatorio
components.subtype	Debe ser "payment_request".	String	Obligatorio
components.index	Posición del botón de pago dentro de la plantilla. Los valores pueden ser: 0, 1, 2.	Integer	Obligatorio
parameters.type	Debe ser "action".	String	Obligatorio
action.payment_request	Objeto que envuelve `payment_setting`.	Objeto	Obligatorio
action.payment_request.payment_setting.type	Método de pago. Los valores pueden ser: pix_dynamic_code boleto payment_link	String	Obligatorio
action.payment_request.payment_setting.pix_dynamic_code.code	Código dinámico de PIX de la transacción.	String	Condicional
action.payment_request.payment_setting.boleto.digitable_line	Línea digitable de la transacción.	String	Condicional
action.payment_request.payment_setting.payment_link.uri	Dirección de pago de la transacción.	String	Condicional

Nota: en la plantilla de solicitud de pago, el objeto pix_dynamic_code admite únicamente el atributo code, a diferencia del utilizado en los mensajes de detalles del pedido.

Ejemplo

Ejemplo completo de Enviar plantilla de solicitud de pago:

Petición HTTP con un botón de pago

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" }
                                }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'

Petición HTTP con tres botones de pago

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" }
                                }
                            }
                        }
                    }
                ]
            }
        ]
    }
}'