Introdução

Este guia irá orientá-lo na realização de sua primeira solicitação de pagamento por débito direto via a API. O fluxo geral é:

1. Criar um cliente
   Você precisa criar um cliente para cada usuário de quem deseja receber fundos.

2. Criar um método de pagamento para o cliente
   Um método de pagamento consiste nas informações da conta bancária ou cartão de débito do seu cliente, de onde você irá retirar fundos.

3. Enviar documentos de consentimento
   Você deve enviar os documentos de consentimento do seu cliente, autorizando você a debitar fundos de sua conta.

   Importante: Acordos de usuário (consentimento)

   Antes de fazer qualquer solicitação de pagamento, você deve obter o consentimento explícito dos seus usuários autorizando você a debitar fundos de suas contas e enviá-lo para a Belvo via a API.

4. Criar uma solicitação de pagamento
   Uma solicitação de pagamento é o valor real que você deseja debitar de um usuário.

5. Ouvir por webhooks
   Você receberá webhooks quando a instituição financeira confirmar que o método de pagamento está registrado e outro quando a solicitação de pagamento tiver sido processada (e os fundos tiverem sido debitados da conta do seu usuário).

Pré-requisitos

Antes de começar, certifique-se de:

1. Gerar suas chaves de API.
2. Configurar um webhook para escutar eventos.
3. Configurar a Lista de IPs Permitidos

Criar um cliente

Para criar um cliente, faça uma chamada POST Create a Direct Debit customer com as seguintes informações principais:

{
  "firstname": "John",
  "lastname": "Doe",
  "documentType": "mx_rfc",
  "documentNumber": "11223344",
  "email": "john.doe@me.com",
  "phone": "573457865"
}

Você receberá a seguinte resposta da nossa API, confirmando que o cliente foi criado. Certifique-se de salvar o customerId que você receber, pois este ID é necessário ao criar um método de pagamento.

{
  "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"
}

Criar um método de pagamento para o cliente

Após criar seu cliente, faça uma solicitação POST Create a payment method para seu cliente com o seguinte payload:

{
  "customerId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "accountType": "savings",
  "accountNumber": "445566790",
  "bank": "mx_bancoppel",
  "reference": "SAVINGS_445566790"
}

Você receberá a seguinte resposta da nossa API, confirmando que o Método de Pagamento foi criado. Certifique-se de salvar o paymentMethodId que você receber, pois este ID é necessário ao gerar um Consentimento e posteriormente Solicitações de Pagamento.

{
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"
}

Crie um consentimento para o seu cliente

Após criar seu método de pagamento, você precisa criar um consentimento para o seu cliente que seja composto por fotos do documento de identidade, uma selfie e um contrato assinado. Este consentimento é necessário para autorizar o débito direto.

O processo de criação do consentimento consiste nas seguintes etapas:

1. Inicializar o Consentimento - Crie um registro de consentimento vinculado ao seu método de pagamento
2. Enviar Arquivos Necessários - Envie fotos do documento de identidade, selfie e contrato assinado
3. Aguardar Revisão e Atualização de Status - Especialistas da Belvo revisam os arquivos (1-2 dias úteis) e atualizam o status.
   • O status pode ser awaiting_information, submitted, incomplete_information, confirmed ou rejected.

Inicializar o Consentimento para um Método de Pagamento

Inicialize o Consentimento para um Método de Pagamento fazendo uma chamada POST Create a Direct Debit Consent com o seguinte payload:

{
  "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b"
}

Nossa API responderá com o seguinte payload, confirmando que o consentimento foi criado. Certifique-se de salvar o consentId que você receber, pois este ID é necessário ao fazer o upload dos arquivos de consentimento.

{
  "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c", 
  "status": "awaiting_information",
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "isBankNotified": false
}

Upload Consent files

Após inicializar o consentimento, você precisa fazer o upload dos arquivos necessários. Faça uma chamada POST Upload Consent Files com o seguinte payload:

curl -i -X POST \
  'baseURL/consents/{consentId}/files' \
  -H 'Content-Type: multipart/form-data' \
  -H 'api-key-id: YOUR_API_KEY_HERE' \
  -H 'api-key-secret: YOUR_API_KEY_HERE' \
  -F id_front=string \
  -F id_back=string \
  -F selfie=string \
  -F contract=string

Nossa API responderá com o seguinte payload, confirmando que os arquivos de consentimento foram carregados com sucesso (um objeto por arquivo de Consentimento carregado):

[
  {
    "type": "id_front",
    "consentFileId": "8c56b4e7-d025-4b1a-a303-dd472b24f431",
    "consentId": "0494baff-3bbb-43c7-bb58-67ac6cba3e54"
  }
]

Monitorar Status do Consentimento

Depois de ter carregado todos os arquivos necessários, o status do consentimento mudará para submitted e então será revisado por nossos especialistas. Uma vez que a revisão esteja completa, o status mudará para confirmed ou rejected. Você pode verificar o status do consentimento fazendo uma chamada GET Get a Direct Debit Consent.

// Exemplo de resposta
{
  "consentId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "status": "submitted",
  "paymentMethodId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c",
  "isBankNotified": false
}

Status Possíveis:

• awaiting_information: Aguardando upload de arquivos
• submitted: Todos os arquivos carregados, em revisão
• incomplete_information: Arquivos necessários ausentes
• confirmed: ✅ Aprovado - você pode agora criar solicitações de pagamento
• rejected: ❌ Negado - verifique o motivo da rejeição e envie novamente

Para mais detalhes sobre os estados dos consentimentos, confira nosso artigo dedicado Estados de Entidade.

Criar uma solicitação de pagamento

Após o consentimento ser confirmado, faça uma chamada POST Create a payment request:

{
  "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b",
  "currency": "mxn",
  "amount": "100000",
  "reference": "Monthly Subscription"
}

Isso retornará o seguinte payload da nossa API:

{
  "paymentRequestId": "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"
}

Ouvir eventos de webhook

Você receberá webhooks quando a instituição financeira confirmar que o método de pagamento está registrado (payment_method_registration_successful) e outro quando a solicitação de pagamento tiver sido processada (payment_request_successful), indicando que os fundos foram debitados da conta do seu usuário.

payment_method_registration_successful

O webhook payment_method_registration_successful indica que o método de pagamento está registrado na instituição financeira do usuário. Assim que você receber este webhook, sua solicitação de pagamento será processada.

payment_request_successful

O webhook payment_request_successful indica que a solicitação de pagamento foi processada e os fundos foram debitados da conta do usuário.