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 é:

Criar um cliente
Você precisa criar um cliente para cada usuário de quem deseja receber fundos.
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.
Criar uma solicitação de pagamento
Uma solicitação de pagamento é o valor real que você deseja debitar de um usuário.
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).

Importante: Acordos com usuários (consentimento)

Antes de fazer qualquer solicitação de pagamento, você deve:

Obter consentimento explícito dos seus usuários, autorizando você a debitar fundos de suas contas.
Manter evidências documentadas desse consentimento.

Solicitações subsequentes de débito direto

Depois de criar inicialmente um cliente e sua conta (método de pagamento) ser registrada com sucesso, solicitações subsequentes de débito direto exigem apenas que você faça um POST Create a payment request.

Pré-requisitos

Antes de começar, certifique-se de:

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

Parâmetro	Tipo	Obrigatório	Descrição
`firstname`	string	sim	O primeiro nome do seu usuário.
`lastname`	string	sim	O sobrenome do seu usuário.
`documentType`	string	sim	O tipo de documento de identificação do seu usuário. Para 🇲🇽 México, pode ser um dos seguintes: `mx_rfc`: Número de Identificação Fiscal (Registro Federal de Contribuyentes), `mx_curp`: Código Único de Registro de População (Clave Única de Registro de Población).
`documentNumber`	string	sim	O número do documento do usuário.
`email`	string	sim	O email do usuário.
`phone`	string	não	O número de telefone do usuário (incluindo o código do país).

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 o seu cliente com o seguinte payload:

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

Parâmetro	Tipo	Obrigatório	Descrição
`customerId`	string	sim	O `customerId` para o qual você deseja criar o método de pagamento.
`accountType`	string	sim	O tipo de conta bancária ou cartão. Pode ser: `savings`, `checkings` ou `debit_card`.
`accountNumber`	string	sim	O número da conta bancária ou do cartão de débito.
`bank`	string	sim	O nome do banco mexicano onde a conta ou cartão está registrado. Para uma lista completa de instituições, consulte nossa página dedicada a Instituições de Pagamento.
`reference`	string	não	Uma descrição de referência opcional para a conta bancária.

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 uma solicitação de pagamento.

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

Criar uma solicitação de pagamento

Após criar seu método de pagamento, faça uma chamada POST Create a payment request para o método de pagamento com o seguinte payload:

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

Parâmetro	Tipo	Obrigatório	Descrição
`paymentMethodId`	string	sim	O `paymentMethodId` do qual você deseja debitar fundos.
`currency`	string	sim	O código de moeda de três letras ISO 4217 da transação. Pode ser: `mxn` ou `usd`.
`amount`	string	sim	O valor da transação.
`reference`	string	sim	Uma descrição para o débito direto (para aparecer no extrato do cliente).

Isso retornará o seguinte payload da nossa API:

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

Solicitações de pagamento só são executadas para métodos de pagamento ativos

A solicitação de pagamento permanecerá no status initial até que o método de pagamento se torne active. Você receberá webhooks indicando quando o método de pagamento foi registrado com sucesso (active) e, em seguida, um webhook indicando que a solicitação de pagamento foi processada com sucesso.

Ouça por 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 para 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.

✳️ Feito! Você acabou de configurar seu primeiro débito direto para um usuário. Débitos subsequentes para o mesmo usuário exigirão apenas que você envie uma solicitação de pagamento e aguarde o webhook payment_request_successful.