Detalles del pedido y pago

Last update: 4 days ago by Irais Aguirre

Resumen para integración
Endpoint: POST https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging
Token: de mensajería, en el encabezado Authorization: Bearer {{wa-msg-api-token}} (cómo generarlo)
Campos comunes: from, to (teléfono o BSUID) y type (detalle)
Valores de type en esta página: "interactive"
Respuesta: la misma para todos los mensajes (ver respuesta)

Mensaje interactivo de detalles del pedido (order_details) con uno o varios métodos de pago para clientes en Brasil. Todos los montos se expresan en reales brasileños (BRL). Todos se envían con POST /v1/messaging; los encabezados (Encabezados), los campos comunes y la respuesta (Respuesta) están en Conexión HTTP.

Detalles del pedido

Envía los detalles de un pedido y solicita el pago. El campo type debe ser "interactive" y el contenido va en el objeto order_details con la acción "review_and_pay". Los ejemplos por método de pago están en las secciones siguientes.

Cuerpo

Campos de Detalles del pedido:

Nombre	Descripción	Tipo	Requerimientos
from	Teléfono (con código de país) del que se enviará el mensaje.	String	Obligatorio
to	Teléfono del destinatario en formato E.164, sin el signo +. También acepta el BSUID del usuario, por ejemplo, US.13491208655302741918.	String	Obligatorio
type	Tipo de mensaje. Debe ser "interactive".	String	Obligatorio
order_details	Objeto que contiene el contenido del mensaje y los detalles del pago.	Objeto	Obligatorio

Objeto order details

Nombre	Descripción	Tipo	Requerimientos
body	Texto principal del mensaje.	String	Obligatorio
footer	Texto del pie del mensaje.	String	Opcional
headerImage	Encabezado de imagen opcional (`link` o `id`).	Objeto	Opcional
action	Objeto que contiene la acción y sus parámetros.	Objeto	Obligatorio

Objeto action

Nombre	Descripción	Tipo	Requerimientos
name	Nombre de la acción. Debe ser "review_and_pay".	String	Obligatorio
parameters	Objeto con los datos del pedido y del pago.	Objeto	Obligatorio

Objeto parameters

Nombre	Descripción	Tipo	Requerimientos
reference_id	Identificador único del pedido. Solo admite letras del alfabeto inglés, números, guion, guion bajo y punto.	String	Obligatorio
payment_type	Debe ser "br". Esta sección documenta únicamente el flujo de pago específico de Brasil; otros valores de `payment_type` pertenecen a una API de pagos global independiente que no se documenta aquí.	String	Obligatorio
type	Tipo de bien. Los valores pueden ser: digital-goods physical-goods	String	Obligatorio
payment_settings	Lista de métodos de pago. Admite uno o varios métodos.	Array	Obligatorio
currency	Moneda del pago. Debe ser "BRL".	String	Obligatorio
total_amount.value	Monto total expresado como entero.	Long	Obligatorio
total_amount.offset	Debe ser 100.	Integer	Obligatorio
order	Desglose del pedido (estado, impuestos, artículos y subtotal). Se omite en la carga simplificada.	Objeto	Opcional

Nota: supported_payment_methods pertenece a la API de pagos global independiente y no es válido en este flujo de Brasil (payment_type=br). Este servicio no bloquea la combinación; Meta la rechaza del lado del proveedor y devuelve el error correspondiente de la Graph API, que se reenvía de vuelta al llamador.

Objeto order

Nombre	Descripción	Tipo	Requerimientos
status	Estado del pedido. Valores: pending, processing, partially_shipped, shipped, completed, canceled.	String	Obligatorio si se envía `order`
catalog_id	Identificador del catálogo.	String	Opcional
expiration	Objeto `{ timestamp, description }`.	Objeto	Opcional
items	Lista de artículos del pedido.	Lista de objetos	Obligatorio si se envía `order`
subtotal	Objeto `amount` con el subtotal. `value` debe ser > 0.	Objeto	Obligatorio si se envía `order`
tax	Objeto `amount` con el impuesto.	Objeto	Opcional
shipping	Objeto `amount` con el envío.	Objeto	Opcional
discount	Objeto `amount` con el descuento.	Objeto	Opcional

Objeto items[]

Nombre	Descripción	Tipo	Requerimientos
name	Nombre del artículo.	String	Obligatorio
amount	Objeto `amount` del artículo. `amount.value` > 0.	Objeto	Obligatorio
quantity	Cantidad del artículo.	Integer	Opcional
retailer_id	Identificador del artículo en el comercio.	String	Opcional
catalog_id	Identificador del catálogo.	String	Opcional
sale_amount	Objeto `amount` con el precio en oferta.	Objeto	Opcional

Objeto amount

Nombre	Descripción	Tipo	Requerimientos
value	Monto expresado como entero.	Long	Obligatorio (> 0)
offset	Factor de escala. Debe ser 100 cuando `payment_type` es `br`.	Integer	Obligatorio

