Vinculación de Cuentas Bancarias con Plaid

Plaid permite que un cliente conecte su cuenta bancaria de EE. UU. iniciando sesión con sus credenciales bancarias, en lugar de escribir a mano un número de ruta y de cuenta. El gateway envuelve el flujo de Plaid Link con:

El resultado de una vinculación de Plaid completada es una cuenta bancaria tokenizada que usted pasa a un pago como paymentMethod.accountTokenId — el mismo flujo PULL que ACH, pero sin manipular números bancarios crudos.

Cuándo usar Plaid vs. ACH directo: Use Plaid cuando quiera verificación instantánea de la cuenta y una mejor experiencia de conversión, y para evitar recolectar/almacenar números de ruta y de cuenta crudos. Use ACH directo cuando ya posea datos bancarios validados.

Resumen del Flujo

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

Paso 1 — Crear un Link Token de Plaid

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

Headers:

Cuerpo de la Solicitud

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

Respuesta (200)

Una llamada exitosa devuelve el Link token de Plaid usado para inicializar Plaid Link en el cliente.

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

Paso 2 — Abrir Plaid Link (Lado del Cliente)

Inicialice Plaid Link con el token devuelto arriba. El cliente se autentica con su banco y elige una cuenta. Consulte la documentación de Plaid Link para los SDK de web, iOS, Android y React Native.

const handler = Plaid.create({
  token: token, // el `token` de POST /providers/plaid
  onSuccess: (publicToken, metadata) => {
    // Vinculación completa — Plaid devuelve un public token + el id de la cuenta seleccionada.
    // Envíe ambos a su backend para verificar y tokenizar la cuenta.
    verifyAccount(publicToken, metadata.account_id);
  },
  onExit: (err, metadata) => { /* manejar el abandono */ }
});
handler.open();

El callback onSuccess de Plaid le entrega un public token y el account id seleccionado — estos se convierten en accountCheckToken y accountCheckId en el siguiente paso.

Paso 3 — Verificar y Tokenizar la Cuenta

Intercambie el public token de Plaid por un accountTokenId reutilizable vía Check Account. Esto verifica la cuenta y devuelve el token que usted usa en los pagos.

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

La respuesta devuelve status: "VERIFIED" y el accountTokenId que usará para debitar fondos:

{
  "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 la referencia completa de campos de solicitud y respuesta.

Paso 4 — Debitar Fondos Usando la Cuenta Vinculada

Use el accountTokenId del Paso 3 en un pago PULL estándar. No se envían números de ruta/cuenta — el token referencia la cuenta 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"
      }
    }
  }'

La respuesta del pago es idéntica a la de un débito ACH directo — los pagos ACH se capturan automáticamente, por lo que un resultado exitoso devuelve el estado CAPTURED.

Qué Sigue

• ACH (Cuenta Bancaria) — Debite fondos con números de ruta/cuenta crudos (sin Plaid)
• Payment — Operaciones de pago principales y estructura del payload
• Webhooks — Reciba actualizaciones de estado de pago de forma asíncrona