Cuenta de Fondeo del Remitente

Una Cuenta de Fondeo representa la fuente de fondos que utiliza el remitente para pagar una transacción. Inyo admite múltiples métodos de pago, todos abstraídos a través de un sistema de libro mayor unificado para el cumplimiento, la conciliación y el seguimiento de la liquidación.

Estados de la Cuenta de Fondeo

Cada cuenta de fondeo tiene un campo status que refleja su estado de verificación actual. Su aplicación debe manejar los cuatro estados:

Nota para los consumidores de la API: El campo status en las respuestas de cuenta de fondeo se devuelve como una cadena. Los cuatro valores anteriores son el conjunto completo de estados posibles.

Ciclo de Vida de los Estados

                         ┌──────────────┐
                         │   Pending    │
                         └──────┬───────┘
                                │
                    ┌───────────┼───────────┐
                    ▼           │           ▼
           ┌───────────────┐   │   ┌───────────────┐
           │ActionRequired │   │   │   Verified    │
           └───────┬───────┘   │   └───────────────┘
                   │           │
           ┌───────┼───────┐   │
           ▼               ▼   ▼
   ┌───────────────┐   ┌───────────────┐
   │   Verified    │   │   Rejected    │
   └───────────────┘   └───────────────┘

• Tarjeta (CARD): Típicamente transiciona Pending → ActionRequired (desafío 3DS) → Verified o Rejected. Algunas tarjetas de bajo riesgo pueden pasar directamente a Verified.
• ACH: Típicamente transiciona Pending → Verified o Rejected una vez que se completa la verificación de cuenta de Plaid.
• Billetera (WALLET): Usualmente transiciona directamente a Verified.

Verifique siempre el estado antes de usar una cuenta de fondeo en una transacción. Intentar usar una cuenta de fondeo en estado Pending, ActionRequired o Rejected resultará en un error.

Manejo de Rejected: Si una cuenta de fondeo es rechazada, no puede reintentarse. El remitente debe crear una nueva cuenta de fondeo con datos de pago corregidos o alternativos.

Métodos de Pago Admitidos

Creación de una Cuenta de Fondeo

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts
Autenticación: A nivel de agente (x-api-key + x-agent-id + x-agent-api-key)

Campos Comunes de la Solicitud

Opción A: Tarjeta de Débito

Los pagos con tarjeta requieren un número de tarjeta tokenizado. Los datos crudos de la tarjeta nunca se envían a la Core API de Inyo — primero se envían al servicio de tokenización (vea Tokenización de Tarjetas) para obtener un token seguro.

Campos del Método de Pago con Tarjeta

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$SENDER_ID/fundingAccounts \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "000000001",
  "asset": "USD",
  "nickname": "My USD card",
  "paymentMethod": {
    "type": "CARD",
    "ipAddress": "127.0.0.1",
    "token": "d5a41e06-e3dc-448f-b2bb-ff8dc0ed1b93",
    "bin": "541333",
    "schemeId": "MASTERCARD",
    "lastFourDigits": "3303",
    "billingAddress": {
      "countryCode": "US",
      "stateCode": "CA",
      "city": "LAKEWOOD",
      "line1": "4429 CANDLEWOOD ST",
      "line2": "Some line 2 address",
      "zipcode": "90712"
    }
  }
}'

Ejemplo de Respuesta para Tarjeta:

{
  "id": "3e1463df-9414-433b-91e9-b7b21d06e095",
  "createdAt": "2025-08-25T16:03:42",
  "asset": "USD",
  "nickname": "",
  "token": "9a7574a9-c93b-458e-ab59-9c34697d2ddc",
  "bin": "520000",
  "schemeId": "MASTERCARD",
  "lastFourDigits": "2235",
  "billingAddressId": "cf92a897-cbda-4350-8930-cb335da08ac6",
  "type": "CARD",
  "status": "Verified",
  "statusMessage": "Test card USD funding account",
  "externalId": null,
  "tenantId": "inyo",
  "representative": {
    "id": "57104187-3c70-4d43-867d-c47b4a6961eb",
    "type": "PARTICIPANT"
  }
}

Desafío 3D Secure (3DS):

Algunas tarjetas requieren autenticación adicional. Si la respuesta devuelve status: "ActionRequired":

1. Guarde la cuenta de fondeo localmente con un estado Pending
2. Muestre la redirectAcsUrl proporcionada en un iframe para que el usuario complete el desafío
3. Escuche un evento postMessage del iframe que confirme la autorización
4. Llame a GET /organizations/{tenant}/payout/fundingAccounts/{fundingAccountId} para verificar el estado actualizado
5. Si es Verified — la tarjeta está lista para usarse en transacciones
6. Si es Rejected — el desafío 3DS falló o la tarjeta fue rechazada; solicite al remitente que agregue una tarjeta diferente

Para los detalles completos de implementación de 3DS, vea Manejo de 3D Secure.

Opción B: ACH (Cuenta Bancaria de EE. UU.)

Las cuentas de fondeo ACH utilizan Plaid para la verificación segura de la cuenta bancaria. Usted nunca envía números de ruta o de cuenta crudos a la API de Inyo — en su lugar, el usuario conecta su cuenta bancaria a través de Plaid Link, y usted pasa los tokens resultantes a Inyo.

