Check Account

La API Check Account verifica una cuenta bancaria vinculada a través de Plaid y devuelve un accountTokenId reutilizable que puedes usar para extraer fondos vía ACH — sin manejar nunca números de cuenta y de ruta en crudo.

Es el paso de finalización del flujo de vinculación bancaria con Plaid: después de que el cliente completa Plaid Link, intercambias el public token de Plaid (accountCheckToken) y el id de cuenta (accountCheckId) por una cuenta tokenizada y verificada.

Usa este endpoint para:

Tokenizar una cuenta vinculada con Plaid en un accountTokenId para reutilizarlo en pagos
Verificar la titularidad de la cuenta antes de enviar un pago de tipo pull
Reducir transacciones fallidas detectando temprano datos de cuenta inválidos

Nota: Esta API no realiza cargos a la cuenta ni crea un pago. Solo verifica y tokeniza la cuenta.

Endpoint

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

Encabezados:

Encabezado	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Solicitud

Objeto Raíz

Campo	Tipo	Requerido	Descripción
`externalPaymentId`	string	Sí	Tu identificador único para esta solicitud de verificación (clave de idempotencia)
`sender`	object	Sí	Datos del remitente — envuelve el método de pago a verificar

Objeto `sender`

Campo	Tipo	Requerido	Descripción
`paymentMethod`	object	Sí	La cuenta vinculada con Plaid a verificar y tokenizar

`sender.paymentMethod`

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`"BANK_DEPOSIT"`
`countryCode`	string	Sí	País del banco (ISO Alpha-2, p. ej. `"US"`)
`accountCheckToken`	string	Sí	El public token de Plaid devuelto por Plaid Link en el cliente (`public-sandbox-...` / `public-production-...`)
`accountCheckId`	string	Sí	El id de cuenta de Plaid que el cliente seleccionó en Plaid Link

Ejemplo de Solicitud

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

Respuesta — Verificada (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 de la Respuesta

Campo	Tipo	Descripción
`paymentId`	string	Identificador único de Inyo para esta verificación
`parentPaymentId`	string	Identificador raíz (igual a `paymentId` en una verificación independiente)
`externalPaymentId`	string	El identificador que proporcionaste en la solicitud
`accountTokenId`	string	La cuenta tokenizada. Pásalo como `sender.paymentMethod.accountTokenId` en una solicitud de pago para extraer fondos
`created`	string	Marca de tiempo de la verificación
`approved`	boolean	Si la cuenta se verificó exitosamente
`accessToken`	string	Token de acceso de Plaid asociado al item vinculado (guárdalo de forma segura si necesitas volver a consultar la cuenta)
`status`	string	Estado de la verificación — `VERIFIED` en caso de éxito
`bankAccountName`	string	Nombre de la institución (p. ej. `"Chase"`)
`accountNumberMasked`	string	Número de cuenta enmascarado
`routingNumberMasked`	string	Número de ruta enmascarado

Uso del `accountTokenId` en un Pago

Una vez verificada, referencia la cuenta por su token en un pago PULL — sin necesidad de números de cuenta en crudo:

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

Qué Sigue

Vinculación de Cuentas Bancarias con Plaid — Crea el token de Plaid Link y obtén el accountCheckToken
ACH (Cuenta Bancaria) — Extrae fondos usando la cuenta tokenizada
Check Card Account (ANI) — Valida tarjetas con AVS, CVC y Visa ANI
Push Transaction — Envía payouts a cuentas bancarias, tarjetas, PIX y billeteras