openapi: 3.0.3 info: title: IngoPay API — Notification of Payment Intent (Notify v4) description: > Submit a notification of payment intent using the v4 structured envelope for staged disbursement processing. **Notify v4 is a SaaS-only endpoint.** Your participant account must be configured as a SaaS participant to use this endpoint. **Cancellations:** Use `POST /gateway/v3/notifycancel` to cancel a staged disbursement created by Notify v4. The cancel endpoint is forward compatible across both v3 and v4. **v4 vs v3 architecture differences:** - v4 uses a fully structured `request{}` + `transaction{}` + `transaction_parties[]` envelope rather than a flat request body. - Recipients, approvers, and interested parties are all defined as items in the `transaction_parties[]` array, each with a `settings{}` object that defines their `role` and `classification`. - `notify_type` controls the disbursement flow: - `0` = Standard disbursement (one-time) - `1` = Enrollment only (recurring, no disbursement) - `2` = Disbursement only (recurring, party must already be enrolled) - `3` = Enrollment and disbursement (recurring) - `role` values within `transaction_parties[].settings{}`: - `0` = Recipient - `1` = Approver - `2` = Interested party - `classification` values within `transaction_parties[].settings{}`: - `1` = Individual - `2` = Business **`sender{}` conditionality:** Required when the client is configured with `require_sender_data`. Contact your Ingo integration manager to confirm your configuration. **`authentication[]` and `notification[]` per party:** Each party in `transaction_parties[]` may include their own `authentication[]` and `notification[]` records. Maximum counts are determined by client configuration. **`recipient.name_personal` mutual exclusivity:** Provide either `name_personal{}` (individual) **or** `name_business` (business name string) — not both. `name_business` requires client-level configuration (`enable_business_name`). version: '4' contact: name: Ingo Money Developer Support url: https://developers.ingomoney.com servers: - url: https://payapi-sandbox.ingo.money description: Sandbox - url: https://payapi.ingo.money description: Production paths: /gateway/v4/notify: post: summary: Submit a notification of payment intent (v4) description: > Submits a staged disbursement notification using the v4 structured envelope. Each party in `transaction_parties[]` receives a notification based on their `role` and `classification`. The recipient must authenticate before the disbursement is released for processing. To cancel a disbursement submitted via this endpoint, use `POST /gateway/v3/notifycancel`. operationId: notifyV4 tags: - Notification of Payment Intent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotifyV4Request' example: request: participant_id: 12345 timestamp: 1745356800 transaction: transaction_amount: amount: 250 currency_code: USD participant_unique_ids: participant_unique_id1: a4f1b2c3-d456-789e-f012-34567890abcd participant_unique_id2: b5e2c3d4-e567-890f-a123-456789012345 workflow_id: 1 notify_type: 0 sender: name_personal: first_name: Alex last_name: Rivera contact_address: address1: 100 Innovation Way city: Anytown state: GA zip: '00000' contact_telcom: email: noreply@example.com sender_account: sender-acct-001 transaction_parties: - settings: client_provided_id: party-001 role: 0 classification: 1 recipient_enabled: 1 name_personal: first_name: Alex last_name: Rivera contact_telcom: email: johnny.rockets@example.com phone_mobile: '5555550100' contact_address: address1: 100 Innovation Way address2: '' city: Anytown state: GA zip: '00000' authentication: - field_label: Last 4 SSN field_order: 1 validation_type: 1 match_failure_type: 1 value_format: XXXX client_provided_value: '1234' notification: - field_label: Account client_provided_value: Checking Account ending 5678 responses: '200': description: Notification submitted successfully content: application/json: schema: $ref: '#/components/schemas/NotifyV4Response' example: request: participant_id: 12345 timestamp: 1745356800 response: status: '100' message: Success duration: '0' transaction: participant_unique_ids: participant_unique_id1: a4f1b2c3-d456-789e-f012-34567890abcd participant_unique_id2: b5e2c3d4-e567-890f-a123-456789012345 notification_id: '9876543' tracer_id: trc-20260422-001 parties: - client_provided_id: party-001 party_id: '1' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: request: participant_id: 12345 timestamp: 1745356800 response: status: '400' message: Validation Error components: schemas: NotifyV4Request: type: object required: - request - transaction - transaction_parties properties: request: type: object required: - participant_id - timestamp description: General information associated with the API request. properties: participant_id: type: integer description: Unique participant identifier assigned by Ingo. example: 12345 timestamp: type: integer description: > Unix timestamp of the request. Must not exceed the current time by more than 30 minutes. example: 1745356800 transaction: type: object required: - transaction_amount - participant_unique_ids - workflow_id - notify_type description: Transaction-level information for the disbursement notification. properties: transaction_amount: type: object required: - amount - currency_code properties: amount: type: number format: float maximum: 9999999999.99 description: Dollar amount of the disbursement. example: 250 currency_code: type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ description: 3-character ISO-4217 (alpha) currency code. example: USD participant_unique_ids: type: object required: - participant_unique_id1 properties: participant_unique_id1: type: string minLength: 1 maxLength: 100 description: > Participant assigned transaction ID. Must be unique. Used for idempotency. Appears on daily reconciliation reports. example: a4f1b2c3-d456-789e-f012-34567890abcd participant_unique_id2: type: string maxLength: 100 nullable: true description: Optional second participant assigned transaction ID. example: b5e2c3d4-e567-890f-a123-456789012345 workflow_id: type: integer description: > Ingo assigned workflow ID that determines the notification and authentication flow. Assigned during client onboarding. example: 1 notify_type: type: integer enum: - 0 - 1 - 2 - 3 description: > Disbursement flow type. 0 = Standard disbursement (one-time), 1 = Enrollment only (recurring), 2 = Disbursement only (recurring — party must already be enrolled), 3 = Enrollment and disbursement (recurring). example: 0 secure_link_1: type: string maxLength: 250 nullable: true description: Optional secure link to include in the notification. example: null document_link: type: string maxLength: 2048 nullable: true description: > Optional URL to a document embedded in the notification. Required when the client is configured for document embedding (`document_embedding_enabled`). example: https://example.com/documents/agreement.pdf language: type: string maxLength: 8 nullable: true description: > Optional language code for the recipient notification. Required when configured for alternate language support. example: es sender: type: object description: > Sender information. Required when the client is configured with `require_sender_data`. Contact your Ingo integration manager to confirm. required: - name_personal - contact_address - contact_telcom - sender_account properties: name_personal: type: object required: - first_name - last_name properties: first_name: type: string minLength: 1 maxLength: 150 description: Sender first name. example: Ingo last_name: type: string minLength: 1 maxLength: 150 description: Sender last name. example: Money contact_address: type: object required: - address1 - city - state - zip properties: address1: type: string minLength: 1 maxLength: 150 description: Sender address line 1. example: 100 Innovation Way address2: type: string maxLength: 150 nullable: true description: Optional sender address line 2. example: null city: type: string minLength: 1 maxLength: 150 description: Sender city. example: Peachtree Corners state: type: string minLength: 2 maxLength: 2 pattern: >- ^(?:A[LKSZRAEP]|C[AOT]|D[EC]|F[LM]|G[AU]|HI|I[ADLN]|K[SY]|LA|M[ADEHINOPST]|N[CDEHJMVY]|O[HKR]|P[ARW]|RI|S[CD]|T[NX]|UT|V[AIT]|W[AIVY])$ description: Sender state (standard US postal abbreviation). example: GA zip: type: string maxLength: 10 pattern: ^[0-9]{5}(?:-[0-9]{4})?$ description: Sender zip code. example: '30092' contact_telcom: type: object required: - email properties: email: type: string minLength: 1 maxLength: 150 description: Sender email address. example: noreply@example.com sender_account: type: string minLength: 1 maxLength: 100 description: | Client assigned sender account identifier. example: sender-acct-001 transaction_parties: type: array minItems: 1 description: > Array of transaction parties. Each party defines a recipient, approver, or interested party for the disbursement notification. At least one party with `role: 0` (recipient) and `recipient_enabled: 1` is required. items: type: object required: - settings - contact_telcom - contact_address description: > Individual party in the disbursement notification. Provide either `name_personal{}` (individual) or `name_business` (business name string) — not both. properties: settings: type: object required: - role - classification - recipient_enabled description: > Party configuration settings that define the party's role in the disbursement flow. properties: client_provided_id: type: string minLength: 1 maxLength: 50 description: > Client assigned identifier for this party. Required for `notify_type: 0`, `1`, and `3`. Not required for `notify_type: 2` (disbursement-only recurring — uses `party_id` instead). Must not be the value `default_check`. example: party-001 party_id: type: string minLength: 1 maxLength: 36 description: > Ingo assigned party identifier for recurring disbursements. Required for `notify_type: 2` (disbursement-only recurring). UUID or `1` for default. example: '1' role: type: integer enum: - 0 - 1 - 2 description: > Party role. 0 = Recipient, 1 = Approver, 2 = Interested party. When `multiparty_enabled` is false, only role `0` (Recipient) is accepted. example: 0 classification: type: integer enum: - 1 - 2 description: | Party classification. 1 = Individual, 2 = Business. example: 1 recipient_enabled: type: integer enum: - 0 - 1 description: > Whether this party is enabled to receive the disbursement. 1 = Enabled, 0 = Notification only (no disbursement). At least one party must have `recipient_enabled: 1`. example: 1 name_personal: type: object description: > Individual name for the party. Provide either `name_personal{}` or `name_business` — not both. required: - first_name - last_name properties: first_name: type: string minLength: 1 maxLength: 150 description: Party first name. example: Johnny last_name: type: string minLength: 1 maxLength: 150 description: Party last name. example: Rockets name_business: type: string minLength: 1 maxLength: 150 nullable: true description: > Business name for the party. Provide instead of `name_personal{}` for business parties. Requires `enable_business_name` client configuration. example: null contact_telcom: type: object required: - email description: Party contact telecommunication information. properties: email: type: string minLength: 1 maxLength: 150 description: > Party email address. The disbursement notification is sent to this address. example: johnny.rockets@example.com phone_mobile: type: string maxLength: 10 nullable: true description: > 10-digit party mobile number. Conditionality depends on OTAC client configuration. example: '4045551234' phone_home: type: string maxLength: 10 nullable: true description: Optional 10-digit party home phone number. example: null contact_address: type: object required: - address1 - city - state - zip description: Party postal address. properties: address1: type: string minLength: 1 maxLength: 150 description: Party address line 1. example: 123 Main St. address2: type: string maxLength: 150 nullable: true description: Optional party address line 2. example: Apt 3 city: type: string minLength: 1 maxLength: 150 description: Party city. example: Atlanta state: type: string minLength: 2 maxLength: 2 pattern: >- ^(?:A[LKSZRAEP]|C[AOT]|D[EC]|F[LM]|G[AU]|HI|I[ADLN]|K[SY]|LA|M[ADEHINOPST]|N[CDEHJMVY]|O[HKR]|P[ARW]|RI|S[CD]|T[NX]|UT|V[AIT]|W[AIVY])$ description: Party state (standard US postal abbreviation). example: GA zip: type: string maxLength: 10 pattern: ^[0-9]{5}(?:-[0-9]{4})?$ description: Party zip code. example: '30313' authentication: type: array nullable: true minItems: 1 description: > Array of authentication challenge records for this party. Maximum count determined by client configuration (`max_authentication_records`). items: type: object required: - field_label - field_order - validation_type - match_failure_type - value_format - client_provided_value properties: field_label: type: string minLength: 1 maxLength: 50 pattern: ^[A-Za-z0-9\-\/ ]+$ description: > Display label for the authentication field. Accepts letters, numbers, hyphens, forward slashes, and spaces. example: Last 4 SSN field_order: type: integer minimum: 1 maximum: 99 description: > Display order for the authentication field. Must be unique within the array. example: 1 validation_type: type: integer enum: - 0 - 1 - 2 - 3 description: > Validation behavior type per NOTIFY_TYPES_V4. 0–3 accepted. example: 1 match_failure_type: type: integer enum: - 0 - 1 - 2 - 3 description: > Behavior on match failure per NOTIFY_TYPES_V4. 0–3 accepted. example: 1 value_format: type: string maxLength: 250 description: > Mask format string defining how the value is displayed to the party. example: XXXX client_provided_value: type: string minLength: 1 maxLength: 100 description: | The actual value the party must match to authenticate. example: '1234' notification: type: array nullable: true minItems: 1 description: > Array of supplemental notification records for this party. Maximum count determined by client configuration (`max_notification_records`). items: type: object properties: field_label: type: string minLength: 1 maxLength: 50 description: Display label for the notification record. example: Account client_provided_value: type: string minLength: 1 maxLength: 750 description: Value to display for this notification record. example: Checking Account ending 5678 NotifyV4Response: type: object properties: request: type: object description: Echo of the request envelope. properties: participant_id: type: integer example: 12345 timestamp: type: integer example: 1745356800 response: type: object properties: status: type: string description: > Numeric code describing the status of the API request. 100 = Success. example: '100' message: type: string description: Text description associated with the status code. example: Success duration: type: string description: Time in seconds to complete the request. example: '0' transaction: type: object description: Transaction outcome data. properties: participant_unique_ids: type: object properties: participant_unique_id1: type: string description: Echo of participant_unique_id1 from request. example: a4f1b2c3-d456-789e-f012-34567890abcd participant_unique_id2: type: string nullable: true description: Echo of participant_unique_id2 from request. example: b5e2c3d4-e567-890f-a123-456789012345 notification_id: type: string description: > Ingo assigned unique identifier for the staged disbursement. Retain this value — it can be used in cancel operations via `POST /gateway/v3/notifycancel`. example: '9876543' tracer_id: type: string description: Ingo assigned tracer ID for the notification. example: trc-20260422-001 parties: type: array description: Party identifiers assigned by Ingo for each party submitted. items: type: object properties: client_provided_id: type: string description: Echo of `client_provided_id` from request. example: party-001 party_id: type: string description: Ingo assigned party ID for this party. example: '1' ErrorResponse: type: object properties: request: type: object properties: participant_id: type: integer example: 12345 timestamp: type: integer example: 1745356800 response: type: object properties: status: type: string example: '400' message: type: string example: Validation Error securitySchemes: HmacAuth: type: apiKey in: header name: Authorization description: >- HMAC-SHA512 signed Authorization header. See the Authentication page for the complete signing guide. security: - HmacAuth: []