Paso 1: Crear un Link Token de Plaid

Antes de que el usuario pueda conectar su cuenta bancaria, su backend debe solicitar un link token de Plaid a Inyo.

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts/linkTokens
Autenticación: A nivel de agente (x-api-key + x-agent-id + x-agent-api-key)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$SENDER_ID/fundingAccounts/linkTokens \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{}'

El participante debe tener un número de teléfono registrado — la creación del link token de Plaid lo requiere.

Respuesta:

{
  "token": "link-sandbox-c2ad1be1-20fe-4944-a8f7-2d64b89412f1",
  "expireAt": "2025-11-26T13:46:42Z",
  "requestId": "Jc6pgl5mY3tse0P"
}

Paso 2: Lanzar Plaid Link en el Cliente

Use el token del Paso 1 para inicializar Plaid Link en su aplicación cliente. El usuario seleccionará su banco y se autenticará. Si tiene éxito, Plaid Link devuelve un public_token y un account_id — estos son los valores que necesita para el Paso 3.

Para los detalles de integración de Plaid Link, consulte la documentación de Plaid Link.

Paso 3: Registrar la Cuenta de Fondeo ACH

Pase el account_id de Plaid como accountCheckId y el public_token de Plaid como accountCheckToken para crear la cuenta de fondeo.

Campos del Método de Pago ACH (Plaid)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$SENDER_ID/fundingAccounts \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "000000002",
  "asset": "USD",
  "nickname": "My USD ACH funding account",
  "paymentMethod": {
    "type": "ACH",
    "countryCode": "US",
    "accountCheckId": "zXn435xnnJsZBjq3WjA5T7ZeRmdZyotJMNjbA",
    "accountCheckToken": "public-sandbox-0446ca14-0234-4475-afe2-9daf1871755d"
  }
}'

Ejemplo de Respuesta ACH:

{
  "id": "94800c36-ce22-42ed-a45c-00dde5bd1f9f",
  "createdAt": "2025-11-26T13:46:42",
  "asset": "USD",
  "nickname": "My USD ACH funding account",
  "countryCode": "US",
  "bankName": "Tartan Bank",
  "routingNumber": "*****1533",
  "accountNumber": "************1111",
  "type": "ACH",
  "status": "Verified",
  "statusMessage": "Test ACH USD funding account",
  "externalId": "000000002",
  "tenantId": "inyo",
  "representative": {
    "id": "57104187-3c70-4d43-867d-c47b4a6961eb",
    "type": "PARTICIPANT"
  },
  "accountTokenId": "access-sandbox-96027a8a-c796-4298-b867-3b82726faf16"
}

Tenga en cuenta que los números de ruta y de cuenta se devuelven enmascarados en la respuesta. Los valores completos nunca se exponen a través de la API — Plaid maneja la conexión segura de la cuenta bancaria.

Guarde el id devuelto — este es el fundingAccountId requerido al crear una transacción.

Opción C: ACH con Datos Bancarios Directos

Dependiendo de su acuerdo de integración, es posible que pueda registrar una cuenta bancaria de EE. UU. directamente con los números de ruta y de cuenta, omitiendo la verificación de Plaid:

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$SENDER_ID/fundingAccounts \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "000000003",
  "asset": "USD",
  "nickname": "Direct ACH account",
  "paymentMethod": {
    "type": "ACH",
    "countryCode": "US",
    "routingNumber": "021000021",
    "accountNumber": "123456789012",
    "accountType": "CHECKING"
  }
}'

Las cuentas con datos directos se registran inmediatamente con estado Verified — no se ejecuta ningún paso de verificación externa. Como no hay una verificación de titularidad bancaria, esta opción suele reservarse para tenants B2B; consulte con su gerente de cuenta si está habilitada para usted.

Listado de Cuentas de Fondeo

Endpoint: GET /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts
Autenticación: A nivel de agente

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$SENDER_ID/fundingAccounts \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Use esto para mostrar al remitente sus métodos de pago guardados y permitirle seleccionar uno para una transacción.

Obtener una Cuenta de Fondeo

Endpoint: GET /organizations/{tenant}/payout/fundingAccounts/{fundingAccountId}
Autenticación: A nivel de agente

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/fundingAccounts/$FUNDING_ACCOUNT_ID \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Use esto para verificar el estado actual de una cuenta de fondeo. Casos de uso comunes:

• Después de un desafío 3DS para confirmar Verified o detectar Rejected
• Antes de crear una transacción para asegurarse de que la cuenta de fondeo siga en Verified
• Sondeo (polling) después de la creación de una cuenta ACH para verificar si la verificación se completó

Consejo: Implemente una estrategia de sondeo o un listener de webhook para detectar las transiciones de estado de Pending → Verified/Rejected, en lugar de depender de que el usuario actualice manualmente.

Cómo Funciona el Fondeo en el Ciclo de Vida de la Transacción

1. Sender selects payment method  →  Use existing or create new funding account
2. Transaction submitted          →  Funds are debit-locked from the funding source
3. Compliance approved            →  Funds are collected (captured)
4. Payout processed               →  Funds settled to recipient via payout network
5. Transaction recorded           →  Ledger entry created for reconciliation

Todos los Endpoints

Documentación Interactiva de la API