Sender Funding Account

A Funding Account represents the source of funds used by the sender to pay for a transaction. Inyo supports multiple payment methods, all abstracted through a unified ledger system for compliance, reconciliation, and settlement tracking.

Funding Account Statuses

Every funding account has a status field that reflects its current verification state. Your application should handle all four statuses:

Note for API consumers: The status field in funding account responses is returned as a string. The four values above are the complete set of possible statuses.

Status Lifecycle

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

• Card (CARD): Typically transitions Pending → ActionRequired (3DS challenge) → Verified or Rejected. Some low-risk cards may go directly to Verified.
• ACH: Typically transitions Pending → Verified or Rejected after Plaid account verification completes.
• Wallet (WALLET): Usually transitions directly to Verified.

Always check the status before using a funding account in a transaction. Attempting to use a Pending, ActionRequired, or Rejected funding account will result in an error.

Handling Rejected: If a funding account is rejected, it cannot be retried. The sender must create a new funding account with corrected or alternative payment details.

Supported Payment Methods

Creating a Funding Account

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts
Authentication: Agent-level (x-api-key + x-agent-id + x-agent-api-key)

Common Request Fields

Option A: Debit Card

Card payments require a tokenized card number. Raw card details are never sent to the Inyo Core API — they are first sent to the tokenization service (see Tokenizing Cards) to obtain a secure token.

Card Payment Method Fields

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

Example Card Response:

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

3D Secure (3DS) Challenge:

Some cards require additional authentication. If the response returns status: "ActionRequired":

1. Save the funding account locally with a Pending status
2. Display the provided redirectAcsUrl in an iframe for the user to complete the challenge
3. Listen for a postMessage event from the iframe confirming authorization
4. Call GET /organizations/{tenant}/payout/fundingAccounts/{fundingAccountId} to check the updated status
5. If Verified — the card is ready to use for transactions
6. If Rejected — the 3DS challenge failed or the card was declined; prompt the sender to add a different card

For full 3DS implementation details, see Handling 3D Secure.

Option B: ACH (US Bank Account)

ACH funding accounts use Plaid for secure bank account verification. You never send raw routing or account numbers to the Inyo API — instead, the user connects their bank account through Plaid Link, and you pass the resulting tokens to Inyo.

Step 1: Create a Plaid Link Token

Before the user can connect their bank account, your backend must request a Plaid Link token from Inyo.

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts/linkTokens
Authentication: Agent-level (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 '{
  "provider": "PLAID"
}'

Response:

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

Step 2: Launch Plaid Link on the Client

Use the token from Step 1 to initialize Plaid Link in your client application. The user will select their bank and authenticate. On success, Plaid Link returns a public_token and an account_id — these are the values you need for Step 3.

For Plaid Link integration details, refer to the Plaid Link documentation.

Step 3: Register the ACH Funding Account

Pass the Plaid account_id as accountCheckId and the Plaid public_token as accountCheckToken to create the funding account.

ACH Payment Method Fields

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

Example ACH Response:

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

Note that routing and account numbers are returned masked in the response. The full values are never exposed through the API — Plaid handles the secure bank account connection.

Save the returned id — this is the fundingAccountId required when creating a transaction.

Listing Funding Accounts

Endpoint: GET /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts
Authentication: Agent-level

Supports sorting via the sort query parameter. Each item should be in the format field,order where field is one of createdAt and order is either ASC or DESC.

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 this to show the sender their saved payment methods and let them select one for a transaction.

Getting a Funding Account

Endpoint: GET /organizations/{tenant}/payout/fundingAccounts/{fundingAccountId}
Authentication: Agent-level

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 this to check a funding account's current status. Common use cases:

• After a 3DS challenge to confirm Verified or detect Rejected
• Before creating a transaction to ensure the funding account is still Verified
• Polling after ACH account creation to check if verification has completed

Tip: Implement a polling strategy or webhook listener to detect status transitions from Pending → Verified/Rejected, rather than relying on the user to manually refresh.

How Funding Works in the Transaction Lifecycle

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

All Endpoints

Interactive API Documentation