Objeto payment settings

Nombre	Descripción	Tipo	Requerimientos
type	Método de pago. Los valores pueden ser: payment_link: Enlace de Pago. pix_dynamic_code: Código Dinámico de PIX. boleto: Boleto.	String	Obligatorio
payment_link	Objeto con los datos del Enlace de Pago.	Objeto	Obligatorio cuando type es payment_link
pix_dynamic_code	Objeto con los datos del Código Dinámico de PIX.	Objeto	Obligatorio cuando type es pix_dynamic_code
boleto	Objeto con los datos del Boleto.	Objeto	Obligatorio cuando type es boleto

Objeto payment link

Nombre	Descripción	Tipo	Requerimientos
uri	Dirección que se abre en el navegador al pulsar el botón. Debe usar el esquema https.	String	Obligatorio

Objeto pix dynamic code

Nombre	Descripción	Tipo	Requerimientos
code	Código dinámico de PIX que el comprador copia para realizar el pago.	String	Obligatorio
merchant_name	Nombre del titular de la cuenta de PIX.	String	Obligatorio
key	Llave de PIX del comercio.	String	Obligatorio
key_type	Tipo de llave. Los valores pueden ser: CPF CNPJ EMAIL PHONE EVP	String	Obligatorio

Objeto boleto

Nombre	Descripción	Tipo	Requerimientos
digitable_line	Línea digitable que el comprador copia para realizar el pago en su banco.	String	Obligatorio

Enlace de Pago

Muestra un botón que abre en el navegador la dirección de pago del comercio.

Ejemplo

Ejemplo completo de Enlace de Pago:

Petición HTTP con carga completa

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": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "footer": "Pagamento seguro",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "link-br-full-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 },
                "order": {
                    "status": "pending",
                    "tax": { "value": 0, "offset": 100, "description": "Imposto" },
                    "items": [
                        {
                            "retailer_id": "SKU-001",
                            "name": "Bolo de chocolate",
                            "amount": { "value": 50000, "offset": 100 },
                            "quantity": 1
                        }
                    ],
                    "subtotal": { "value": 50000, "offset": 100 }
                }
            }
        }
    }
}'

Petición HTTP con carga simplificada

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": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "link-br-simple-002",
                "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 }
            }
        }
    }
}'

Código Dinámico de PIX

Muestra un botón con el que el comprador copia el código de PIX para realizar el pago desde su aplicación bancaria.

Ejemplo

Ejemplo completo de Código Dinámico de PIX:

Petición HTTP con carga completa

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": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "footer": "Pagamento seguro",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "pix-full-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 },
                "order": {
                    "status": "pending",
                    "tax": { "value": 0, "offset": 100, "description": "Imposto" },
                    "items": [
                        {
                            "retailer_id": "SKU-001",
                            "name": "Bolo de chocolate",
                            "amount": { "value": 50000, "offset": 100 },
                            "quantity": 1
                        }
                    ],
                    "subtotal": { "value": 50000, "offset": 100 }
                }
            }
        }
    }
}'

Petición HTTP con carga simplificada

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": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "pix-simple-002",
                "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 }
            }
        }
    }
}'

Boleto

Muestra un botón con el que el comprador copia la línea digitable del boleto para pagarlo en su banco.

Ejemplo

Ejemplo completo de Boleto:

Petición HTTP con carga completa

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": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "footer": "Pagamento seguro",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "boleto-br-full-001",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "boleto",
                        "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 },
                "order": {
                    "status": "pending",
                    "tax": { "value": 0, "offset": 100, "description": "Imposto" },
                    "items": [
                        {
                            "retailer_id": "SKU-001",
                            "name": "Bolo de chocolate",
                            "amount": { "value": 50000, "offset": 100 },
                            "quantity": 1
                        }
                    ],
                    "subtotal": { "value": 50000, "offset": 100 }
                }
            }
        }
    }
}'

Petición HTTP con carga simplificada

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": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "boleto-br-simple-002",
                "payment_type": "br",
                "type": "digital-goods",
                "payment_settings": [
                    {
                        "type": "boleto",
                        "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 }
            }
        }
    }
}'

Múltiples métodos de pago

Un mismo mensaje puede ofrecer PIX, Enlace de Pago y Boleto al mismo tiempo. Asi como botones para páginas web y contácto por télefono.

Ejemplo

Ejemplo completo de Múltiples métodos de pago:

Petición HTTP con PIX, Enlace de Pago y 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": "interactive",
    "order_details": {
        "body": "Detalhes do seu pedido",
        "action": {
            "name": "review_and_pay",
            "parameters": {
                "reference_id": "multi-br-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"
                        }
                    },
                    {
                        "type": "payment_link",
                        "payment_link": { "uri": "https://minhaloja.com.br/pagar/001" }
                    },
                    {
                        "type": "boleto",
                        "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
                    }
                ],
                "currency": "BRL",
                "total_amount": { "value": 50000, "offset": 100 }
            }
        }
    }
}'