Conta de Financiamento do Remetente

Uma Conta de Financiamento (Funding Account) representa a fonte de fundos usada pelo remetente para pagar por uma transação. A Inyo suporta múltiplos métodos de pagamento, todos abstraídos por um sistema unificado de ledger para conformidade, reconciliação e rastreamento de liquidação.

Status da Conta de Financiamento

Toda conta de financiamento tem um campo status que reflete seu estado atual de verificação. Sua aplicação deve tratar os quatro status:

Nota para consumidores da API: O campo status nas respostas de conta de financiamento é retornado como string. Os quatro valores acima são o conjunto completo de status possíveis.

Ciclo de Vida dos Status

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

• Cartão (CARD): Tipicamente transiciona Pending → ActionRequired (desafio 3DS) → Verified ou Rejected. Alguns cartões de baixo risco podem ir diretamente para Verified.
• ACH: Tipicamente transiciona Pending → Verified ou Rejected após a conclusão da verificação de conta do Plaid.
• Carteira (WALLET): Normalmente transiciona diretamente para Verified.

Sempre verifique o status antes de usar uma conta de financiamento em uma transação. Tentar usar uma conta de financiamento Pending, ActionRequired ou Rejected resultará em erro.

Tratando Rejected: Se uma conta de financiamento for rejeitada, não é possível tentar novamente com ela. O remetente deve criar uma nova conta de financiamento com dados de pagamento corrigidos ou alternativos.

Métodos de Pagamento Suportados

Criando uma Conta de Financiamento

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts
Autenticação: Nível de agente (x-api-key + x-agent-id + x-agent-api-key)

Campos Comuns da Requisição

Opção A: Cartão de Débito

Pagamentos com cartão exigem um número de cartão tokenizado. Os dados brutos do cartão nunca são enviados à Inyo Core API — eles são primeiro enviados ao serviço de tokenização (veja Tokenizando Cartões) para obter um token seguro.

Campos do Método de Pagamento com Cartão

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

Exemplo de Resposta de Cartão:

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

Desafio 3D Secure (3DS):

Alguns cartões exigem autenticação adicional. Se a resposta retornar status: "ActionRequired":

1. Salve a conta de financiamento localmente com status Pending
2. Exiba a redirectAcsUrl fornecida em um iframe para o usuário completar o desafio
3. Escute um evento postMessage do iframe confirmando a autorização
4. Chame GET /organizations/{tenant}/payout/fundingAccounts/{fundingAccountId} para verificar o status atualizado
5. Se Verified — o cartão está pronto para ser usado em transações
6. Se Rejected — o desafio 3DS falhou ou o cartão foi recusado; solicite ao remetente que adicione um cartão diferente

Para todos os detalhes de implementação do 3DS, veja Tratando o 3D Secure.

Opção B: ACH (Conta Bancária dos EUA)

Contas de financiamento ACH usam o Plaid para verificação segura de conta bancária. Você nunca envia números brutos de routing ou de conta para a API da Inyo — em vez disso, o usuário conecta sua conta bancária pelo Plaid Link e você passa os tokens resultantes para a Inyo.

Passo 1: Crie um Link Token do Plaid

Antes de o usuário poder conectar sua conta bancária, seu backend deve solicitar um Link token do Plaid à Inyo.

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts/linkTokens
Autenticação: Nível 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 '{}'

O participante deve ter um número de telefone cadastrado — a criação do Link token do Plaid exige isso.

Resposta:

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

Passo 2: Abra o Plaid Link no Cliente

Use o token do Passo 1 para inicializar o Plaid Link na sua aplicação cliente. O usuário selecionará seu banco e fará a autenticação. Em caso de sucesso, o Plaid Link retorna um public_token e um account_id — estes são os valores necessários para o Passo 3.

Para detalhes de integração do Plaid Link, consulte a documentação do Plaid Link.

Passo 3: Registre a Conta de Financiamento ACH

Passe o account_id do Plaid como accountCheckId e o public_token do Plaid como accountCheckToken para criar a conta de financiamento.

Campos do Método de Pagamento 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"
  }
}'

Exemplo de Resposta 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"
}

Observe que os números de routing e de conta são retornados mascarados na resposta. Os valores completos nunca são expostos pela API — o Plaid cuida da conexão segura com a conta bancária.

Guarde o id retornado — este é o fundingAccountId exigido ao criar uma transação.

Opção C: ACH com Dados Bancários Diretos

Dependendo do seu acordo de integração, você pode registrar uma conta bancária dos EUA diretamente com números de routing e de conta, pulando a verificação do 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"
  }
}'

Contas com dados diretos são registradas imediatamente com status Verified — nenhuma etapa de verificação externa é executada. Como não há checagem de titularidade bancária, essa opção normalmente é reservada a tenants B2B; consulte seu gerente de conta para saber se está habilitada para você.

Listando Contas de Financiamento

Endpoint: GET /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts
Autenticação: Nível 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 este endpoint para mostrar ao remetente seus métodos de pagamento salvos e permitir que ele selecione um para uma transação.

Consultando uma Conta de Financiamento

Endpoint: GET /organizations/{tenant}/payout/fundingAccounts/{fundingAccountId}
Autenticação: Nível 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 este endpoint para verificar o status atual de uma conta de financiamento. Casos de uso comuns:

• Após um desafio 3DS, para confirmar Verified ou detectar Rejected
• Antes de criar uma transação, para garantir que a conta de financiamento ainda está Verified
• Fazer polling após a criação de uma conta ACH para verificar se a verificação foi concluída

Dica: Implemente uma estratégia de polling ou um listener de webhook para detectar transições de status de Pending → Verified/Rejected, em vez de depender de o usuário atualizar manualmente.

Como o Financiamento Funciona no Ciclo de Vida da Transação

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 os Endpoints

Documentação Interativa da API