> ## Documentation Index > Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Stage Disbursement > Stage a disbursement notification for a single recipient via Notify v3. ## OpenAPI ````yaml specs/ingopay-notify-v3.yaml POST /gateway/v3/notify 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 security: - HmacAuth: [] paths: /gateway/v3/notify: post: tags: - Notification of Payment Intent 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 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' 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' 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. ````