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

authentication_records[] is required by default but may be optional based on client OTAC configuration. recipient.mobile conditionality depends on OTAC configuration.

participant_id

integer

required

Unique participant identifier assigned by Ingo.

Example:

12345

amount

string

required

Dollar amount of the disbursement. Must be greater than 0 with a maximum of 2 decimal places.

Maximum string length: 10

Example:

"250.00"

workflow_id

integer

required

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

Example:

1

participant_unique_id1

string

required

Participant assigned transaction ID. Must be unique. Used for idempotency — a duplicate value returns an idempotent response. Appears on daily reconciliation reports.

Required string length: 1 - 100

Example:

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

recipient

object

required

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.

Hide child attributes

recipient.customer_id

string

required

Client assigned unique identifier for the customer.

Maximum string length: 100

Example:

"cust-001"

recipient.email

string

required

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

Required string length: 1 - 150

Example:

"johnny.rockets@example.com"

recipient.address1

string

required

Recipient address line 1.

Required string length: 1 - 150

Example:

"123 Main St."

recipient.city

string

required

Recipient city.

Required string length: 1 - 150

Example:

"Atlanta"

recipient.state

string

required

Recipient 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"

recipient.zip

string

required

Recipient zip code. 5-digit or zip+4 in xxxxx-xxxx format.

Maximum string length: 10

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

Example:

"30313"

recipient.first_name

string

Recipient first name. Required unless business_name is provided.

Required string length: 1 - 150

Example:

"Johnny"

recipient.last_name

string

Recipient last name. Required unless business_name is provided.

Required string length: 1 - 150

Example:

"Rockets"

recipient.business_name

string | null

Recipient business name. Provide instead of first_name and last_name for business recipients. Requires enable_business_name client configuration.

Required string length: 1 - 150

Example:

null

recipient.mobile

string | null

10-digit recipient mobile number. Conditionality depends on OTAC client configuration. Required when otac_enabled is true and otac_allow_same_delivery is false.

Required string length: 1 - 10

Example:

"4045551234"

recipient.address2

string | null

Optional recipient address line 2.

Maximum string length: 150

Example:

"Apt 3"

recipient.phone

string | null

Optional 10-digit recipient home/office phone number.

Maximum string length: 10

Example:

"4045554321"

participant_unique_id2

string | null

Optional second participant assigned transaction ID.

Maximum string length: 100

Example:

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

tracer_id

string | null

Optional client assigned tracer ID for tracking the request. If not provided, Ingo generates one and returns it in the response.

Maximum string length: 254

Example:

"trc-20260422-001"

language

string | null

Optional language code for the recipient notification. Required when the client is configured for alternate language support (alternate_language_enabled).

Maximum string length: 8

Example:

"es"

document_link

string | null

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

Maximum string length: 2048

Example:

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

joint_recipient

object

Optional joint recipient information for joint account disbursements.

Hide child attributes

joint_recipient.joint_first_name

string | null

Joint recipient first name.

Required string length: 1 - 150

Example:

"Jane"

joint_recipient.joint_last_name

string | null

Joint recipient last name.

Required string length: 1 - 150

Example:

"Rockets"

joint_recipient.joint_email

string | null

Joint recipient email address.

Required string length: 1 - 150

Example:

"jane.rockets@example.com"

joint_recipient.joint_mobile

string | null

10-digit joint recipient mobile number.

Required string length: 1 - 10

Example:

"4045559876"

joint_recipient.joint_address1

string | null

Joint recipient address line 1.

Required string length: 1 - 150

Example:

"123 Main St."

joint_recipient.joint_address2

string | null

Optional joint recipient address line 2.

Maximum string length: 150

Example:

"Apt 3"

joint_recipient.joint_city

string | null

Joint recipient city.

Required string length: 1 - 150

Example:

"Atlanta"

joint_recipient.joint_state

string | null

Joint recipient 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"

joint_recipient.joint_zip

string | null

Joint recipient zip code.

Maximum string length: 10

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

Example:

"30313"

joint_recipient.joint_phone

string | null

10-digit joint recipient home/office phone number.

Required string length: 1 - 10

Example:

"4045558765"

approver

object

Optional approver information. When provided, the approver is notified and must approve the disbursement before it is released to the recipient.

Hide child attributes

approver.approver_first_name

string | null

Approver first name.

Required string length: 1 - 150

Example:

"Bob"

approver.approver_last_name

string | null

Approver last name.

Required string length: 1 - 150

Example:

"Smith"

approver.approver_email

string | null

Approver email address.

Required string length: 1 - 150

Example:

"bob.smith@example.com"

approver.approver_mobile

string | null

10-digit approver mobile number.

Required string length: 1 - 10

Example:

"4045557890"

authentication_records

object[]

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.

Required array length: 1 - 20 elements

Hide child attributes

authentication_records.field_label

string

required

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

Required string length: 1 - 50

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

Example:

"Last 4 SSN"

authentication_records.field_order

integer

required

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

Required range: 1 <= x <= 99

Example:

1

authentication_records.validation_type

enum<integer>

required

Validation behavior type. 1 = exact match required, 2 = partial match allowed.

Available options:

1,

2

Example:

1

authentication_records.match_failure_type

enum<integer>

required

Behavior on match failure. 1 = block disbursement, 2 = allow with flag.

Available options:

1,

2

Example:

1

authentication_records.value_format

string

required

Mask format string defining how the value is displayed to the recipient (e.g. XXXX for last-4 masking).

Maximum string length: 250

Example:

"XXXX"

authentication_records.client_provided_value

string

required

The actual value the recipient must match to authenticate the disbursement.

Required string length: 1 - 100

Example:

"1234"

notification_records

object[] | null

Optional array of supplemental notification records displayed in the recipient notification. Certain records may be required based on client configuration.

Hide child attributes

notification_records.field_label

string

Display label for the notification record.

Required string length: 1 - 50

Example:

"Account"

notification_records.client_provided_value

string

Value to display for this notification record.

Required string length: 1 - 4000

Example:

"Checking Account ending 5678"

Response

Notification submitted successfully

status

integer

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

Example:

100

client_message

string

Text description associated with the status code.

Example:

"Success"

data

object

Hide child attributes

data.notification_id

integer

Ingo assigned unique identifier for the staged disbursement notification. Retain this value — it is required for cancel operations.

Example:

9876543

data.tracer_id

string

Tracer ID associated with the notification. Echo of the value provided on the request, or Ingo-generated if not provided.

Example:

"trc-20260422-001"

Overview

Notify

Webhooks

Authorizations

Body

Response

Overview

Notify

Webhooks

Documentation Index

Authorizations

Body

Response