--- description: >- Link a funding source (bank account or wallet) to a sender entity to cover remittance disbursements. --- # 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: | Status | Description | Can Be Used for Transactions? | | ------ | ----------- | ----------------------------- | | `Pending` | Account has been created but verification is not yet complete (e.g., waiting for Plaid account verification or initial processing). | No | | `ActionRequired` | Additional action is needed from the user — typically a 3D Secure (3DS) authentication challenge for card payments. See [Handling 3D Secure](../payments-gateway/apis/payment/pulling-funds/cards/authorizing/handling-3d-secure.md). | No | | `Verified` | Account has been fully verified and is ready to fund transactions. | Yes | | `Rejected` | Verification failed — the card was declined, 3DS authentication failed, or the bank account could not be verified. The sender must add a new funding account. | No | > **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 | Method | Type Value | Description | Speed | | ------ | ---------- | ----------- | ----- | | Debit Card | `CARD` | Tokenized card payment via AFT (Account Funding Transaction) | Instant | | ACH | `ACH` | US bank transfer that uses Plaid verification | Varies according to destination bank | | Wallet | `WALLET` | Internal wallet / P2P balance | Instant | *** ### 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 | Field | Type | Required | Description | | ----- | ---- | -------- | ----------- | | `externalId` | string | Yes | Your internal reference for this funding source | | `asset` | string | Yes | Currency code — must be `USD` | | `nickname` | string | No | Display name (e.g., "My Visa Debit") | | `paymentMethod` | object | Yes | Payment method details (varies by type — see options below) | *** #### 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](../payments-gateway/apis/tokenizing-cards.md)) to obtain a secure token. ##### Card Payment Method Fields | Field | Type | Required | Description | | ----- | ---- | -------- | ----------- | | `type` | string | Yes | Must be `CARD` | | `ipAddress` | string | Yes | IP address of the cardholder's device | | `token` | string | Yes | Tokenized card number from the tokenization service | | `schemeId` | string | Yes | Card network identifier (e.g., `VISA`, `MASTERCARD`) | | `bin` | string | Yes | First 6 digits of the card number (Bank Identification Number) | | `lastFourDigits` | string | Yes | Last 4 digits of the card number | | `billingAddress` | object | Yes | Cardholder billing address | | `billingAddress.countryCode` | string | Yes | Two-letter ISO country code (e.g., `US`) | | `billingAddress.stateCode` | string | No | State/province code (e.g., `CA`) | | `billingAddress.city` | string | No | City name | | `billingAddress.line1` | string | No | Street address line 1 | | `billingAddress.line2` | string | No | Street address line 2 | | `billingAddress.zipcode` | string | No | Postal/ZIP code | ```bash curl --request POST \ --url https://api.sandbox.inyoplatform.com/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:** ```json { "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](../payments-gateway/apis/payment/pulling-funds/cards/authorizing/handling-3d-secure.md). *** #### 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`) | Field | Type | Required | Description | | ----- | ---- | -------- | ----------- | | `provider` | string | No | Account verification provider — defaults to `PLAID` | ```bash curl --request POST \ --url https://api.sandbox.inyoplatform.com/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:** ```json { "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](https://plaid.com/docs/link/). ##### 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 | Field | Type | Required | Description | | ----- | ---- | -------- | ----------- | | `type` | string | Yes | Must be `ACH` | | `countryCode` | string | Yes | Must be `US` | | `accountCheckId` | string | Yes | Plaid `account_id` returned from Plaid Link | | `accountCheckToken` | string | Yes | Plaid `public_token` returned from Plaid Link | ```bash curl --request POST \ --url https://api.sandbox.inyoplatform.com/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:** ```json { "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`. ```bash curl --request GET \ --url https://api.sandbox.inyoplatform.com/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 ```bash curl --request GET \ --url https://api.sandbox.inyoplatform.com/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 | Operation | Method | Endpoint | | --------- | ------ | -------- | | Create Plaid link token | `POST` | `/organizations/{tenant}/payout/participants/{participantId}/fundingAccounts/linkTokens` | | Create funding account | `POST` | `/organizations/{tenant}/payout/participants/{participantId}/fundingAccounts` | | List funding accounts | `GET` | `/organizations/{tenant}/payout/participants/{participantId}/fundingAccounts` | | Get funding account | `GET` | `/organizations/{tenant}/payout/fundingAccounts/{fundingAccountId}` | [Interactive API Documentation](https://dev-api.inyoglobal.com/sandbox/#tag/payout_Funding-Account-Resource)