Check Account

A API Check Account verifica uma conta bancária vinculada por meio do Plaid e retorna um accountTokenId reutilizável que você pode usar para captar fundos via ACH — sem nunca manipular números de conta e de roteamento em texto claro.

Ela é a etapa de finalização do fluxo de vinculação bancária do Plaid: depois que o cliente conclui o Plaid Link, você troca o public token do Plaid (accountCheckToken) e o id da conta (accountCheckId) por uma conta tokenizada e verificada.

Use este endpoint para:

Tokenizar uma conta vinculada via Plaid em um accountTokenId para reutilização em pagamentos
Verificar a titularidade da conta antes de submeter um pagamento pull
Reduzir transações com falha capturando cedo detalhes de conta inválidos

Nota: Esta API não debita a conta nem cria um pagamento. Ela apenas verifica e tokeniza a conta.

Endpoint

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

Cabeçalhos:

Cabeçalho	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Requisição

Objeto Raiz

Campo	Tipo	Obrigatório	Descrição
`externalPaymentId`	string	Sim	Seu identificador único para esta requisição de verificação (chave de idempotência)
`sender`	object	Sim	Dados do remetente — encapsula o método de pagamento a verificar

Objeto `sender`

Campo	Tipo	Obrigatório	Descrição
`paymentMethod`	object	Sim	A conta vinculada via Plaid a verificar e tokenizar

`sender.paymentMethod`

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"BANK_DEPOSIT"`
`countryCode`	string	Sim	País do banco (ISO Alpha-2, ex.: `"US"`)
`accountCheckToken`	string	Sim	O public token do Plaid retornado pelo Plaid Link no cliente (`public-sandbox-...` / `public-production-...`)
`accountCheckId`	string	Sim	O id da conta do Plaid que o cliente selecionou no Plaid Link

Exemplo de Requisição

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

Resposta — Verificado (200)

{
  "paymentId": "cf8600be-ec46-4ed9-a00b-ece348004ca7",
  "parentPaymentId": "cf8600be-ec46-4ed9-a00b-ece348004ca7",
  "externalPaymentId": "CHECK_ACCOUNT_0a022f78-14b6-4f6b-8ddd-d1c9be7c4dcc",
  "accountTokenId": "62d37fd8-89d0-43ca-900f-a75a6e871fe5",
  "created": "2026-05-29 16:39:57",
  "approved": true,
  "accessToken": "access-sandbox-b16d9e78-b2d0-48ca-b2af-dc985571776b",
  "status": "VERIFIED",
  "bankAccountName": "Chase",
  "accountNumberMasked": "************0000",
  "routingNumberMasked": "*****1533"
}

Campos da Resposta

Campo	Tipo	Descrição
`paymentId`	string	Identificador único da Inyo para esta verificação
`parentPaymentId`	string	Identificador raiz (igual a `paymentId` para uma verificação isolada)
`externalPaymentId`	string	O identificador que você forneceu na requisição
`accountTokenId`	string	A conta tokenizada. Passe este valor como `sender.paymentMethod.accountTokenId` em uma requisição de pagamento para captar fundos
`created`	string	Timestamp da verificação
`approved`	boolean	Se a conta foi verificada com sucesso
`accessToken`	string	Access token do Plaid associado ao item vinculado (armazene com segurança se precisar consultar a conta novamente)
`status`	string	Status da verificação — `VERIFIED` em caso de sucesso
`bankAccountName`	string	Nome da instituição (ex.: `"Chase"`)
`accountNumberMasked`	string	Número da conta mascarado
`routingNumberMasked`	string	Número de roteamento mascarado

Usando o `accountTokenId` em um Pagamento

Uma vez verificada, referencie a conta pelo seu token em um pagamento PULL — sem necessidade de números de conta em texto claro:

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "ach-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"
      }
    }
  }'

Próximos Passos

Vinculando Contas Bancárias com Plaid — Crie o token do Plaid Link e obtenha o accountCheckToken
ACH (Conta Bancária) — Capte fundos usando a conta tokenizada
Check Card Account (ANI) — Valide cartões com AVS, CVC e Visa ANI
Push Transaction — Envie payouts para contas bancárias, cartões, PIX e carteiras