Vinculando Contas Bancárias com o Plaid

O Plaid permite que um cliente conecte sua conta bancária dos EUA fazendo login com as credenciais do banco, em vez de digitar manualmente o número de roteamento (routing number) e o número da conta. O gateway encapsula o fluxo do Plaid Link com:

O resultado de um vínculo Plaid concluído é uma conta bancária tokenizada que você passa em um pagamento como paymentMethod.accountTokenId — o mesmo fluxo PULL do ACH, mas sem manipular números bancários em texto puro.

Quando usar Plaid vs. ACH direto: Use o Plaid quando quiser verificação instantânea da conta e uma melhor experiência de conversão, além de evitar coletar/armazenar números de roteamento e de conta em texto puro. Use o ACH direto quando você já possuir dados bancários validados.

Visão Geral do Fluxo

1. POST /providers/plaid          2. Open Plaid Link            3. POST /check-account
   (server-side)                     (client-side)                 (server-side)
        │                                 │                              │
        ▼                                 ▼                              ▼
   Gateway returns a            Customer logs in, selects      Exchange the Plaid public
   Plaid Link token        →    an account; Plaid returns  →   token for a verified,
   (token)                      a public token + account id    tokenized accountTokenId

4. POST /v2/payment
   Use the accountTokenId in paymentMethod to pull funds via ACH

Passo 1 — Criar um Link Token do Plaid

POST https://{FQDN}/providers/plaid

Headers:

Corpo da Requisição

curl -X POST https://{FQDN}/providers/plaid \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+15555550123",
    "androidPackageName": "com.example.app"
  }'

Resposta (200)

Uma chamada bem-sucedida retorna o Link token do Plaid usado para inicializar o Plaid Link no cliente.

{
  "token": "link-sandbox-7f8e9d0c-1a2b-3c4d-...",
  "expiration": "2026-02-12T20:27:26Z",
  "requestId": "JWk6bG8b0zsLXWZ"
}

Passo 2 — Abrir o Plaid Link (Lado do Cliente)

Inicialize o Plaid Link com o token retornado acima. O cliente se autentica no banco e escolhe uma conta. Consulte a documentação do Plaid Link para os SDKs de web, iOS, Android e React Native.

const handler = Plaid.create({
  token: token, // o `token` de POST /providers/plaid
  onSuccess: (publicToken, metadata) => {
    // Link concluído — o Plaid retorna um public token + o id da conta selecionada.
    // Envie ambos ao seu backend para verificar e tokenizar a conta.
    verifyAccount(publicToken, metadata.account_id);
  },
  onExit: (err, metadata) => { /* trate o abandono do fluxo */ }
});
handler.open();

O callback onSuccess do Plaid fornece um public token e o id da conta selecionada — eles se tornam accountCheckToken e accountCheckId no próximo passo.

Passo 3 — Verificar e Tokenizar a Conta

Troque o public token do Plaid por um accountTokenId reutilizável via Check Account. Isso verifica a conta e retorna o token que você usa nos pagamentos.

POST https://{FQDN}/check-account

curl -X POST https://{FQDN}/check-account \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "CHECK_ACCOUNT_0a022f78-14b6-4f6b-8ddd-d1c9be7c4dcc",
    "sender": {
      "paymentMethod": {
        "type": "BANK_DEPOSIT",
        "countryCode": "US",
        "accountCheckToken": "public-sandbox-57f6f60a-e637-4582-8858-b871e59f5f4e",
        "accountCheckId": "X4943dk1W1CbvoJ6r3vPTQrLgWlmyet1vm1on"
      }
    }
  }'

A resposta retorna status: "VERIFIED" e o accountTokenId que você usará para captar fundos:

{
  "paymentId": "cf8600be-ec46-4ed9-a00b-ece348004ca7",
  "externalPaymentId": "CHECK_ACCOUNT_0a022f78-14b6-4f6b-8ddd-d1c9be7c4dcc",
  "accountTokenId": "62d37fd8-89d0-43ca-900f-a75a6e871fe5",
  "approved": true,
  "status": "VERIFIED",
  "bankAccountName": "Chase",
  "accountNumberMasked": "************0000",
  "routingNumberMasked": "*****1533"
}

Consulte Check Account para a referência completa dos campos de requisição e resposta.

Passo 4 — Captar Fundos Usando a Conta Vinculada

Use o accountTokenId do Passo 3 em um pagamento PULL padrão. Nenhum número de roteamento/conta é enviado — o token referencia a conta verificada.

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "plaid-order-001",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULL",
    "capture": true,
    "amount": {
      "total": 19.99,
      "currency": "USD"
    },
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "paymentMethod": {
        "type": "BANK_DEPOSIT",
        "accountTokenId": "62d37fd8-89d0-43ca-900f-a75a6e871fe5"
      }
    }
  }'

A resposta do pagamento é idêntica à de um débito ACH direto — pagamentos ACH são capturados automaticamente, portanto um resultado bem-sucedido retorna o status CAPTURED.

Próximos Passos

• ACH (Conta Bancária) — Capte fundos com números de roteamento/conta em texto puro (sem Plaid)
• Payment — Operações principais de pagamento e estrutura do payload
• Webhooks — Receba atualizações de status de pagamento de forma assíncrona