Primeiros Passos

Este guia orienta você no envio da sua primeira transação internacional no sandbox da Inyo. Ao final, você terá uma remessa funcional de um remetente nos EUA para um destinatário internacional.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Credenciais de sandbox fornecidas pela Inyo durante o onboarding:
  • tenant — O identificador da sua organização
  • x-api-key — Chave de API primária (nível de tenant)
  • x-agent-id — O UUID do seu agente
  • x-agent-api-key — Chave de API de nível de agente
• Acesso de rede configurado — um certificado de cliente TLS mútuo e um IP de saída na allowlist. Veja Conectividade; sem ambos, as requisições falham antes de chegar à API.
• Node.js v18+ (se for executar o projeto de exemplo)
• Um cliente REST (cURL, Postman ou similar)

Ainda não tem credenciais? Entre em contato com nossa equipe de vendas para solicitar acesso ao sandbox.

Ambiente Sandbox

Início Rápido: Sua Primeira Transação

Este passo a passo cobre as etapas mínimas para executar uma remessa USD → BRL no sandbox.

Etapa 1: Criar o Remetente

Registre a pessoa que enviará o dinheiro. Isso aciona a triagem 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 o id retornado — este é o senderId usado durante todo o ciclo de vida da transação.

Etapa 2: Verificar o Nível de Conformidade

Confirme que o remetente atingiu pelo menos o Nível 1 antes de prosseguir.

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

Se currentComplianceLevel.level for LEVEL_0, faltam campos obrigatórios para o remetente. Verifique o array missingFieldsForNextComplianceLevel para ver o que é necessário.

Etapa 3: Obter os Destinos Disponíveis

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

Isso retorna a lista de países para os quais seu tenant está habilitado a enviar, junto com suas moedas.

Etapa 4: Travar uma Cotação de Câmbio

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 o quoteId da resposta e verifique o expireAt. As cotações são válidas por 30 minutos por padrão (configurável por tenant).

Etapa 5: Criar o Destinatário

Primeiro, consulte o schema exigido para o 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"

Em seguida, crie o destinatário usando os campos exigidos pelo schema:

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 o id retornado — este é o recipientId.

Etapa 6: Vincular a Conta Bancária do Destinatário

Consulte o schema da conta e, em seguida, vincule a conta bancária:

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 o id retornado — este é o recipientAccountId.

Etapa 7: Registrar a Fonte de Financiamento do Remetente

Você pode financiar transações com um cartão de débito ou uma conta bancária ACH (via Plaid).

Opção A: Cartão 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"
    }
  }
}'

Opção B: ACH (via Plaid)

Primeiro, crie um link token do Plaid e, em seguida, conclua o fluxo do Plaid Link no client para obter o accountCheckId e o accountCheckToken. Veja Conta de Financiamento do Remetente para o fluxo 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 o id retornado — este é o fundingAccountId.

Etapa 8: Executar a Transação

Vincule todos os IDs e envie:

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

A maioria dos tenants tem o device fingerprinting habilitado (o padrão) — deviceData.fingerprint e deviceData.userIpAddress passam a ser obrigatórios, e você deve sempre enviar visitor junto com o fingerprint. Veja Transação — Device Fingerprint.

Uma resposta bem-sucedida retorna HTTP 202 com o objeto completo da transação, incluindo complianceStatus, payoutStatus, detalhes da taxa de câmbio e o objeto receipt contendo as divulgações exigidas por lei. Se o cartão exigir 3D Secure, a resposta também traz paymentStatus: "ActionRequired" e uma redirectAcsUrl — veja Tratando o 3D Secure.

O Que Vem a Seguir?

• Configure webhooks para receber atualizações de status da transação em tempo real
• Revise o ciclo de vida da transação para entender as transições de status
• Explore os níveis de conformidade para construir fluxos de KYC progressivos
• Use os testes no sandbox para forçar transições de status e simular cenários de conformidade

Problemas Comuns

Feedback e Suporte

Estamos melhorando continuamente esta documentação. Para feedback, dúvidas ou problemas técnicos:

• Entre em contato com nossa equipe de vendas
• Referência interativa da API
• Projeto de exemplo no GitHub