> ## Documentation Index > Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Save Program Bank Account > Persist a linked bank account at the program level (used for program funding operations). Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. ## OpenAPI ````yaml specs/ingo-banking-merchant-ledgering.yaml POST /program/bank-accounts/save openapi: 3.1.0 info: title: Ingo Banking API v3 version: 3.2.8 summary: Customer-facing Banking-as-a-Service API for tenant integrations. description: > The Ingo Banking API v3 lets partner programs create users and businesses, verify identities, issue routable bank accounts and cards, move money, and retrieve transaction and balance information. This specification covers 82 operations organised across 10 functional areas: Onboarding, Manage Merchants, Link Accounts, VBAN, Move Money, Balance, Business Contacts, Reports, Program, and Cards (user and business flows). ## Authentication Ingo Banking API requests require both HMAC-SHA512 authentication and a program API key on every request. **Ingo Banking API credentials (provisioned by your Ingo integration manager):** | Credential | Where used | Notes | |---|---|---| | HMAC username | `Authorization` header `username` field | Distinct from `api_key` | | HMAC secret | Used locally to compute the signature | Provisioned by your Ingo integration manager. Never transmit this value — store it in a secrets manager or environment variable, never in source code | | `api_key` | JSON request body field or `api_key` HTTP header | Your program API key — the Banking API equivalent of `participant_id` in IngoPay. Required on every request | Both the HMAC `Authorization` header and the `api_key` are required on every request — they serve complementary roles. The HMAC signature authenticates the request integrity and caller identity. The `api_key` identifies the program account being acted upon. The `api_key` may be passed as the `api_key` HTTP header (preferred) or as a field in the JSON request body. Examples in this documentation use the body placement. **Algorithm requirement:** New integrations must use HMAC-SHA512. Legacy integrations using HMAC-SHA256 remain supported but are encouraged to upgrade. MD5 and SHA-1 are not accepted and will be rejected. See the Ingo API Authentication Guide for string-to-sign construction, body hashing requirements, and timestamp validation rules. ## Environments Replace the base URL placeholder shown in the `servers` list with the environment URL provided to you (sandbox or production) by the product team. ## Response envelopes Every response uses a standard envelope: - Success: `{ "status": "success", "message": "...", "data": { ... } }` - Error: `{ "status": "error", "message": "...", "data": { ... }, "status_code": { "status_code": 1000, "error_type": "NOT_FOUND", ... } }` ## Error codes Errors use a numeric code family: - 1000 - 1005 NOT_FOUND - 1010 - 1014 INVALID_STATE - 1020 - 1026 VALIDATION - 1030 - 1034 SYSTEM_ERROR - 1040 - 1042 SECURITY - 1050 - 1053 PROCESSING ## Entity ID prefixes All entity IDs use a prefixed format: `user-`, `buss-`, `wllt-`, `rbac-`, `vacc-`, `rcrd-`, `ltra-`, `prog-`, `bown-`, `bcus-`. contact: name: Ingo Banking Platform API Support license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.sdev.banking.ingopayments.tech/api/v4 description: Sandbox - url: https://api.banking.ingopayments.tech/api/v4 description: Production security: - HmacAuth: [] ApiKeyAuth: [] tags: - name: Onboarding description: >- Create users and businesses; upload owners and documents; trigger identity verification. - name: Manage Merchants description: >- List, view and update businesses, business representatives, owners and metadata. - name: Link Accounts description: >- Link external bank accounts to users and businesses via Plaid or the hosted IPG flow. - name: VBAN description: >- Issue, list and view virtual/routable bank accounts (VBANs/RBAs) for businesses and for the program. - name: Move Money description: Top ups, payouts and book transfers between routable accounts. - name: Balance description: >- Balance queries for users, businesses and the program master routable account. - name: Business Contacts description: >- Business contact (customer/vendor) directory and per-contact transaction history. - name: Reports description: >- Ledger transaction listings, single-transaction lookup, export, and payment-intent history. - name: Program description: >- Program-level linked accounts, master routable account, funded advances, user/business admin. - name: Cards description: >- Routable card issuance and lifecycle for both users and business cardholders. paths: /program/bank-accounts/save: post: tags: - Program summary: Save a linked bank account on the program description: > Persist a linked bank account at the program level (used for program funding operations). Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. operationId: saveProgramLinkedAccount requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - idempotent_key - first_name - last_name - account_number - routing_number properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. user_id: $ref: '#/components/schemas/EntityIdUser' description: >- Identifier of the target user. Required when the endpoint operates on a specific user. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. first_name: type: string description: First name. last_name: type: string description: Last name. account_number: type: string description: Bank account number (5-20 digits). routing_number: type: string description: ABA routing number (9 digits). postal_code: type: string description: 5-digit US ZIP code. country: type: string description: ISO 3166-1 alpha-2 country code. state: type: string description: ISO 3166-2 two-letter state/region code. city: type: string description: City. address_one: type: string description: Street address line 1. fingerprint: type: string description: Tokenised fingerprint representing the linked account. examples: postman_example: summary: Add External Bank to Program value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef idempotent_key: idp-9f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8 first_name: Alex last_name: Rivera account_number: '8001234567' routing_number: '123456789' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true properties: items: type: array items: $ref: '#/components/schemas/LinkedBankAccount' pagination: $ref: '#/components/schemas/Pagination' '400': description: Validation or business-rule error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: EntityIdUser: type: string description: User entity id; prefix `user-`. example: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef SuccessEnvelope: type: object required: - status - message properties: status: type: string enum: - success message: type: string example: operation completed data: description: Endpoint-specific payload; shape varies per operation. LinkedBankAccount: type: object properties: id: type: string example: bbac-... account_number_last_4: type: string example: '6789' routing_number: type: string example: '123456789' bank_name: type: string source_platform: type: string enum: - plaid - ipg created_at: $ref: '#/components/schemas/Timestamp' Pagination: type: object properties: page: type: integer minimum: 1 example: 1 per_page: type: integer minimum: 1 maximum: 500 example: 25 total: type: integer example: 100 sort: type: string example: created_at:desc search: type: string example: jane ErrorEnvelope: type: object required: - status - message properties: status: type: string enum: - error message: type: string example: Something went wrong data: description: >- Optional error context (for example validation field errors or missing ids). status_code: $ref: '#/components/schemas/ErrorCode' Timestamp: type: string format: date-time example: '2026-04-16T12:34:56.000Z' ErrorCode: type: object description: Structured error code family (1000 to 1060). properties: status_code: type: integer example: 1000 error_type: type: string enum: - NOT_FOUND - INVALID_STATE - VALIDATION - SYSTEM_ERROR - SECURITY - PROCESSING message: type: string example: Resource not found description: type: string example: The requested resource does not exist securitySchemes: HmacAuth: type: http scheme: hmac-sha512 description: > All requests must be authenticated using an HMAC-signed Authorization header. Ingo Money requires HMAC-SHA512 for all new integrations. SHA-512 provides a significantly larger internal state and output length than SHA-256, making it substantially more resistant to length-extension attacks and brute-force preimage attempts — properties that matter for financial API traffic. Legacy integrations using HMAC-SHA256 remain supported but are encouraged to upgrade. MD5 and SHA-1 are not accepted and will be rejected. Authorization header format: Authorization: hmac username="YOUR_HMAC_USERNAME", algorithm="hmac-sha512", headers="request-line x-date content-type content-length content-sha512", signature="BASE64_SIGNATURE" See the Ingo API Authentication Guide for signature construction details. ApiKeyAuth: type: apiKey in: header name: api_key description: > Program API key identifying your integration. Pass as the `api_key` HTTP header (preferred) or as an `api_key` field in the JSON request body. Required on every request in addition to the HMAC Authorization header. ````