Stage Disbursement

Authorizations

Authorization

string

header

required

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 where each request authorizes a real money movement.

Legacy integrations using HMAC-SHA256 remain supported but are encouraged to upgrade. SHA-256 continues to meet the current minimum security bar; however, upgrading to SHA-512 eliminates an entire class of potential vulnerabilities before they become exploitable, and aligns with NIST guidance recommending SHA-2 family algorithms with 256-bit security strength or greater for long-term use. Contact your Ingo integration manager to coordinate an algorithm upgrade.

MD5 and SHA-1 are not accepted under any circumstances. Requests signed with either algorithm 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"

Credentials provisioned by your Ingo integration manager:

HMAC username — identifies your integration in the Authorization header username field. Distinct from your participant identifier.
HMAC secret — provisioned by your Ingo integration manager. The private key used to compute the signature. Never transmit this value — store it in a secrets manager or environment variable, never in source code.
Participant identifier — a separate value used to identify your account within the API request payload. The name and placement differs by product family. Both the HMAC username and participant identifier are provisioned at onboarding — do not substitute one for the other.
API key — required for select product families as an additional per-request credential. See product-specific documentation for applicability.

See the Ingo API Authentication Guide for the complete string-to-sign construction, body hashing requirements, and timestamp validation rules.

Body

application/json

request

object

required

General information associated with the API request.

Hide child attributes

request.participant_id

integer

required

Unique participant identifier assigned by Ingo.

Example:

12345

request.timestamp

integer

required

Unix timestamp of the request. Must not exceed the current time by more than 30 minutes.

Example:

1745356800

transaction

object

required

Transaction-level information for the disbursement notification.

Hide child attributes

transaction.transaction_amount

object

required

Hide child attributes

transaction.transaction_amount.amount

number<float>

required

Dollar amount of the disbursement.

Required range: x <= 9999999999.99

Example:

250

transaction.transaction_amount.currency_code

string

required

3-character ISO-4217 (alpha) currency code.

Required string length: 3

Pattern: ^[A-Z]{3}$

Example:

"USD"

transaction.participant_unique_ids

object

required

Hide child attributes

transaction.participant_unique_ids.participant_unique_id1

string

required

Participant assigned transaction ID. Must be unique. Used for idempotency. Appears on daily reconciliation reports.

Required string length: 1 - 100

Example:

"a4f1b2c3-d456-789e-f012-34567890abcd"

transaction.participant_unique_ids.participant_unique_id2

string | null

Optional second participant assigned transaction ID.

Maximum string length: 100

Example:

"b5e2c3d4-e567-890f-a123-456789012345"

transaction.workflow_id

integer

required

Ingo assigned workflow ID that determines the notification and authentication flow. Assigned during client onboarding.

Example:

1

transaction.notify_type

enum<integer>

required

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).

Available options:

0,

1,

2,

3

Example:

0

transaction.secure_link_1

string | null

Optional secure link to include in the notification.

Maximum string length: 250

Example:

null

transaction.document_link

string | null

Optional URL to a document embedded in the notification. Required when the client is configured for document embedding (document_embedding_enabled).

Maximum string length: 2048

Example:

"https://example.com/documents/agreement.pdf"

transaction.language

string | null

Optional language code for the recipient notification. Required when configured for alternate language support.

Maximum string length: 8

Example:

"es"

transaction.sender

object

Sender information. Required when the client is configured with require_sender_data. Contact your Ingo integration manager to confirm.

Hide child attributes

transaction.sender.name_personal

object

required

Hide child attributes

transaction.sender.name_personal.first_name

string

required

Sender first name.

Required string length: 1 - 150

Example:

"Ingo"

transaction.sender.name_personal.last_name

string

required

Sender last name.

Required string length: 1 - 150

Example:

"Money"

transaction.sender.contact_address

object

required

Hide child attributes

transaction.sender.contact_address.address1

string

required

Sender address line 1.

Required string length: 1 - 150

Example:

"100 Innovation Way"

transaction.sender.contact_address.city

string

required

Sender city.

Required string length: 1 - 150

Example:

"Peachtree Corners"

transaction.sender.contact_address.state

string

required

Sender state (standard US postal abbreviation).

Required string length: 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])$

Example:

"GA"

transaction.sender.contact_address.zip

string

required

Sender zip code.

Maximum string length: 10

Pattern: ^[0-9]{5}(?:-[0-9]{4})?$

Example:

"30092"

transaction.sender.contact_address.address2

string | null

Optional sender address line 2.

Maximum string length: 150

Example:

null

transaction.sender.contact_telcom

object

required

Hide child attributes

transaction.sender.contact_telcom.email

string

required

Sender email address.

Required string length: 1 - 150

Example:

"noreply@example.com"

transaction.sender.sender_account

string

required

Client assigned sender account identifier.

Required string length: 1 - 100

Example:

"sender-acct-001"

transaction_parties

object[]

required

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.

Minimum array length: 1

Hide child attributes

transaction_parties.settings

object

required

Party configuration settings that define the party's role in the disbursement flow.

Hide child attributes

transaction_parties.settings.role

enum<integer>

required

Party role. 0 = Recipient, 1 = Approver, 2 = Interested party. When multiparty_enabled is false, only role 0 (Recipient) is accepted.

Available options:

0,

1,

2

Example:

0

transaction_parties.settings.classification

enum<integer>

required

Party classification. 1 = Individual, 2 = Business.

Available options:

1,

2

Example:

1

transaction_parties.settings.recipient_enabled

enum<integer>

required

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.

