Primeros Pasos

Esta guía lo lleva a través del envío de su primera transacción transfronteriza en el sandbox de Inyo. Al final, tendrá una remesa funcional de un remitente en EE. UU. a un destinatario internacional.

Requisitos Previos

Antes de comenzar, asegúrese de tener:

• Credenciales de sandbox proporcionadas por Inyo durante el onboarding:
  • tenant — El identificador de su organización
  • x-api-key — Clave de API principal (a nivel de tenant)
  • x-agent-id — El UUID de su agente
  • x-agent-api-key — Clave de API a nivel de agente
• Acceso de red configurado — un certificado de cliente TLS mutuo y una IP de egreso en la lista de permitidos. Vea Conectividad; sin ambos, las solicitudes fallan antes de llegar a la API.
• Node.js v18+ (si va a ejecutar el proyecto de ejemplo)
• Un cliente REST (cURL, Postman o similar)

¿Aún no tiene credenciales? Póngase en contacto con nuestro equipo de ventas para solicitar acceso al sandbox.

Entorno de Sandbox

Inicio Rápido: Su Primera Transacción

Este recorrido cubre los pasos mínimos para ejecutar una remesa USD → BRL en el sandbox.

Paso 1: Crear el Remitente

Registre a la persona que enviará el dinero. Esto activa el screening de KYC/AML.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "birthDate": "1990-01-15",
  "phoneNumber": "+15551234567",
  "gender": "Male",
  "address": {
    "countryCode": "US",
    "stateCode": "CA",
    "city": "San Francisco",
    "line1": "123 Market St",
    "zipcode": "94105"
  },
  "documents": [
    {
      "type": "SSN",
      "document": "123456789",
      "countryCode": "US"
    }
  ]
}'

Guarde el id devuelto — este es el senderId que se usa durante todo el ciclo de vida de la transacción.

Paso 2: Verificar el Nivel de Cumplimiento

Confirme que el remitente haya alcanzado al menos el Level 1 antes de continuar.

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/participants/$SENDER_ID/complianceLevels \
  --header "x-api-key: $API_KEY"

Si currentComplianceLevel.level es LEVEL_0, al remitente le faltan campos requeridos. Revise el arreglo missingFieldsForNextComplianceLevel para ver qué se necesita.

Paso 3: Obtener los Destinos Disponibles

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

Esto devuelve la lista de países a los que su tenant está habilitado para enviar, junto con sus monedas.

Paso 4: Fijar una Cotización de FX

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/quotes \
  --header 'Content-Type: application/json' \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "fromCurrency": "USD",
  "toCurrency": "BRL",
  "amount": 100.00
}'

Guarde el quoteId de la respuesta y verifique su expireAt. Las cotizaciones son válidas por 30 minutos por defecto (configurable por tenant).

Paso 5: Crear el Destinatario

Primero, obtenga el esquema requerido para el país de destino:

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

Luego cree el destinatario usando los campos requeridos por el esquema:

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "Maria",
  "lastName": "Silva",
  "phoneNumber": "+5511999998888",
  "documents": [
    {
      "type": "CPF",
      "document": "12345678901",
      "countryCode": "BR"
    }
  ]
}'

Guarde el id devuelto — este es el recipientId.

Paso 6: Vincular la Cuenta Bancaria del Destinatario

Obtenga el esquema de la cuenta y luego vincule la cuenta bancaria:

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "recipient-acct-001",
  "asset": "BRL",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "BR",
    "bankCode": "001",
    "routingNumber": "0001",
    "accountNumber": "123456",
    "accountType": "CHECKING"
  }
}'

Guarde el id devuelto — este es el recipientAccountId.

Paso 7: Registrar la Fuente de Fondeo del Remitente

Puede fondear las transacciones con una tarjeta de débito o una cuenta bancaria ACH (vía Plaid).

Opción A: Tarjeta de Débito

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$SENDER_ID/fundingAccounts \
  --header 'Content-Type: application/json' \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "funding-001",
  "asset": "USD",
  "nickname": "My Debit Card",
  "paymentMethod": {
    "type": "CARD",
    "ipAddress": "127.0.0.1",
    "token": "tok_sandbox_test_token",
    "bin": "541333",
    "schemeId": "MASTERCARD",
    "lastFourDigits": "3303",
    "billingAddress": {
      "countryCode": "US",
      "stateCode": "CA",
      "city": "San Francisco",
      "line1": "123 Market St",
      "zipcode": "94105"
    }
  }
}'

Opción B: ACH (vía Plaid)

Primero, cree un link token de Plaid y luego complete el flujo de Plaid Link en el cliente para obtener el accountCheckId y el accountCheckToken. Vea Cuenta de Fondeo del Remitente para el flujo ACH completo.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$SENDER_ID/fundingAccounts \
  --header 'Content-Type: application/json' \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "funding-002",
  "asset": "USD",
  "nickname": "My Checking Account",
  "paymentMethod": {
    "type": "ACH",
    "countryCode": "US",
    "accountCheckId": "PLAID_ACCOUNT_ID",
    "accountCheckToken": "PLAID_PUBLIC_TOKEN"
  }
}'

Guarde el id devuelto — este es el fundingAccountId.

Paso 8: Ejecutar la Transacción

Vincule todos los ID y envíe:

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/fx/transactions \
  --header 'Content-Type: application/json' \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "senderId": "'$SENDER_ID'",
  "recipientId": "'$RECIPIENT_ID'",
  "fundingAccountId": "'$FUNDING_ACCOUNT_ID'",
  "recipientAccountId": "'$RECIPIENT_ACCOUNT_ID'",
  "quoteId": "'$QUOTE_ID'",
  "deviceData": {
    "userIpAddress": "127.0.0.1",
    "fingerprint": "<fingerprint-requestId>",
    "visitor": "<fingerprint-visitorId>"
  }
}'

La mayoría de los tenants tienen el fingerprinting de dispositivo habilitado (el valor por defecto) — en ese caso deviceData.fingerprint y deviceData.userIpAddress son requeridos, y siempre debe enviar visitor junto con el fingerprint. Vea Transacción — Huella del Dispositivo.

Una respuesta exitosa devuelve HTTP 202 con el objeto completo de la transacción, incluyendo complianceStatus, payoutStatus, los detalles de la tasa de cambio y el objeto receipt que contiene las divulgaciones legalmente requeridas. Si la tarjeta requiere 3D Secure, la respuesta también incluye paymentStatus: "ActionRequired" y una redirectAcsUrl — vea Manejo de 3D Secure.

¿Qué Sigue?

• Configure webhooks para recibir actualizaciones de estado de las transacciones en tiempo real
• Revise el ciclo de vida de la transacción para entender las transiciones de estado
• Explore los niveles de cumplimiento para construir flujos de KYC progresivos
• Use las pruebas en sandbox para forzar transiciones de estado y simular escenarios de cumplimiento

Problemas Comunes

Comentarios y Soporte

Mejoramos continuamente esta documentación. Para comentarios, preguntas o problemas técnicos:

• Póngase en contacto con nuestro equipo de ventas
• Referencia interactiva de la API
• Proyecto de ejemplo en GitHub