openapi: 3.0.3 info: title: IngoPay API — Notification of Payment Intent (Notify v3) description: > Submit a notification of payment intent to a recipient for staged disbursement processing, and cancel a staged disbursement request. **Notify v3 covers two operations:** - `POST /gateway/v3/notify` — Submit a notification of payment intent. The recipient receives a notification (email and/or SMS) and must authenticate before the disbursement is released. - `POST /gateway/v3/notifycancel` — Cancel a staged disbursement that has not yet been claimed. This endpoint is forward compatible and can be used to cancel staged disbursements initiated by both Notify v3 and Notify v4. **Notify v3 is a SaaS-only endpoint.** Your participant account must be configured as a SaaS participant to use these endpoints. Contact your Ingo integration manager to confirm your configuration. **`authentication_records[]` conditionality:** Required by default for all SaaS participants. May be optional when the client is configured with OTAC (One-Time Auth Code) and DPA authentication is disabled. Contact your Ingo integration manager to confirm your configuration. **`recipient` name mutual exclusivity:** Provide either `first_name` + `last_name` (personal name) **or** `business_name` (business name) — not both. `business_name` requires client-level configuration (`enable_business_name`). > **Note on `open_banking_finicity`:** Recipients inside `recipient{}` may include an `open_banking_finicity{}` sub-object when the client is configured for Finicity open banking (`open_banking_finicity` flag). This is gated behind client configuration — contact your integration manager to confirm if this applies. version: '3' 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/v3/notify: post: summary: Submit a notification of payment intent description: > Submits a staged disbursement notification to a recipient. The recipient is notified via email and/or SMS and must authenticate before the disbursement is released for processing. operationId: notifyV3 tags: - Notification of Payment Intent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotifyV3Request' example: participant_id: 12345 amount: '250.00' workflow_id: 1 participant_unique_id1: a4f1b2c3-d456-789e-f012-34567890abcd participant_unique_id2: b5e2c3d4-e567-890f-a123-456789012345 tracer_id: trc-20260422-001 recipient: customer_id: cust-001 first_name: Alex last_name: Rivera email: johnny.rockets@example.com mobile: '5555550100' address1: 100 Innovation Way address2: '' city: Anytown state: GA zip: '00000' phone: '5555550100' authentication_records: - field_label: Last 4 SSN field_order: 1 validation_type: 1 match_failure_type: 1 value_format: XXXX client_provided_value: '1234' notification_records: - field_label: Account client_provided_value: Checking Account ending 5678 responses: '200': description: Notification submitted successfully content: application/json: schema: $ref: '#/components/schemas/NotifyV3Response' example: status: 100 client_message: Success data: notification_id: 9876543 tracer_id: trc-20260422-001 participant_unique_id1: PARTNER-REF-001 participant_unique_id2: PARTNER-REF-002 request_timestamp: 1700000000 time: '0.85' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 400 client_message: Validation Error data: errors: recipient.email: Field is required participant_unique_id1: PARTNER-REF-001 participant_unique_id2: PARTNER-REF-002 request_timestamp: 1700000000 time: '0.85' /gateway/v3/notifycancel: post: summary: Cancel a staged disbursement description: > Cancels a staged disbursement that has not yet been claimed by the recipient. This endpoint is forward compatible and can be used to cancel staged disbursements initiated by either Notify v3 or Notify v4. The transaction is located using `participant_unique_id1` and `tracer_id`. `notification_id` may optionally be provided as an additional identifier. operationId: notifyCancelV3 tags: - Notification of Payment Intent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotifyCancelRequest' example: participant_id: 12345 participant_unique_id1: a4f1b2c3-d456-789e-f012-34567890abcd first_name: Alex last_name: Rivera amount: '250.00' tracer_id: trc-20260422-001 notification_id: 9876543 customer_id: cust-001 participant_unique_id2: b5e2c3d4-e567-890f-a123-456789012345 responses: '200': description: Disbursement cancelled successfully content: application/json: schema: $ref: '#/components/schemas/NotifyCancelResponse' example: status: 100 client_message: Disbursement Request Canceled data: notification_id: '9876543' participant_unique_id1: PARTNER-REF-001 tracer_id: trc-20260422-001 request_timestamp: 1700000000 participant_unique_id2: PARTNER-REF-002 time: '0.85' '400': description: Validation error or transaction not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 400 client_message: Validation Error data: errors: tracer_id: Field is required participant_unique_id1: PARTNER-REF-001 participant_unique_id2: PARTNER-REF-002 request_timestamp: 1700000000 time: '0.85' components: schemas: NotifyV3Request: type: object required: - participant_id - amount - workflow_id - participant_unique_id1 - recipient description: > `authentication_records[]` is required by default but may be optional based on client OTAC configuration. `recipient.mobile` conditionality depends on OTAC configuration. properties: participant_id: type: integer description: Unique participant identifier assigned by Ingo. example: 12345 amount: type: string maxLength: 10 description: > Dollar amount of the disbursement. Must be greater than 0 with a maximum of 2 decimal places. example: '250.00' workflow_id: type: integer description: >- Ingo-assigned workflow identifier that determines the disbursement flow configuration. Defaults to 1 if not otherwise specified by your Ingo integration manager. example: 1 participant_unique_id1: type: string minLength: 1 maxLength: 100 description: > Participant assigned transaction ID. Must be unique. Used for idempotency — a duplicate value returns an idempotent response. 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 recipient: type: object required: - customer_id - email - address1 - city - state - zip description: > Information about the disbursement recipient. Provide either `first_name` + `last_name` **or** `business_name` — not both. `business_name` requires client-level configuration. `mobile` conditionality depends on OTAC configuration. properties: customer_id: type: string maxLength: 100 description: Client assigned unique identifier for the customer. example: cust-001 first_name: type: string minLength: 1 maxLength: 150 description: > Recipient first name. Required unless `business_name` is provided. example: Johnny last_name: type: string minLength: 1 maxLength: 150 description: > Recipient last name. Required unless `business_name` is provided. example: Rockets business_name: type: string minLength: 1 maxLength: 150 nullable: true description: > Recipient business name. Provide instead of `first_name` and `last_name` for business recipients. Requires `enable_business_name` client configuration. example: null address1: type: string minLength: 1 maxLength: 150 description: Recipient address line 1. example: 123 Main St. address2: type: string maxLength: 150 nullable: true description: Optional recipient address line 2. example: Apt 3 city: type: string minLength: 1 maxLength: 150 description: Recipient 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: Recipient state (standard US postal abbreviation). example: GA zip: type: string maxLength: 10 pattern: ^[0-9]{5}(?:-[0-9]{4})?$ description: | Recipient zip code. 5-digit or zip+4 in xxxxx-xxxx format. example: '30313' email: type: string minLength: 1 maxLength: 150 description: > Recipient email address. The disbursement notification is sent to this address. example: johnny.rockets@example.com mobile: type: string minLength: 1 maxLength: 10 nullable: true description: > 10-digit recipient mobile number. Conditionality depends on OTAC client configuration. Required when `otac_enabled` is true and `otac_allow_same_delivery` is false. example: '4045551234' phone: type: string maxLength: 10 nullable: true description: Optional 10-digit recipient home/office phone number. example: '4045554321' open_banking_finicity: type: object nullable: true description: >- Open banking account identification via Finicity. Optional — only applicable for clients configured to use Finicity for open banking services. properties: customer_id: type: string maxLength: 50 description: Finicity customer ID. example: FINICITY-CUST-001 required: - customer_id authentication_records: type: array minItems: 1 maxItems: 20 description: > Array of authentication challenge records used to verify the recipient's identity before releasing the disbursement. Required by default — may be optional based on client OTAC configuration. Maximum 20 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 shown to the recipient. 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: - 1 - 2 description: > Validation behavior type. 1 = exact match required, 2 = partial match allowed. example: 1 match_failure_type: type: integer enum: - 1 - 2 description: > Behavior on match failure. 1 = block disbursement, 2 = allow with flag. example: 1 value_format: type: string maxLength: 250 description: > Mask format string defining how the value is displayed to the recipient (e.g. `XXXX` for last-4 masking). example: XXXX client_provided_value: type: string minLength: 1 maxLength: 100 description: > The actual value the recipient must match to authenticate the disbursement. example: '1234' notification_records: type: array nullable: true description: > Optional array of supplemental notification records displayed in the recipient notification. Certain records may be required based on client configuration. 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: 4000 description: | Value to display for this notification record. example: Checking Account ending 5678 language: type: string maxLength: 8 nullable: true description: >- IETF locale code specifying the language for the notification. Conditional on alternate_language_enabled client configuration. example: en-US enum: - ar-SA - cs-CZ - da-DK - de-DE - en-GB - en-US - es-ES - es-US - fa-IR - fi-FI - fr-FR - hmn-Latn - it-IT - ja-JP - km-KH - ko-KR - nb-NO - nl-NL - pl-PL - pt-BR - ru-RU - sv-SE - tl-PH - tr-TR - vi-VN - zh-CN - zh-Hans - zh-TW document_link: type: string maxLength: 2048 nullable: true description: > Optional URL to a document to be embedded in the recipient notification. Required when the client is configured for document embedding (`document_embedding_enabled`). example: https://example.com/documents/agreement.pdf NotifyV3Response: type: object properties: status: type: integer description: > Numeric code describing the status of the API request. 100 = Success. example: 100 client_message: type: string description: Text description associated with the status code. example: Success data: type: object properties: notification_id: type: integer description: Ingo-assigned unique identifier for the staged notification. example: 1000001 tracer_id: type: string description: Ingo-assigned tracer identifier for internal tracking. example: trc-abc123 participant_unique_id1: type: string description: Echo of the participant_unique_id1 submitted in the request. example: PARTNER-REF-001 participant_unique_id2: type: string nullable: true description: Echo of the participant_unique_id2 submitted in the request. example: PARTNER-REF-002 request_timestamp: type: integer description: Unix timestamp of the request. example: 1700000000 description: Response data for the staged notification. time: type: string description: Server-side request processing time in seconds. example: '0.85' NotifyCancelRequest: type: object required: - participant_id - participant_unique_id1 - first_name - last_name - amount - tracer_id description: > Cancels a staged disbursement. The transaction is located using `participant_unique_id1` and `tracer_id`. Compatible with disbursements staged via Notify v3 or Notify v4. properties: participant_id: type: integer description: Unique participant identifier assigned by Ingo. example: 12345 participant_unique_id1: type: string minLength: 1 maxLength: 254 description: > Participant assigned transaction ID provided on the original Notify request. example: a4f1b2c3-d456-789e-f012-34567890abcd first_name: type: string minLength: 1 maxLength: 150 description: Recipient first name as provided on the original Notify request. example: Johnny last_name: type: string minLength: 1 maxLength: 150 description: Recipient last name as provided on the original Notify request. example: Rockets amount: type: string description: > Dollar amount of the disbursement as provided on the original Notify request. example: '250.00' tracer_id: type: string maxLength: 254 description: | Tracer ID associated with the original Notify request. example: trc-20260422-001 notification_id: type: integer nullable: true description: > Optional Ingo assigned notification ID returned on the original Notify response. When provided, used as an additional identifier to locate the staged disbursement. example: 9876543 customer_id: type: string maxLength: 254 nullable: true description: | Optional client assigned customer identifier. example: cust-001 participant_unique_id2: type: string maxLength: 254 nullable: true description: > Optional second participant assigned transaction ID as provided on the original Notify request. example: b5e2c3d4-e567-890f-a123-456789012345 NotifyCancelResponse: type: object properties: status: type: integer description: > Numeric code describing the status of the API request. 100 = Success. example: 100 client_message: type: string description: Text description associated with the status code. example: Disbursement Request Canceled data: type: object properties: notification_id: type: string description: Echo of the notification ID for the cancelled disbursement. example: '9876543' participant_unique_id1: type: string description: Echo of participant_unique_id1 from the original request. example: a4f1b2c3-d456-789e-f012-34567890abcd tracer_id: type: string description: Echo of the tracer ID. example: trc-20260422-001 request_timestamp: type: integer format: int64 description: Unix timestamp of the cancel request. example: 1745356800 ErrorResponse: type: object properties: status: type: integer example: 400 client_message: type: string example: Validation Error data: type: object properties: errors: type: object description: Field-level validation errors. additionalProperties: type: string 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: []