Available options:

0,

1

Example:

1

transaction_parties.settings.client_provided_id

string

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.

Required string length: 1 - 50

Example:

"party-001"

transaction_parties.settings.party_id

string

Ingo assigned party identifier for recurring disbursements. Required for notify_type: 2 (disbursement-only recurring). UUID or 1 for default.

Required string length: 1 - 36

Example:

"1"

transaction_parties.contact_telcom

object

required

Party contact telecommunication information.

Hide child attributes

transaction_parties.contact_telcom.email

string

required

Party email address. The disbursement notification is sent to this address.

Required string length: 1 - 150

Example:

"johnny.rockets@example.com"

transaction_parties.contact_telcom.phone_mobile

string | null

10-digit party mobile number. Conditionality depends on OTAC client configuration.

Maximum string length: 10

Example:

"4045551234"

transaction_parties.contact_telcom.phone_home

string | null

Optional 10-digit party home phone number.

Maximum string length: 10

Example:

null

transaction_parties.contact_address

object

required

Party postal address.

Hide child attributes

transaction_parties.contact_address.address1

string

required

Party address line 1.

Required string length: 1 - 150

Example:

"123 Main St."

transaction_parties.contact_address.city

string

required

Party city.

Required string length: 1 - 150

Example:

"Atlanta"

transaction_parties.contact_address.state

string

required

Party state (standard US postal abbreviation).

Required string length: 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])$

Example:

"GA"

transaction_parties.contact_address.zip

string

required

Party zip code.

Maximum string length: 10

Pattern: ^[0-9]{5}(?:-[0-9]{4})?$

Example:

"30313"

transaction_parties.contact_address.address2

string | null

Optional party address line 2.

Maximum string length: 150

Example:

"Apt 3"

transaction_parties.name_personal

object

Individual name for the party. Provide either name_personal{} or name_business — not both.

Hide child attributes

transaction_parties.name_personal.first_name

string

required

Party first name.

Required string length: 1 - 150

Example:

"Johnny"

transaction_parties.name_personal.last_name

string

required

Party last name.

Required string length: 1 - 150

Example:

"Rockets"

transaction_parties.name_business

string | null

Business name for the party. Provide instead of name_personal{} for business parties. Requires enable_business_name client configuration.

Required string length: 1 - 150

Example:

null

transaction_parties.authentication

object[] | null

Array of authentication challenge records for this party. Maximum count determined by client configuration (max_authentication_records).

Minimum array length: 1

Hide child attributes

transaction_parties.authentication.field_label

string

required

Display label for the authentication field. Accepts letters, numbers, hyphens, forward slashes, and spaces.

Required string length: 1 - 50

Pattern: ^[A-Za-z0-9\-\/ ]+$

Example:

"Last 4 SSN"

transaction_parties.authentication.field_order

integer

required

Display order for the authentication field. Must be unique within the array.

Required range: 1 <= x <= 99

Example:

1

transaction_parties.authentication.validation_type

enum<integer>

required

Validation behavior type per NOTIFY_TYPES_V4. 0–3 accepted.

Available options:

0,

1,

2,

3

Example:

1

transaction_parties.authentication.match_failure_type

enum<integer>

required

Behavior on match failure per NOTIFY_TYPES_V4. 0–3 accepted.

Available options:

0,

1,

2,

3

Example:

1

transaction_parties.authentication.value_format

string

required

Mask format string defining how the value is displayed to the party.

Maximum string length: 250

Example:

"XXXX"

transaction_parties.authentication.client_provided_value

string

required

The actual value the party must match to authenticate.

Required string length: 1 - 100

Example:

"1234"

transaction_parties.notification

object[] | null

Array of supplemental notification records for this party. Maximum count determined by client configuration (max_notification_records).

Minimum array length: 1

Hide child attributes

transaction_parties.notification.field_label

string

Display label for the notification record.

Required string length: 1 - 50

Example:

"Account"

transaction_parties.notification.client_provided_value

string

Value to display for this notification record.

Required string length: 1 - 750

Example:

"Checking Account ending 5678"

Response

Notification submitted successfully

request

object

Echo of the request envelope.

Hide child attributes

request.participant_id

integer

Example:

12345

request.timestamp

integer

Example:

1745356800

response

object

Hide child attributes

response.status

string

Numeric code describing the status of the API request. 100 = Success.

Example:

"100"

response.message

string

Text description associated with the status code.

Example:

"Success"

response.duration

string

Time in seconds to complete the request.

Example:

"0"

transaction

object

Transaction outcome data.

Hide child attributes

transaction.participant_unique_ids

object

Hide child attributes

transaction.participant_unique_ids.participant_unique_id1

string

Echo of participant_unique_id1 from request.

Example:

"a4f1b2c3-d456-789e-f012-34567890abcd"

transaction.participant_unique_ids.participant_unique_id2

string | null

Echo of participant_unique_id2 from request.

Example:

"b5e2c3d4-e567-890f-a123-456789012345"

transaction.notification_id

string

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"

transaction.tracer_id

string

Ingo assigned tracer ID for the notification.

Example:

"trc-20260422-001"

transaction.parties

object[]

Party identifiers assigned by Ingo for each party submitted.

Hide child attributes

transaction.parties.client_provided_id

string

Echo of client_provided_id from request.

Example:

"party-001"

transaction.parties.party_id

string

Ingo assigned party ID for this party.

Example:

"1"

Overview

Notify

Webhooks

Authorizations

Body

Response

Overview

Notify

Webhooks

Documentation Index

Authorizations

Body

Response