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: /user/create: post: operationId: createUser summary: Create a user entity tags: - Onboarding description: > Create a new end-user entity. Identity fields are required and the record is created in a pending KYC state. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - first_name - last_name - phone_number - address_one - city - postal_code - country - state - email properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. first_name: type: string description: First name. last_name: type: string description: Last name. ssn: type: string description: Social security number. Encrypted at rest. date_of_birth: $ref: '#/components/schemas/DateOfBirth' description: Date of birth in YYYY-MM-DD format. address_one: type: string description: Street address line 1. city: type: string description: City. 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. email: $ref: '#/components/schemas/Email' description: Email address. middle_name: type: string description: Middle name. phone_number: $ref: '#/components/schemas/Phone' description: Phone number in E.164 format. address_two: type: string description: Street address line 2. username: type: string description: Chosen username for the user. terms_accepted: type: boolean description: True to confirm the end user accepted the program terms. meta_data: $ref: '#/components/schemas/Metadata' description: List of {name, value} pairs to persist alongside the entity. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Optional. When supplied, the created user is also linked as a contact of this business. is_vendor: type: boolean description: >- Optional. When `business_id` is supplied, marks the created business contact as a vendor. examples: postman_example: summary: Create Entity value: api_key: YOUR_API_KEY email: jane.doe@example.com first_name: Alex middle_name: '' last_name: Rivera phone_number: '+15555551234' postal_code: '30044' country: US state: TX city: Anytown address_one: 100 Innovation Way address_two: Suite 100 username: janedoe date_of_birth: '1980-04-20' ssn: XXXXXXXXX terms_accepted: true meta_data: - name: external_ref value: customer-001 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/User' 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' /business/create: post: operationId: createBusiness summary: Create a business entity tags: - Onboarding description: > Create a new business entity tied to the authorised user. Identity and representative fields should be provided to progress KYB verification. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_name - email - phone_number - business_industry - country - state - city - business_address - incorporated_date - incorporated_state 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 representative user. Required. business_name: type: string description: Legal business name. name: type: string description: >- Optional display name. Defaults to `business_name` when omitted. email: $ref: '#/components/schemas/Email' description: Primary email address for the business. business_email: type: string description: 'Business onboarding field: business email.' business_phone: type: string description: 'Business onboarding field: business phone.' business_phone_number: type: string description: 'Business onboarding field: business phone number.' phone_number: $ref: '#/components/schemas/Phone' description: Phone number in E.164 format. support_email: type: string description: 'Business onboarding field: support email.' support_phone_number: type: string description: 'Business onboarding field: support phone number.' website: type: string description: 'Business onboarding field: website.' business_address: type: string description: 'Business onboarding field: business address.' business_address_2: type: string description: 'Business onboarding field: business address 2.' naics_code: type: string description: 'Business onboarding field: naics code.' business_type: type: string description: 'Business onboarding field: business type.' business_industry: type: string description: 'Business onboarding field: business industry.' 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. zipcode: type: string description: 5-digit US ZIP code. business_description: type: string description: 'Business onboarding field: business description.' incorporated_date: type: string description: 'Business onboarding field: incorporated date.' incorporated_state: type: string description: 'Business onboarding field: incorporated state.' ein: type: string description: 'Business onboarding field: ein.' logo: type: string description: 'Business onboarding field: logo.' business_logo: type: string description: 'Business onboarding field: business logo.' ach_engine: type: string description: 'Business onboarding field: ach engine.' business_rep_name: type: string description: Legal name of the business representative. business_rep_email: type: string description: 'Business onboarding field: business rep email.' business_rep_job_title: type: string description: 'Business onboarding field: business rep job title.' business_rep_dob: type: string description: 'Business onboarding field: business rep dob.' business_rep_address: type: string description: 'Business onboarding field: business rep address.' business_rep_address_2: type: string description: 'Business onboarding field: business rep address 2.' business_rep_zipcode: type: string description: 'Business onboarding field: business rep zipcode.' business_rep_city: type: string description: 'Business onboarding field: business rep city.' business_rep_phone: type: string description: 'Business onboarding field: business rep phone.' business_rep_ssn: type: string description: 'Business onboarding field: business rep ssn.' business_rep_website: type: string description: 'Business onboarding field: business rep website.' business_rep_country: type: string description: 'Business onboarding field: business rep country.' business_rep_state: type: string description: 'Business onboarding field: business rep state.' delivery_fufilment: type: string description: 'Business onboarding field: delivery fufilment.' support_address_one: type: string description: 'Business onboarding field: support address one.' support_address_two: type: string description: 'Business onboarding field: support address two.' support_country: type: string description: 'Business onboarding field: support country.' support_city: type: string description: 'Business onboarding field: support city.' support_zipcode: type: string description: 'Business onboarding field: support zipcode.' support_state: type: string description: 'Business onboarding field: support state.' business_proof: type: string description: 'Business onboarding field: business proof.' personal_id: type: string description: 'Business onboarding field: personal id.' send_email_notification: type: string description: 'Business onboarding field: send email notification.' otp: type: string description: 'Business onboarding field: otp.' security: type: string description: 'Business onboarding field: security.' meta_data: $ref: '#/components/schemas/Metadata' description: List of {name, value} pairs to persist alongside the entity. examples: postman_example: summary: Create Business value: api_key: YOUR_API_KEY name: Judo INC60 user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef email: johndoe6@example.com phone_number: '+15555551234' support_email: support@example.com support_phone_number: '+15555555678' business_address: 100 Innovation Way business_address_2: Suite 200 naics_code: '541611' business_type: LLC country: US ein: 12-3456789 business_industry: Consulting incorporated_date: '2020-01-01' incorporated_state: CA business_description: A consulting firm offering expert advice. zipcode: '00000' city: Los Angeles state: CA business_name: Doe60 LLC business_email: info@example.com business_phone: '+15555559876' business_rep_name: Jane Smith business_rep_email: janesmith@example.com business_rep_job_title: Business Representative business_rep_dob: '1985-05-15' business_rep_address: 100 Innovation Way business_rep_address_2: Apt 5B business_rep_zipcode: '00000' business_rep_city: Los Angeles business_rep_phone: '+15555550001' business_rep_country: US business_rep_state: CA meta_data: - name: external_ref value: merchant-001 - name: source value: partner-portal 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/Business' 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' /business/add-business-owner: post: operationId: addBusinessOwner summary: Add an owner to a business tags: - Onboarding description: > Add a beneficial owner to an existing business. Required for KYB verification of businesses that have owners above the disclosure threshold. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - name - email - address - phone_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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. name: type: string description: Display name. email: $ref: '#/components/schemas/Email' description: Email address. address: type: string description: Street address. phone_number: $ref: '#/components/schemas/Phone' description: Phone number in E.164 format. ssn: type: string description: Social security number. Encrypted at rest. selfie: type: string description: >- URL or token of a selfie image used for identity verification. role: type: string description: >- Role of the owner within the business (for example director, officer). ownership_percent: type: number description: Ownership percentage held by this owner (0 to 100). street: type: string description: Street address. state: type: string description: ISO 3166-2 two-letter state/region code. city: type: string description: City. zipcode: type: string description: 5-digit US ZIP code. country: type: string description: ISO 3166-1 alpha-2 country code. date_of_birth: $ref: '#/components/schemas/DateOfBirth' description: Date of birth in YYYY-MM-DD format. examples: postman_example: summary: Add business owner value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e name: Jane Doe email: jane.doe@example.com address: 123 Example Street phone_number: '+15555551234' 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/BusinessOwner' 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' /business/add-business-owner-document: post: operationId: addBusinessOwnerDocument summary: Upload a document for a business owner tags: - Onboarding description: > Attach an identity document (for example a drivers license) to a business owner record. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - business_owner_id - doc_type - doc_url 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. business_owner_id: type: string description: Identifier of the target business owner. doc_type: type: string description: >- Document type (for example ein_document, articles_of_incorporation, drivers_license). doc_url: type: string format: uri description: >- Public or tokenised URL where the uploaded document can be retrieved. doc_back_url: type: string format: uri description: Optional URL for the back side of a two-sided document. examples: postman_example: summary: Add business owner document value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e business_owner_id: bown-4a5d6e7f-8901-2345-6789-abcdef012345 doc_type: articles_of_incorporation doc_url: https://example.com/docs/sample.pdf 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/BusinessDocument' 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' /business/add-business-document: post: operationId: addBusinessDocument summary: Upload a document for a business tags: - Onboarding description: > Attach a supporting document (articles of incorporation, EIN letter, etc.) to a business record. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - doc_type - doc_url 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. doc_type: type: string description: >- Document type (for example ein_document, articles_of_incorporation, drivers_license). doc_url: type: string format: uri description: >- Public or tokenised URL where the uploaded document can be retrieved. doc_back_url: type: string format: uri description: Optional URL for the back side of a two-sided document. examples: postman_example: summary: Add Business Document value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e doc_type: articles_of_incorporation doc_url: https://example.com/docs/sample.pdf 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/BusinessDocument' 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' /business/delete-business-document: post: operationId: deleteBusinessDocument summary: Remove a document from a business tags: - Onboarding description: > Remove a previously uploaded business document. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id_generic 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id_generic: type: string description: Identifier of the target resource. examples: postman_example: summary: Delete Business Document value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /business/send-verification-request: post: operationId: sendBusinessVerificationRequest summary: Submit a business for KYB verification tags: - Onboarding description: > Submit the business to the configured identity-verification provider for KYB review. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. examples: postman_example: summary: Verify Business value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /user/send-verification-request: post: operationId: sendUserVerificationRequest summary: Submit a user for KYC verification tags: - Onboarding description: > Submit the user to the configured identity-verification provider for KYC review. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. examples: postman_example: summary: Verify User value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /user/update: post: operationId: updateUser summary: Update a user tags: - Onboarding description: > Update mutable fields on an existing user. Omit fields to leave them unchanged. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. first_name: type: string description: First name. middle_name: type: string description: Middle name. last_name: type: string description: Last name. phone_number: $ref: '#/components/schemas/Phone' description: Phone number in E.164 format. 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. address_two: type: string description: Street address line 2. username: type: string description: Chosen username for the user. date_of_birth: $ref: '#/components/schemas/DateOfBirth' description: Date of birth in YYYY-MM-DD format. ssn: type: string description: Social security number. Encrypted at rest. examples: postman_example: summary: Update user entity value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef first_name: Alex middle_name: '' last_name: Rivera phone_number: '+15555551234' city: Anytown state: TX country: US postal_code: '30044' date_of_birth: '2000-04-20' address_one: 100 Innovation Way address_two: Suite 100 username: janedoe ssn: XXXXXXXXX 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/User' 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' /user/check-verification-request: post: operationId: checkUserVerificationRequest summary: Poll the status of a user verification tags: - Onboarding description: > Return the latest KYC verification state for the user. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. examples: postman_example: summary: Check user verification value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /user/get: post: operationId: getUser summary: Get a single user tags: - Onboarding description: > Retrieve a user record by identifier. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. examples: postman_example: summary: Get User Entity value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/User' 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' /business/program/get-all: post: operationId: listBusinesses summary: List businesses for the program tags: - Manage Merchants description: > List all businesses under the program with optional free-text search and pagination. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. name: type: string description: Display name. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get All Businesses value: api_key: YOUR_API_KEY 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/Business' 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' /business/get: post: operationId: getBusiness summary: Get a single business tags: - Manage Merchants description: > Retrieve a business record by identifier. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. examples: postman_example: summary: Get Single Business value: api_key: YOUR_API_KEY business_id: buss-6ef45cba-3d9a-4eaf-ab3f-f446426a3a35 user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/Business' 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' /business/get-business-documents: post: operationId: getBusinessDocuments summary: List documents attached to a business tags: - Manage Merchants description: > Return the set of supporting documents uploaded for a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. examples: postman_example: summary: Get Business Documents value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/BusinessDocument' 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' /business/update: post: operationId: updateBusiness summary: Update a business tags: - Manage Merchants description: > Update a business record. All fields are optional; omit to leave unchanged. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. email: $ref: '#/components/schemas/Email' description: Email address. business_email: type: string description: 'Business onboarding field: business email.' business_phone: type: string description: 'Business onboarding field: business phone.' business_phone_number: type: string description: 'Business onboarding field: business phone number.' phone_number: $ref: '#/components/schemas/Phone' description: Phone number in E.164 format. support_email: type: string description: 'Business onboarding field: support email.' support_phone_number: type: string description: 'Business onboarding field: support phone number.' website: type: string description: 'Business onboarding field: website.' business_address: type: string description: 'Business onboarding field: business address.' business_address_2: type: string description: 'Business onboarding field: business address 2.' naics_code: type: string description: 'Business onboarding field: naics code.' business_type: type: string description: 'Business onboarding field: business type.' business_industry: type: string description: 'Business onboarding field: business industry.' 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. zipcode: type: string description: 5-digit US ZIP code. business_description: type: string description: 'Business onboarding field: business description.' incorporated_date: type: string description: 'Business onboarding field: incorporated date.' incorporated_state: type: string description: 'Business onboarding field: incorporated state.' ein: type: string description: 'Business onboarding field: ein.' business_rep_name: type: string description: Legal name of the business representative. business_rep_email: type: string description: 'Business onboarding field: business rep email.' business_rep_job_title: type: string description: 'Business onboarding field: business rep job title.' business_rep_dob: type: string description: 'Business onboarding field: business rep dob.' business_rep_address: type: string description: 'Business onboarding field: business rep address.' business_rep_address_2: type: string description: 'Business onboarding field: business rep address 2.' business_rep_zipcode: type: string description: 'Business onboarding field: business rep zipcode.' business_rep_city: type: string description: 'Business onboarding field: business rep city.' business_rep_phone: type: string description: 'Business onboarding field: business rep phone.' business_rep_ssn: type: string description: 'Business onboarding field: business rep ssn.' business_rep_website: type: string description: 'Business onboarding field: business rep website.' business_rep_country: type: string description: 'Business onboarding field: business rep country.' business_rep_state: type: string description: 'Business onboarding field: business rep state.' support_address_one: type: string description: 'Business onboarding field: support address one.' support_address_two: type: string description: 'Business onboarding field: support address two.' support_country: type: string description: 'Business onboarding field: support country.' support_city: type: string description: 'Business onboarding field: support city.' support_zipcode: type: string description: 'Business onboarding field: support zipcode.' support_state: type: string description: 'Business onboarding field: support state.' examples: postman_example: summary: Update Business value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e business_name: Demo LLC phone_number: '+12345678901' dba: TEST Demo INC business_address: 100 Innovation Way business_address_2: Suite 200 business_industry: Consulting business_description: A consulting firm offering expert advice. zipcode: '00000' state: CA support_email: support@example.com support_phone_number: '+12345678901' business_email: info@example.com support_address_one: 100 Innovation Way support_address_two: Floor 3 support_country: US support_city: Los Angeles support_zipcode: '00000' business_proof: https://www.examplebusiness.com/proof.png personal_id: https://www.examplebusiness.com/id.png support_state: TX city: Los Angeles business_type: LLC country: US logo: https://www.examplebusiness.com/logo.png ein: 12-3456789 incorporated_date: '2020-01-01' incorporated_state: CA meta_data: - name: external_ref value: merchant-002 - name: source value: partner-portal 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/Business' 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' /business/update-business-rep: post: operationId: updateBusinessRep summary: Update the representative of a business tags: - Manage Merchants description: > Update the business representative contact and identity fields. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. business_rep_country: type: string description: 'Business onboarding field: business rep country.' business_rep_state: type: string description: 'Business onboarding field: business rep state.' business_rep_name: type: string description: Legal name of the business representative. business_rep_address: type: string description: 'Business onboarding field: business rep address.' address_2: type: string description: Second line of street address. business_rep_city: type: string description: 'Business onboarding field: business rep city.' business_rep_dob: type: string description: 'Business onboarding field: business rep dob.' business_rep_phone: type: string description: 'Business onboarding field: business rep phone.' business_rep_ssn: type: string description: 'Business onboarding field: business rep ssn.' business_rep_website: type: string description: 'Business onboarding field: business rep website.' business_rep_zipcode: type: string description: 'Business onboarding field: business rep zipcode.' business_rep_email: type: string description: 'Business onboarding field: business rep email.' business_rep_job_title: type: string description: 'Business onboarding field: business rep job title.' examples: postman_example: summary: Update Business Rep value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e business_rep_name: John Doe business_rep_email: john.doe@example.com business_rep_job_title: Lead Dev business_rep_dob: '2000-12-10' business_rep_address: 100 Innovation Way business_rep_address_2: Suite 200 business_rep_zipcode: '00000' business_rep_city: Anytown business_rep_phone: '+15555550001' business_rep_ssn: XXXXXXXXX business_rep_website: https://example.com business_rep_country: US business_rep_state: TX 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/Business' 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' /business/meta-data/add: post: operationId: addBusinessMetadataBulk summary: Add a batch of metadata entries to a business tags: - Manage Merchants description: > Attach multiple metadata key/value pairs to a business in a single request. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. meta_data: $ref: '#/components/schemas/Metadata' description: List of {name, value} pairs to persist alongside the entity. examples: postman_example: summary: Update Business Meta-data value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e meta_data: - name: external_ref value: ref-001 - name: external_ref_secondary value: ref-002 responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /business/get-business-owners: post: operationId: listBusinessOwners summary: List owners of a business tags: - Manage Merchants description: > List the beneficial owners registered on the business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. examples: postman_example: summary: Get business owners value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/BusinessOwner' 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' /business/delete-business-owner: post: operationId: deleteBusinessOwner summary: Remove an owner from a business tags: - Manage Merchants description: > Remove a beneficial owner from a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - business_owner_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. business_owner_id: type: string description: Identifier of the target business owner. examples: postman_example: summary: Delete Business owner value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e business_owner_id: bown-4a5d6e7f-8901-2345-6789-abcdef012345 responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /business/delete-business-owner-document: post: operationId: deleteBusinessOwnerDocument summary: Remove a document from a business owner tags: - Manage Merchants description: > Remove a previously uploaded document from a business-owner record. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id_generic - business_owner_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id_generic: type: string description: Identifier of the target resource. business_owner_id: type: string description: Identifier of the target business owner. examples: postman_example: summary: Delete business owner document value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 business_owner_id: bown-4a5d6e7f-8901-2345-6789-abcdef012345 responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /business/get-business-owner-documents: post: operationId: listBusinessOwnerDocuments summary: List documents for a business owner tags: - Manage Merchants description: > List documents attached to a specific business owner. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - business_owner_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. business_owner_id: type: string description: Identifier of the target business owner. examples: postman_example: summary: Get business owner document value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e business_owner_id: bown-4a5d6e7f-8901-2345-6789-abcdef012345 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/BusinessDocument' 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' /metadata/business/get-all: post: operationId: listBusinessMetadata summary: List metadata attached to a business tags: - Manage Merchants description: > List key/value metadata entries attached to a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get Business meta-data value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /metadata/update: post: operationId: updateMetadata summary: Update a metadata record tags: - Manage Merchants description: > Update a previously created metadata record. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - metadata_id properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. metadata_id: type: string description: Identifier of the metadata record to update. metadata_name: type: string description: Metadata key. metadata_value: type: string description: Metadata value. examples: postman_example: summary: Update existing metadata value: api_key: YOUR_API_KEY metadata_id: meta-1234abcd-5678-90ef-ghij-klmnopqrstuv responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /business/bank-accounts/sync-from-external-platform: post: operationId: syncBusinessLinkedAccount summary: Link an external bank account to a business tags: - Link Accounts description: > Persist an external bank account (Plaid, IPG) against a business using a tokenised link from the source platform. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id - source_platform - source_platform_token properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. source_platform: type: string enum: - plaid - ipg description: External platform the linked account is sourced from. source_platform_token: type: string description: >- Linking token (for example a Plaid processor token) issued by the source platform. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. examples: postman_example: summary: Sync Business DDA from external platform value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e source_platform: plaid source_platform_token: plaid-processor-token-xyz 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' /business/bank-accounts/get-all: post: operationId: listBusinessLinkedAccounts summary: List linked bank accounts for a business tags: - Link Accounts description: > List external bank accounts linked to a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get All Business Linked Accounts value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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' /users/bank-accounts/get-all: post: operationId: listUserLinkedAccounts summary: List linked bank accounts for a user tags: - Link Accounts description: > List external bank accounts linked to a user. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get a users linked bank account value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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' /business/ipg/connect-bank-account: post: operationId: linkBusinessAccountIPG summary: Link a business bank account via the hosted IPG flow tags: - Link Accounts description: > Persist a business bank account captured via the hosted IPG (Instant Payment Gateway) flow. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id - idempotent_key - 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. name: type: string description: Display 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: Link Business Bank Account value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e idempotent_key: idp-9f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8 name: Jane Doe 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' /users/bank-accounts/sync-from-external-platform: post: operationId: syncUserLinkedAccount summary: Link an external bank account to a user tags: - Link Accounts description: > Persist an external bank account (Plaid, IPG) against a user. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - source_platform - source_platform_token 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. source_platform: type: string enum: - plaid - ipg description: External platform the linked account is sourced from. source_platform_token: type: string description: >- Linking token (for example a Plaid processor token) issued by the source platform. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. examples: postman_example: summary: Sync User DDA from external platform value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef source_platform: plaid source_platform_token: plaid-processor-token-xyz 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' /integrations/plaid/business/generate-linked-token: post: operationId: generatePlaidLinkTokenBusiness summary: Create a Plaid Link token for a business tags: - Link Accounts description: > Return a short-lived Plaid Link token that the client can use to launch Plaid Link for the given business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. examples: postman_example: summary: 'PLAID: Generate Link Token' value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /integrations/plaid/business/get-accounts: post: operationId: getPlaidAccountsBusiness summary: Fetch Plaid accounts for a business tags: - Link Accounts description: > Exchange a Plaid public token and return the list of accounts available on that Plaid Item for a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id - public_token properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. public_token: type: string description: >- Short-lived public token returned by the Plaid Link flow; exchanged server-side for an access token. examples: postman_example: summary: 'PLAID: Get Account' value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e public_token: example_public_token responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /business/bank-accounts/remove: post: operationId: removeBusinessLinkedAccount summary: Remove a linked bank account from a business tags: - Link Accounts description: > Remove a linked bank account from a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id - id_generic properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id_generic: type: string description: Identifier of the target resource. examples: postman_example: summary: Remove business linked account value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /users/bank-accounts/remove: post: operationId: removeUserLinkedAccount summary: Remove a linked bank account from a user tags: - Link Accounts description: > Remove a linked bank account from a user. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id_generic 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. id_generic: type: string description: Identifier of the target resource. examples: postman_example: summary: Remove user linked account value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /users/bank-accounts/save: post: operationId: saveUserLinkedAccount summary: Save a bank account for a user (raw entry) tags: - Link Accounts description: > Persist a bank account on a user using raw account/routing numbers. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. 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: Link User Account 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' /business/routable-bank-accounts/get-single: post: operationId: getBusinessRoutableAccount summary: Get a single routable bank account for a business tags: - VBAN description: > Retrieve a single routable bank account (VBAN) by identifier for a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id_generic 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id_generic: type: string description: Identifier of the target resource. examples: postman_example: summary: Get Issued Business Account value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 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/RoutableBankAccount' 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' /business/routable-bank-accounts/issue: post: operationId: issueBusinessRoutableAccount summary: Issue a new routable bank account for a business tags: - VBAN description: > Issue a new routable bank account (VBAN) for a business. The program must have VBAN issuance enabled for businesses. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. examples: postman_example: summary: Issue Account to Business value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/RoutableBankAccount' 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' /business/routable-bank-accounts/get-all: post: operationId: listBusinessRoutableAccounts summary: List routable bank accounts for a business tags: - VBAN description: > List all routable bank accounts (VBANs) attached to a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get all Issued account value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/RoutableBankAccount' 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' /program/routable-bank-accounts/get: post: operationId: getProgramRoutableAccount summary: Get the program master routable bank account tags: - VBAN description: > Return the program master routable bank account record. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. examples: postman_example: summary: Get Program VBAN value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/RoutableBankAccount' 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' /payout/business/routable-bank-account-to-linked-bank-account: post: operationId: payoutBusinessRoutableToLinkedAccount summary: Pay out from a business routable account to a linked bank account tags: - Move Money description: > Pay out funds from a business routable bank account to an external linked bank account. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - amount - source_account_id - destination_account_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. amount: $ref: '#/components/schemas/Money' description: >- Monetary amount as a decimal string with two decimal places (for example "100.00"). Must be positive. source_account_id: type: string description: Source account identifier for the payout. destination_account_id: type: string description: Destination account identifier for the payout. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. reference: type: string description: >- Optional external reference string stored on the resulting transaction. description: type: string description: Free-form description attached to the resulting transaction. source_name: type: string description: >- Display name of the funding source (for receipts and webhook events). descriptive_purpose: type: string description: >- Short description of the transaction purpose surfaced to downstream processors. participant_id: type: string description: >- External participant identifier tracked with the transaction. examples: postman_example: summary: Business Payout from Issued account value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e amount: '100.00' source_account_id: bbac-9abc1234-5678-90ef-klmn-opqrstuv5678 destination_account_id: bbac-9abc1234-5678-90ef-klmn-opqrstuv5678 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/LedgerTransaction' 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' /user/charge-bank-account-fund-business-routable-bank-account: post: operationId: fundBusinessRoutableFromUserLinkedAccount summary: Top up a business routable account from a user linked bank account tags: - Move Money description: > Charge a linked bank account on a user and credit a business routable bank account. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - amount - account_id - receiver_business_id - routable_bank_account_id 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. amount: $ref: '#/components/schemas/Money' description: >- Monetary amount as a decimal string with two decimal places (for example "100.00"). Must be positive. account_id: type: string description: Linked bank account identifier used as funding source. receiver_business_id: $ref: '#/components/schemas/EntityIdBusiness' description: Receiving business identifier. routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: Target routable bank account identifier. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. reference: type: string description: >- Optional external reference string stored on the resulting transaction. description: type: string description: Free-form description attached to the resulting transaction. source_ledger_account_uid: type: string description: Named ledger account uid to debit as the operation source. destination_ledger_account_uid: type: string description: >- Named ledger account uid to credit as the operation destination. source_name: type: string description: >- Display name of the funding source (for receipts and webhook events). descriptive_purpose: type: string description: >- Short description of the transaction purpose surfaced to downstream processors. participant_id: type: string description: >- External participant identifier tracked with the transaction. examples: postman_example: summary: Debit User Credit Business value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef amount: '100.00' account_id: bbac-9abc1234-5678-90ef-klmn-opqrstuv5678 receiver_business_id: example_receiver_business_id routable_bank_account_id: rbac-2b1c0e44-4f2d-9a11-7b23-cc90d1ef8f3a 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/LedgerTransaction' 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' /payout/business/routable-bank-account-to-user-linked-bank-account: post: operationId: payoutBusinessRoutableToUserLinkedAccount summary: Pay out from a business routable account to a user's linked bank account tags: - Move Money description: > Pay out funds from a business routable bank account to the linked bank account of a specified user. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - amount - source_account_id - destination_user_id - destination_account_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. amount: $ref: '#/components/schemas/Money' description: >- Monetary amount as a decimal string with two decimal places (for example "100.00"). Must be positive. source_account_id: type: string description: Source account identifier for the payout. destination_user_id: $ref: '#/components/schemas/EntityIdUser' description: >- Destination user whose linked account/card receives the payout. destination_account_id: type: string description: Destination account identifier for the payout. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. reference: type: string description: >- Optional external reference string stored on the resulting transaction. description: type: string description: Free-form description attached to the resulting transaction. source_name: type: string description: >- Display name of the funding source (for receipts and webhook events). descriptive_purpose: type: string description: >- Short description of the transaction purpose surfaced to downstream processors. participant_id: type: string description: >- External participant identifier tracked with the transaction. examples: postman_example: summary: Business to user payout value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e amount: '100.00' source_account_id: bbac-9abc1234-5678-90ef-klmn-opqrstuv5678 destination_user_id: example_destination_user_id destination_account_id: bbac-9abc1234-5678-90ef-klmn-opqrstuv5678 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/LedgerTransaction' 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' /business/charge-bank-account-fund-business-routable-bank-account: post: operationId: fundBusinessRoutableFromBusinessLinkedAccount summary: >- Top up a business routable account from the business's own linked bank account tags: - Move Money description: > Charge a linked bank account on a business and credit the same business's routable bank account. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - amount - account_id - receiver_business_id - routable_bank_account_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. amount: $ref: '#/components/schemas/Money' description: >- Monetary amount as a decimal string with two decimal places (for example "100.00"). Must be positive. account_id: type: string description: Linked bank account identifier used as funding source. receiver_business_id: $ref: '#/components/schemas/EntityIdBusiness' description: Receiving business identifier. routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: Target routable bank account identifier. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. reference: type: string description: >- Optional external reference string stored on the resulting transaction. description: type: string description: Free-form description attached to the resulting transaction. source_ledger_account_uid: type: string description: Named ledger account uid to debit as the operation source. destination_ledger_account_uid: type: string description: >- Named ledger account uid to credit as the operation destination. source_name: type: string description: >- Display name of the funding source (for receipts and webhook events). descriptive_purpose: type: string description: >- Short description of the transaction purpose surfaced to downstream processors. participant_id: type: string description: >- External participant identifier tracked with the transaction. examples: postman_example: summary: Debit Business Credit Business VBAN value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e amount: '100.00' account_id: bbac-9abc1234-5678-90ef-klmn-opqrstuv5678 receiver_business_id: example_receiver_business_id routable_bank_account_id: rbac-2b1c0e44-4f2d-9a11-7b23-cc90d1ef8f3a 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/LedgerTransaction' 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' /book-transfer/routable-bank-account-to-routable-bank-account-transfer: post: operationId: transferBetweenRoutableAccounts summary: Transfer between two routable bank accounts tags: - Move Money description: > Book transfer between two routable bank accounts (any entity pairing supported). Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - amount - source_entity_id - source_entity_type - source_routable_bank_account_id - destination_entity_id - destination_entity_type - destination_routable_bank_account_id - description - idempotent_key properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. amount: $ref: '#/components/schemas/Money' description: >- Monetary amount as a decimal string with two decimal places (for example "100.00"). Must be positive. source_entity_id: type: string description: >- Identifier of the source entity. Matches `source_entity_type`: a `user-*` id when type is `user`, a `buss-*` id when `business`, or a `prog-*` id when `program`. source_entity_type: type: string enum: - user - business - program description: Type of the source entity. source_routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: >- Source routable bank account identifier. Must belong to the `source_entity_id`. destination_entity_id: type: string description: >- Identifier of the destination entity. Matches `destination_entity_type`: a `user-*` id when type is `user`, a `buss-*` id when `business`, or a `prog-*` id when `program`. destination_entity_type: type: string enum: - user - business - program description: Type of the destination entity. destination_routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: >- Destination routable bank account identifier. Must belong to the `destination_entity_id`. description: type: string description: Free-form description attached to the resulting transaction. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. reference: type: string description: >- Optional external reference string stored on the resulting transaction. metadata: type: object additionalProperties: true description: >- Arbitrary key/value metadata object attached to the operation. examples: postman_example: summary: VBAN Book transfer value: api_key: YOUR_API_KEY amount: '100.00' source_entity_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef source_entity_type: user source_routable_bank_account_id: rbac-2b1c0e44-4f2d-9a11-7b23-cc90d1ef8f3a destination_entity_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e destination_entity_type: business destination_routable_bank_account_id: rbac-9f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8 description: 'Payout for invoice #INV-001' idempotent_key: idp-9f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8 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/LedgerTransaction' 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' /balance/business: post: operationId: getBusinessBalance summary: Get a business balance tags: - Balance description: > Return the available and held balances for a business or for one of its specified accounts. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. user_id_opt: $ref: '#/components/schemas/EntityIdUser' description: Identifier of the target user (optional filter). routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: Target routable bank account identifier. virtual_bank_account_id: type: string description: Virtual bank account identifier to query balance for. extra_wallet_id: type: string description: Secondary wallet identifier to query balance for. examples: postman_example: summary: Get Issued Account Balance value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object properties: available_balance: $ref: '#/components/schemas/Money' pending_balance: $ref: '#/components/schemas/Money' currency: $ref: '#/components/schemas/Currency' '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' /balance/user: post: operationId: getUserBalance summary: Get a user balance tags: - Balance description: > Return the available and held balances for a user or for one of its specified accounts. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. user_id_opt: $ref: '#/components/schemas/EntityIdUser' description: Identifier of the target user (optional filter). routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: Target routable bank account identifier. virtual_bank_account_id: type: string description: Virtual bank account identifier to query balance for. extra_wallet_id: type: string description: Secondary wallet identifier to query balance for. examples: postman_example: summary: Get User Issued Account Balance value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object properties: available_balance: $ref: '#/components/schemas/Money' pending_balance: $ref: '#/components/schemas/Money' currency: $ref: '#/components/schemas/Currency' '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' /business/customers/get-single: post: operationId: getBusinessContact summary: Get a single business contact tags: - Business Contacts description: > Retrieve a single business contact (customer or vendor) by identifier. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id_generic 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id_generic: type: string description: Identifier of the target resource. examples: postman_example: summary: Get single contact in a business value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 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/BusinessContact' 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' /transactions/business-contacts: post: operationId: listBusinessContactTransactions summary: List transactions involving a business's contacts tags: - Business Contacts description: > List ledger transactions where the counterparty is a contact (customer or vendor) of the business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. payment_direction: type: string enum: - credit - debit description: Filter by transaction direction. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get transactions by business contacts value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/LedgerTransaction' 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' /business/customers/get-all: post: operationId: listBusinessContacts summary: List contacts for a business tags: - Business Contacts description: > List contacts (customers or vendors) for a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. type: type: string description: Optional contact type filter. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: GET business contacts value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/BusinessContact' 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' /transactions/report: post: operationId: getTransactionReport summary: Download a transaction report tags: - Reports description: > Generate a program-level transaction report for the given date range and optional direction filter. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - start_date - end_date properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. start_date: type: string format: date-time description: Inclusive lower bound of a date/time range (ISO 8601). end_date: type: string format: date-time description: Inclusive upper bound of a date/time range (ISO 8601). payment_direction: type: string enum: - credit - debit description: Filter by transaction direction. examples: postman_example: summary: Program Transactions report value: api_key: YOUR_API_KEY start_date: '2024-01-01T00:00:00Z' end_date: '2024-01-31T23:59:59Z' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /transactions/business: post: operationId: listBusinessTransactions summary: List ledger transactions for a business tags: - Reports description: > List ledger transaction entries where the business (or one of its routable accounts) is the counterparty. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - business_id properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. payment_direction: type: string enum: - credit - debit description: Filter by transaction direction. routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: Target routable bank account identifier. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get transactions by business Issued account value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/LedgerTransaction' 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' /transactions/single: post: operationId: getLedgerTransaction summary: Get a single ledger transaction tags: - Reports description: > Return a single ledger transaction identified by transaction id, uuid, reference or external id. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id_generic 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. id_generic: type: string description: Identifier of the target resource. payment_direction: type: string enum: - credit - debit description: Filter by transaction direction. examples: postman_example: summary: View single transaction value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 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/LedgerTransaction' 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' /transactions/program: post: operationId: listProgramTransactions summary: List program-level ledger transactions tags: - Reports description: > List ledger transaction entries at the program level with optional direction filter. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. direction: type: string enum: - credit - debit description: Filter by transaction direction. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: All transactions in the program value: api_key: YOUR_API_KEY 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/LedgerTransaction' 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' /payment-intent/program/all: post: operationId: listPaymentIntents summary: List payment intents for the program tags: - Reports description: > List payment intents (pending, settlement-needed, approval-needed and completed) with standard list filters. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. status_str: type: string description: Filter by status value. start_date: type: string format: date-time description: Inclusive lower bound of a date/time range (ISO 8601). end_date: type: string format: date-time description: Inclusive upper bound of a date/time range (ISO 8601). pi_action: $ref: '#/components/schemas/PaymentIntentAction' description: Filter by payment intent action. entity_type: type: string enum: - user - business - program description: Filter by the entity type the payment intent applies to. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. payment_direction: type: string enum: - credit - debit description: Filter by transaction direction. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get all payment intent value: api_key: YOUR_API_KEY 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/PaymentIntent' 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' /program/bank-accounts/save: post: operationId: saveProgramLinkedAccount summary: Save a linked bank account on the program tags: - 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. 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' /program/bank-accounts/remove: post: operationId: removeProgramLinkedAccount summary: Remove a program-level linked bank account tags: - Program description: > Remove a program-level linked bank account. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id_generic 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. id_generic: type: string description: Identifier of the target resource. examples: postman_example: summary: Remove External Bank from Program value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /program/bank-accounts/get-all: post: operationId: listProgramLinkedAccounts summary: List program-level linked bank accounts tags: - Program description: > List the bank accounts linked at the program level. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. examples: postman_example: summary: Get External Program Accounts value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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' /balance/program-master-rba: post: operationId: getProgramMasterRbaBalance summary: Get the program master routable-account balance tags: - Program description: > Return the balance of the program master routable bank account. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. examples: postman_example: summary: Get program VBAN Balance value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object properties: available_balance: $ref: '#/components/schemas/Money' pending_balance: $ref: '#/components/schemas/Money' currency: $ref: '#/components/schemas/Currency' '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' /program/charge-program-bank-account-fund-program-routable-bank-account: post: operationId: fundProgramRoutableFromProgramLinkedAccount summary: Top up the program routable account from a program-level linked account tags: - Program description: > Charge a program-level linked bank account and credit the program routable bank account. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - amount - account_id - routable_bank_account_id 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. amount: $ref: '#/components/schemas/Money' description: >- Monetary amount as a decimal string with two decimal places (for example "100.00"). Must be positive. account_id: type: string description: Linked bank account identifier used as funding source. routable_bank_account_id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' description: Target routable bank account identifier. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. reference: type: string description: >- Optional external reference string stored on the resulting transaction. description: type: string description: Free-form description attached to the resulting transaction. source_ledger_account_uid: type: string description: Named ledger account uid to debit as the operation source. destination_ledger_account_uid: type: string description: >- Named ledger account uid to credit as the operation destination. source_name: type: string description: >- Display name of the funding source (for receipts and webhook events). descriptive_purpose: type: string description: >- Short description of the transaction purpose surfaced to downstream processors. participant_id: type: string description: >- External participant identifier tracked with the transaction. examples: postman_example: summary: Fund program VBAN from program linked Bank value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef amount: '100.00' account_id: bbac-9abc1234-5678-90ef-klmn-opqrstuv5678 routable_bank_account_id: rbac-2b1c0e44-4f2d-9a11-7b23-cc90d1ef8f3a 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/LedgerTransaction' 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' /user/get-all: post: operationId: listUsers summary: List users for the program tags: - Program description: > List all end-user entities under the program with optional email or free-text search and pagination. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. email: $ref: '#/components/schemas/Email' description: Email address. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get all program user entities value: api_key: YOUR_API_KEY 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/User' 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' /program/funds-lent/get: post: operationId: listFundsLent summary: List outstanding or paid program loans tags: - Program description: > List program-funded advances (overdrafts). Filter by status section (outstanding/paid) and search. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. section: type: string enum: - outstanding - paid description: Filter by fund-lent status section. examples: postman_example: summary: Get all overdrafts funded value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/FundLent' 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' /program/funds-lent/mark-as-paid: post: operationId: markFundLentAsPaid summary: Mark a program-funded advance as paid tags: - Program description: > Mark a previously recorded program-funded advance as repaid. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id_generic 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. id_generic: type: string description: Identifier of the target resource. examples: postman_example: summary: Mark overdraft paid value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id_generic: id-1234abcd-5678-90ef-klmn-opqrstuv1234 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/FundLent' 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' /user/block: post: operationId: blockUser summary: Block a user tags: - Program description: > Block a user. Blocked users cannot transact until unblocked. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Block a User Entity value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/User' 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' /user/unblock: post: operationId: unblockUser summary: Unblock a user tags: - Program description: > Unblock a previously blocked user. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. examples: postman_example: summary: Unblock a User entity value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/User' 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' /business/block: post: operationId: blockBusiness summary: Block a business tags: - Program description: > Block a business. Blocked businesses cannot transact until unblocked. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Block a Business entity value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/Business' 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' /business/unblock: post: operationId: unblockBusiness summary: Unblock a business tags: - Program description: > Unblock a previously blocked business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. examples: postman_example: summary: Unblock a business value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e 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/Business' 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' /transactions/program-rba: post: operationId: listProgramMasterRbaTransactions summary: List transactions on the program master routable account tags: - Program description: > List ledger transaction entries posted on the program master routable bank account. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: api_key: type: string description: >- Program API key. Accepted either in the `api_key` HTTP header or as this body field. direction: type: string enum: - credit - debit description: Filter by transaction direction. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Program VBAN Transactions value: api_key: YOUR_API_KEY 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/LedgerTransaction' 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' /balance/program-transaction-summary: post: operationId: getProgramTransactionSummary summary: Summarise program transactions over a date range tags: - Program description: > Return aggregate totals of program transactions bucketed over the given date range. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. start_date: type: string format: date-time description: Inclusive lower bound of a date/time range (ISO 8601). end_date: type: string format: date-time description: Inclusive upper bound of a date/time range (ISO 8601). examples: postman_example: summary: Program Balance Summary value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object additionalProperties: true '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' /user/routable-cards/create: post: operationId: issueUserCard summary: Issue a routable card to a user tags: - Cards description: > Issue a physical or virtual routable card to a user. Physical card issuance requires a shipping address and may optionally reference an existing virtual card id. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - card_type 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. card_type: type: string enum: - physical - virtual description: Requested card form factor. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. shipping_address: type: object description: >- Shipping address object. Required for physical card issuance. properties: street: type: string street2: type: string city: type: string state: type: string description: ISO 3166-2 two-letter state code. zipcode: type: string description: 5-digit US ZIP. country: type: string description: ISO 3166-1 alpha-2 country code. required: - street - city - state - zipcode - country virtual_card_id: type: string description: >- Existing virtual card id to materialise as the physical card (when issuing physical after virtual). examples: postman_example: summary: Issue a Card to a User value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef card_type: virtual 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/Card' 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' /user/routable-cards/get-single: post: operationId: getUserCard summary: Get a single user card tags: - Cards description: > Retrieve a single user card by identifier. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id 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. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. examples: postman_example: summary: Get a single user card value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-ea0f3bfe-d0bd-4c72-bf29-a326b9c6656f 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/Card' 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' /user/routable-cards/get-all: post: operationId: listUserCards summary: List a user's routable cards tags: - Cards description: > List routable cards issued to a user. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id 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. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get all user cards value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/Card' 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' /user/routable-cards/freeze: post: operationId: freezeUserCard summary: Freeze a user card tags: - Cards description: > Freeze (suspend) a user card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id 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. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Freeze a card value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-ea0f3bfe-d0bd-4c72-bf29-a326b9c6656f reason_code: '101' 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/Card' 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' /user/routable-cards/unfreeze: post: operationId: unfreezeUserCard summary: Unfreeze a user card tags: - Cards description: > Unfreeze (resume) a user card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id 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. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Unfreeze Card value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-ea0f3bfe-d0bd-4c72-bf29-a326b9c6656f reason_code: '101' 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/Card' 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' /user/routable-cards/activate: post: operationId: activateUserCard summary: Activate a user card tags: - Cards description: > Activate a user card that was issued in an unactivated state. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id 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. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Activate a card value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-bc4aa5cd-ab0a-4580-ac90-87fd45d4e190 reason_code: '101' 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/Card' 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' /user/routable-cards/reissue: post: operationId: reissueUserCard summary: Reissue a user card tags: - Cards description: > Reissue a user card, either reusing the existing PAN or assigning a new one and optionally terminating the old card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id - reuse_pan 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. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reuse_pan: type: boolean description: >- True to reuse the same PAN on the reissued card, false to assign a new PAN. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. terminate_old_card: type: boolean description: >- When reissuing with a new PAN, whether to terminate the replaced card. shipping_address: type: object description: >- Shipping address object. Required for physical card issuance. properties: street: type: string street2: type: string city: type: string state: type: string description: ISO 3166-2 two-letter state code. zipcode: type: string description: 5-digit US ZIP. country: type: string description: ISO 3166-1 alpha-2 country code. required: - street - city - state - zipcode - country examples: postman_example: summary: Reissue a card value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-417b1398-8eff-4db4-a810-1ffa3dc24c4a card_type: physical terminate_old_card: true reuse_pan: false 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/Card' 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' /user/routable-cards/balance: post: operationId: getUserCardBalance summary: Get the balance on a user card tags: - Cards description: > Return the available balance on a user card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - id 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. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. examples: postman_example: summary: Get Card Balance value: api_key: YOUR_API_KEY user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-417b1398-8eff-4db4-a810-1ffa3dc24c4a responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object properties: available_balance: $ref: '#/components/schemas/Money' pending_balance: $ref: '#/components/schemas/Money' currency: $ref: '#/components/schemas/Currency' '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' /business/routable-cards/create: post: operationId: issueBusinessCard summary: Issue a routable card to a business tags: - Cards description: > Issue a physical or virtual routable card tied to a business cardholder. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - card_type 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. card_type: type: string enum: - physical - virtual description: Requested card form factor. idempotent_key: type: string description: >- Client-supplied idempotency token. Submitting the same key twice returns the first response rather than creating a duplicate transaction. shipping_address: type: object description: >- Shipping address object. Required for physical card issuance. properties: street: type: string street2: type: string city: type: string state: type: string description: ISO 3166-2 two-letter state code. zipcode: type: string description: 5-digit US ZIP. country: type: string description: ISO 3166-1 alpha-2 country code. required: - street - city - state - zipcode - country virtual_card_id: type: string description: >- Existing virtual card id to materialise as the physical card (when issuing physical after virtual). examples: postman_example: summary: Issue card value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef card_type: virtual idempotent_key: idp-9f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8 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/Card' 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' /business/routable-cards/get-all: post: operationId: listBusinessCards summary: List a business's routable cards tags: - Cards description: > List routable cards issued for a business. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. search: type: string description: >- Free-text search filter. Matches common fields on the target collection. page: type: integer minimum: 1 default: 1 description: Page number, 1-indexed. Defaults to 1 when omitted. per_page: type: integer minimum: 1 maximum: 500 default: 10 description: Page size. Defaults to 10 when omitted. examples: postman_example: summary: Get all business cards value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef 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/Card' 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' /business/routable-cards/get-single: post: operationId: getBusinessCard summary: Get a single business card tags: - Cards description: > Retrieve a single business card by identifier. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. examples: postman_example: summary: Get a single business card value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-6c1e4cc4-c158-4d79-86f8-bd9b923f0cfb 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/Card' 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' /business/routable-cards/activate: post: operationId: activateBusinessCard summary: Activate a business card tags: - Cards description: > Activate a business card that was issued in an unactivated state. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Activate a card value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-6c1e4cc4-c158-4d79-86f8-bd9b923f0cfb reason_code: '101' 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/Card' 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' /business/routable-cards/freeze: post: operationId: freezeBusinessCard summary: Freeze a business card tags: - Cards description: > Freeze (suspend) a business card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Freeze a Business Card value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-6c1e4cc4-c158-4d79-86f8-bd9b923f0cfb reason_code: '101' 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/Card' 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' /business/routable-cards/unfreeze: post: operationId: unfreezeBusinessCard summary: Unfreeze a business card tags: - Cards description: > Unfreeze (resume) a business card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. examples: postman_example: summary: Unfreeze a Business Card value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-6c1e4cc4-c158-4d79-86f8-bd9b923f0cfb reason_code: '101' 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/Card' 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' /business/routable-cards/reissue: post: operationId: reissueBusinessCard summary: Reissue a business card tags: - Cards description: > Reissue a business card, either reusing the existing PAN or assigning a new one and optionally terminating the old card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id - reuse_pan 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. reuse_pan: type: boolean description: >- True to reuse the same PAN on the reissued card, false to assign a new PAN. reason_code: type: string description: Short reason code accompanying the state change (optional). reason: type: string description: Free-form reason describing why the state change occurred. terminate_old_card: type: boolean description: >- When reissuing with a new PAN, whether to terminate the replaced card. shipping_address: type: object description: >- Shipping address object. Required for physical card issuance. properties: street: type: string street2: type: string city: type: string state: type: string description: ISO 3166-2 two-letter state code. zipcode: type: string description: 5-digit US ZIP. country: type: string description: ISO 3166-1 alpha-2 country code. required: - street - city - state - zipcode - country examples: postman_example: summary: Reissue a card value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-6c1e4cc4-c158-4d79-86f8-bd9b923f0cfb reuse_pan: false terminate_old_card: false 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/Card' 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' /business/routable-cards/balance: post: operationId: getBusinessCardBalance summary: Get the balance on a business card tags: - Cards description: > Return the available balance on a business card. Authentication: send the program API key either in the `api_key` HTTP header or as an `api_key` JSON body field. requestBody: required: true content: application/json: schema: type: object additionalProperties: true required: - user_id - business_id - id 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. business_id: $ref: '#/components/schemas/EntityIdBusiness' description: >- Identifier of the target business. Required when the endpoint operates on a specific business. id: $ref: '#/components/schemas/EntityIdCard' description: Identifier of the target card. examples: postman_example: summary: Get Card Balance value: api_key: YOUR_API_KEY business_id: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e user_id: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef id: rcrd-6c1e4cc4-c158-4d79-86f8-bd9b923f0cfb responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: type: object properties: available_balance: $ref: '#/components/schemas/Money' pending_balance: $ref: '#/components/schemas/Money' currency: $ref: '#/components/schemas/Currency' '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: 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. schemas: EntityIdUser: type: string description: User entity id; prefix `user-`. example: user-8f3a2b1c-0e44-4f2d-9a11-7b23cc90d1ef EntityIdBusiness: type: string description: Business entity id; prefix `buss-`. example: buss-2ef94c60-5a11-4d72-a3c1-5be7fab0123e EntityIdRoutableBankAccount: type: string description: Routable bank account id; prefix `rbac-`. example: rbac-2b1c0e44-4f2d-9a11-7b23-cc90d1ef8f3a EntityIdCard: type: string description: Routable card id; prefix `rcrd-`. example: rcrd-9a117b23-cc90-d1ef-8f3a-2b1c0e444f2d EntityIdLedgerTransaction: type: string description: Ledger transaction id; prefix `ltra-`. example: ltra-4f2d9a11-7b23-cc90-d1ef-8f3a2b1c0e44 EntityIdPaymentIntent: type: string description: Payment intent id; prefix `ptra-` or `pint-`. example: ptra-cc90d1ef-8f3a-2b1c-0e44-4f2d9a117b23 EntityIdProgram: type: string description: Program id; prefix `prog-`. example: prog-d1ef8f3a-2b1c-0e44-4f2d-9a117b23cc90 Money: type: string description: Decimal money amount as a string with two decimal places. example: '100.00' Currency: type: string enum: - usd - USD example: usd Timestamp: type: string format: date-time example: '2026-04-16T12:34:56.000Z' Phone: type: string example: '+12125551234' Email: type: string format: email example: jane.doe@example.com DateOfBirth: type: string format: date example: '1990-04-15' SSN_Last4: type: string example: '6789' Metadata: type: array description: Key/value metadata pairs to attach to the entity or operation. items: type: object required: - name - value properties: name: type: string example: external_ref value: type: string example: order-123 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 TransactionStatus: type: string enum: - pending - active - complete - completed - deactive - reversal - refund PaymentIntentAction: type: string enum: - instant - approval_needed - settlement_needed - hold - check 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 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. 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' User: type: object additionalProperties: true properties: id: $ref: '#/components/schemas/EntityIdUser' uuid: type: string first_name: type: string example: Jane middle_name: type: string last_name: type: string example: Doe email: $ref: '#/components/schemas/Email' phone_number: $ref: '#/components/schemas/Phone' date_of_birth: $ref: '#/components/schemas/DateOfBirth' address_one: type: string address_two: type: string city: type: string state: type: string country: type: string postal_code: type: string ssn_last_4: $ref: '#/components/schemas/SSN_Last4' status: type: string example: active kyc_status: type: string example: verified created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' Business: type: object properties: id: $ref: '#/components/schemas/EntityIdBusiness' uuid: type: string user_id: $ref: '#/components/schemas/EntityIdUser' name: type: string example: Acme Cafe LLC dba: type: string ein: type: string example: 12-3456789 business_type: type: string example: llc business_industry: type: string example: food_service business_email: $ref: '#/components/schemas/Email' business_phone_number: $ref: '#/components/schemas/Phone' support_email: $ref: '#/components/schemas/Email' support_phone_number: $ref: '#/components/schemas/Phone' address_one: type: string city: type: string state: type: string country: type: string postal_code: type: string status: type: string example: active kyb_status: type: string example: verified created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' BusinessOwner: type: object properties: id: type: string example: bown-... business_id: $ref: '#/components/schemas/EntityIdBusiness' first_name: type: string last_name: type: string email: $ref: '#/components/schemas/Email' phone_number: $ref: '#/components/schemas/Phone' date_of_birth: $ref: '#/components/schemas/DateOfBirth' ownership_percent: type: number example: 25.5 kyc_status: type: string example: verified BusinessDocument: type: object properties: id: type: string example: bkyc-... document_type: type: string example: articles_of_incorporation file_url: type: string format: uri status: type: string created_at: $ref: '#/components/schemas/Timestamp' BusinessContact: type: object properties: id: type: string example: bcus-... contact_type: type: string enum: - customers - vendors first_name: type: string last_name: type: string business_name: type: string email: $ref: '#/components/schemas/Email' phone_number: $ref: '#/components/schemas/Phone' RoutableBankAccount: type: object properties: id: $ref: '#/components/schemas/EntityIdRoutableBankAccount' account_number: type: string example: '8001234567' routing_number: type: string example: '123456789' status: type: string example: active user_id: $ref: '#/components/schemas/EntityIdUser' business_id: $ref: '#/components/schemas/EntityIdBusiness' created_at: $ref: '#/components/schemas/Timestamp' 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' Card: type: object properties: id: $ref: '#/components/schemas/EntityIdCard' card_type: type: string enum: - physical - virtual last_four: type: string example: '4242' status: type: string enum: - unactivated - active - suspended - terminated - limited user_id: $ref: '#/components/schemas/EntityIdUser' business_id: $ref: '#/components/schemas/EntityIdBusiness' created_at: $ref: '#/components/schemas/Timestamp' LedgerTransaction: type: object properties: id: $ref: '#/components/schemas/EntityIdLedgerTransaction' amount: $ref: '#/components/schemas/Money' currency: $ref: '#/components/schemas/Currency' status: $ref: '#/components/schemas/TransactionStatus' category: type: string method: type: string originator_type: type: string originator_id: type: string description: type: string posting_date: $ref: '#/components/schemas/Timestamp' reversed_transaction_id: oneOf: - $ref: '#/components/schemas/EntityIdLedgerTransaction' - type: 'null' PaymentIntent: type: object properties: id: $ref: '#/components/schemas/EntityIdPaymentIntent' amount: $ref: '#/components/schemas/Money' currency: $ref: '#/components/schemas/Currency' direction: type: string enum: - credit - debit action: $ref: '#/components/schemas/PaymentIntentAction' category: type: string enum: - card - bank - wallet status: type: string enum: - pending - in_review - success - failed entity_type: type: string enum: - user - business - program entity_id: type: string idempotent_key: type: string posting_date: $ref: '#/components/schemas/Timestamp' metadata: type: object additionalProperties: true FundLent: type: object properties: id: type: string user_id: $ref: '#/components/schemas/EntityIdUser' business_id: $ref: '#/components/schemas/EntityIdBusiness' amount: $ref: '#/components/schemas/Money' status: type: string enum: - outstanding - paid created_at: $ref: '#/components/schemas/Timestamp'