Zinia — Compre Agora, Pague Depois

O Zinia é um método de pagamento “Compre Agora, Pague Depois” (BNPL - Buy Now, Pay Later) do Santander que permite aos clientes dividir suas compras em parcelas ou pagar depois. Este guia detalha como integrar o Zinia através da Global API utilizando o fluxo padrão de redirecionamento de Método de Pagamento Alternativo (APM).

Ao contrário dos métodos de pagamento imediatos, a resposta inicial para uma requisição Zinia retorna um status WAITING. Isso indica que a requisição foi bem-sucedida, mas o cliente deve ser redirecionado para o portal do Zinia para concluir a autorização.

Requisitos

Antes de integrar o Zinia, certifique-se de que os seguintes itens estejam configurados:

Autenticação: Um Bearer Token gerado através do endpoint de Autenticação.
Listener de Webhook: Você deve ter um endpoint HTTPS público (callback_url) pronto para receber notificações assíncronas sobre o status final do pagamento.
Habilitação do Estabelecimento: Coordene com seu Gerente de Contas para ativar a marca Zinia para sua conta de estabelecimento.

Especificidades de Casos de Uso

Ao integrar qualquer solução Getnet, aplicam-se requisitos específicos do mercado. O Zinia está disponível principalmente para mercados europeus (ex.: Espanha) e espera a moeda EUR.

Características

Capacidade	Detalhes
Interação com o cliente	Redirecionamento para o portal de financiamento do Zinia para seleção de parcelas e aprovação.
Confirmação	Assíncrona: status inicial `WAITING`, depois `APPROVED` ou `DENIED` via webhook.
Notificações	Webhooks para atualizações de status em tempo real após o cliente concluir o fluxo do portal.

Funcionalidades Disponíveis

Use a matriz abaixo para confirmar os cenários atualmente suportados para o Zinia.

Fluxo de pagamento	Países suportados	Compras	Reembolsos	Reembolsos parciais	Pré-autorizações
Redirect	Europa (ES, DE, etc.)	✅	✅	✅	❌

Guia de Simulação Sandbox

Para testar e aprovar transações com sucesso no ambiente sandbox, você deve usar “gatilhos de simulação” específicos:

Nome do Cliente: O customer.name deve incluir a string ZINIA_AP como sobrenome para acionar a lógica de aprovação do motor de sandbox.
Valor da Transação: Use um amount de 500 ou mais (ex.: 600 para €6.00). Valores abaixo de 500 podem ser automaticamente recusados pelo motor de risco de teste.
Verificação de Identidade: Se o portal do Zinia solicitar o upload de um documento durante o teste, você pode enviar qualquer arquivo de imagem para ignorar esse requisito.

Fluxo de Integração

zinia flow

1. Criar a Requisição de Pagamento

Chame o endpoint Create – Authorize com os atributos abaixo. Demografia detalhada do cliente e itens do pedido são estritamente exigidos para a modelagem de risco do Zinia.

Atributo	Descrição	Valor Obrigatório
`payment_method`	Método de pagamento BNPL	`BNPL`
`brand`	Identificador da marca	`ZINIA`
`amount`	Valor da transação em centavos	Inteiro (ex.: `600` para €6.00)
`currency`	Código de moeda ISO	`EUR`
`order.items`	Array de itens sendo comprados	Obrigatório

Exemplo de Requisição:

curl --location --request POST 'https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
    "idempotency_key": "ed2851df-9c94-4229-8848-32043e84f9a1",
    "request_id": "de311099-20b4-4d50-b3c6-08d90c52242c",
    "order_id": "ttk9vnt8qwj7",
    "data": {
        "amount": 600,
        "currency": "EUR",
        "customer_id": "42412312523",
        "payment": {
            "payment_id": "ttk9vnt8qwj7",
            "payment_method": "BNPL",
            "brand": "ZINIA",
            "soft_descriptor": "ZINIA TESTE"
        },
        "additional_data": {
            "callback_url": "https://webhooksite/6ca8fe64-73e2-4400-a760-94c41e92ab43",
            "customer": {
                "email": "joedoe.doejoe@getnet.net",
                "document_number": "50506468",
                "document_type": "uyci",
                "name": "Jose ZINIA_AP",
                "phone_number": "34700000000",
                "billing_address": {
                    "street": "R a",
                    "number": "1",
                    "district": "B",
                    "city": "City Z",
                    "state": "SP",
                    "country": "ES",
                    "postal_code": "05781000",
                    "complement": "N/A"
                }
            },
            "order": {
                "items": [
                    {
                        "name": "Item2",
                        "quantity": 1,
                        "sku": "sku1",
                        "price": 600
                    }
                ]
            }
        }
    }
}'

2. Tratando a Resposta e o Redirecionamento

A resposta inicial retorna um status: WAITING. Você deve redirecionar o cliente para o portal de financiamento usando os dados fornecidos no array additional_data._links.

Exemplo de Resposta:

{
    "payment_id": "ttk9vnt8qwj7",
    "status": "WAITING",
    "reason_message": "Waiting payment flow.",
    "additional_data": {
        "signature": "c5LN2xXHUtardFVg...",
        "_links": [
            {
                "rel": "apm_html",
                "type": "POST",
                "href": "https://sis-i.redsys.es:25443/sis/realizarPago"
            }
        ],
        "merchant_data": "eyJvcmRlcl9pZCI6...",
        "signature_version": "T25V2"
    }
}

Para concluir o fluxo, construa um formulário ou uma requisição fetch usando os seguintes parâmetros:

Método: Use o método HTTP especificado em type (geralmente POST).
Endpoint: Redirecione para o href fornecido no link apm_html.
Dados: Você deve incluir o merchant_data, signature e signature_version no payload de redirecionamento.

3. Verificar Status do Pagamento

Após o cliente concluir o fluxo de autorização no Zinia, ele é retornado ao seu site. Simultaneamente, a Getnet envia uma notificação para a sua callback_url.

Status	Descrição	Próxima Ação
WAITING	Requisição bem-sucedida; o cliente deve autorizar o financiamento.	Redirecionar o cliente para o portal do Zinia.
APPROVED	Financiamento aprovado e pagamento capturado.	Cumprir o pedido.
DENIED	O financiamento foi rejeitado pelo motor de risco.	Exibir erro e oferecer outro método de pagamento.

Você também pode verificar o status manualmente usando o endpoint Get Transaction.