"
},
"created_at": "DD-MM-YYYY hh:mm AM/PM",
"updated_at": "DD-MM-YYYY hh:mm AM/PM"
}
```
| Field | Notes |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `event` | Outer routing key — use this to branch on event type. Example: `"account.transfer.completed"` |
| `data.event_id` | Platform-generated delivery ID. Format: `inn_whe_` followed by 22 alphanumeric characters. Use as your deduplication key. |
| `data.event_type` | Always mirrors `event`. |
| `data.event_description` | Free-text summary. Meaningful on some events (e.g. `account.issue.created` uses it to name the account type issued). May be empty on others. |
| `created_at` / `updated_at` | Outer delivery timestamps. |
***
## Field Conventions
| Field | Type | Notes |
| -------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `entity_id` | string | Numeric platform identifier for the entity, passed as a string. Example: `"6830"` |
| `entity_type` | enum | `"user"` or `"business"` |
| `user_id` / `business_id` | string | Numeric platform identifier for the specific user or business. Example: `"9414"` |
| `account_id` | string | Numeric platform identifier for the account (except in assignment events, where it is a UUID). Example: `"6246"` |
| `wallet_id` | string | Numeric platform identifier for the wallet. Example: `"3273"` |
| `transfer_id` / `transaction_id` / `adjustment_id` | string | Platform-generated transfer or transaction identifiers. Example: `"DPST_PVCVXAR4KRU2CTOT6026NIGGS"` |
| `card_id` (in `card` block) | string | Prefixed UUID. Example: `"rcrd-acc960c0-3a14-413e-a248-74684e52a0f2"` |
| `account.account_id` (assignment events) | string | UUID format. Example: `"9e30d021-3f39-4fcc-935b-e286d7f52807"` |
| `currency` | string | Uppercase currency code. Currently `USD` only. |
| `direction` | enum | `"credit"` (funds in) or `"debit"` (funds out), from the entity's perspective. |
| `amount` | string | Decimal amount with two decimal places, always as a string. Example: `"500.00"`. Never treat as a float. |
***
## Receiver Best Practices
**Deduplicate on `data.event_id`.** The same event may be redelivered under transient failure. Store processed event IDs and skip duplicates.
**Acknowledge fast, process async.** Return `2xx` quickly; defer heavy work to a background job. Slow responses will cause retries.
**Parse defensively.** New optional fields may be added to the `data` block in future platform versions. Do not reject events with unknown fields.
**Handle unknown `card.status.*` values as a no-op.** The platform may emit any value from the card status enum. Unknown statuses should not cause errors.
**Use `event_description` to identify account issuance type.** `account.issue.created` and `account.issue.failed` are emitted for both VBAN and RBA issuance. The `event_description` field distinguishes them — common values are `"Virtual Bank Account"` and `"Routable Bank Account"`.
**Disambiguate bulk vs. single assignment events.** `account.assignment.success` and `account.assignment.failed` are emitted in two distinct payload shapes. Branch on the presence of `process_id`:
* **Single-record** — includes `entity_id`, `entity_type`, and an `account` block describing the assigned account
* **Bulk** — includes `process_id`, `data.event_type` set to the constant `"account.assignment.bulk"`, and a `batch` block with run statistics
***
## Platform Notes
The `status` field on card lifecycle events (including `card.issue.failed`) carries the value `"completed"`. This reflects the event-delivery status, not the card outcome. Use the `event` name itself to determine whether the operation succeeded or failed.
Transfer reversal and block events (`account.transfer.reversed`, `account.transfer.blocked`) use a slimmer payload than created/completed/failed events — they omit `account_id`, `account_type`, `currency`, `amount`, and `memo`.
***
## Event Categories
| Category | Events |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| User Events | `user.created`, `user.kyc.success`, `user.kyc.failed` |
| Business Events | `business.created`, `business.kyb.success`, `business.kyb.failed` |
| Wallet Events | `wallet.created`, `wallet.topup.success`, `wallet.topup.failed` |
| Account Lifecycle | `account.created`, `account.saved`, `account.link.created`, `account.link.deleted`, `account.issue.created`, `account.issue.failed` |
| Account Assignment | `account.assignment.success`, `account.assignment.failed` |
| Transfer Events | `account.transfer.created`, `account.transfer.completed`, `account.transfer.reversed`, `account.transfer.blocked`, `account.transfer.failed`, `account.transfer.returned`, `account.overdraft.created`, `account.transfer.exception` |
| Card Lifecycle In Development | `card.issue.created`, `card.issue.failed`, `card.status.active`, `card.status.frozen`, `card.status.inactive`, `card.status.pending`, `card.status.inreview`, `card.status.terminated`, `card.status.reissue` |
| Card Authorization In Development | `card.auth.created`, `card.auth.cleared`, `card.auth.updated`, `card.auth.reversed`, `card.auth.refund` |
Card Lifecycle and Card Authorization events correspond to the Card Issuance capability, which is currently in development. These events are documented here so you can build and test your handlers in advance. They will not fire until Card Issuance is enabled for your program.
Select an event from the sidebar to view its full payload schema and example.
# Use with AI Tools
Source: https://developers.ingopayments.com/docs/hub/ai-assistant
Connect the Ingo Payments Developer Hub to your AI coding assistant for accurate, up-to-date answers directly from the documentation.
Connect any MCP-compatible AI tool to the Ingo Payments Developer Hub and ask questions directly against the live documentation — instead of relying on your tool's training data, which may be outdated or incomplete. The connection is read-only: no AI tool can edit, create, or modify any documentation through this integration.
**MCP server URL:** `https://developers.ingopayments.com/mcp`
***
## What this enables
When you connect your AI tool to this MCP server, it gains two capabilities:
**Search** — queries the full documentation index to find relevant pages matching your question. The AI uses this proactively while generating a response, even without being asked explicitly.
**Read page content** — retrieves the full text of any documentation page, including API field definitions, code examples, and spec details.
Both tools operate on the current state of the documentation — not cached or training-data versions. This is particularly useful when looking up specific field constraints, error codes, webhook event schemas, or endpoint request/response structures.
***
## Connect your AI tool
### Claude
1. Open [Claude Settings → Connectors](https://claude.ai/settings/connectors)
2. Select **Add custom connector**
3. Enter a name (e.g. `Ingo Developer Hub`) and the URL: `https://developers.ingopayments.com/mcp`
4. Select **Add**
5. When starting a conversation, select the attachments icon (plus) and choose the connector to activate it
### Claude Code
Run the following command in your terminal:
```bash theme={null}
claude mcp add --transport http "Ingo Developer Hub" https://developers.ingopayments.com/mcp
```
Verify the connection:
```bash theme={null}
claude mcp list
```
### Cursor
1. Open the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Search for **Open MCP settings** and select **Add custom MCP** — this opens `mcp.json`
3. Add the following configuration:
```json theme={null}
{
"mcpServers": {
"Ingo Developer Hub": {
"url": "https://developers.ingopayments.com/mcp"
}
}
}
```
4. Save the file. Cursor will connect automatically.
### VS Code
Create or edit `.vscode/mcp.json` in your workspace:
```json theme={null}
{
"servers": {
"Ingo Developer Hub": {
"type": "http",
"url": "https://developers.ingopayments.com/mcp"
}
}
}
```
***
## Tips for better results
Ask specific questions to get the most relevant documentation pulled into context. For example:
* *"What fields are required in an IngoPay card verify request?"*
* *"What webhook fires when a Notify Classic disbursement is successful?"*
* *"What is the difference between Standard ACH and Same-Day ACH in the IngoPay process endpoint?"*
You can also connect multiple MCP servers simultaneously. If you have other product documentation connected, be specific about which product or endpoint you're asking about so the AI searches the right source.
This connection is **read-only**. AI tools connected to this MCP server can search and read documentation but cannot modify, create, or delete any content.
# API Specifications
Source: https://developers.ingopayments.com/docs/hub/api-specs
Direct links to every OpenAPI and AsyncAPI specification published by Ingo Payments — ready to import into Postman, generate SDKs, or connect your IDE.
Every spec file published to this developer center is available as a raw YAML file at a stable URL. Use these links to import specs into Postman, generate client SDKs, connect IDE plugins, or run your own validation tooling. Specs are updated with each platform release — the URLs below always reflect the current published version.
Sections below mirror the product tabs in the top navigation. Within each product, request/response specs are **OpenAPI 3.0** and webhook event specs are **AsyncAPI 3.0** — the Type column tells you which is which. Jump to a product:
Tokenization, push & pull payments, risk, ancillary services, and gateway webhooks.
iFrame session management and EAC plugin webhooks.
Notify v3 request specs and Classic webhook events.
Notify v4 request specs and Managed Parties webhook events.
Banking Platform API and webhook events.
Specs marked **Coming Soon** on their reference pages are excluded from this index. Those specifications are subject to change prior to general availability and are not recommended for integration. Contact your Ingo integration manager for availability timelines.
***
## IngoPay API
The IngoPay API uses a shared endpoint (`POST /gateway/verify`, `POST /gateway/process`, `POST /gateway/v12/debit/process`) that branches by `account_type`. Each spec below covers a single account type so the request and response schemas are unambiguous in the API playground and in generated clients.
### Account Tokenization
| Spec | Type | URL |
| -------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Card Tokenization | OpenAPI 3.0 | [ingopay-verify-card.yaml](https://developers.ingopayments.com/specs/ingopay-verify-card.yaml) |
| ACH Tokenization | OpenAPI 3.0 | [ingopay-verify-ach.yaml](https://developers.ingopayments.com/specs/ingopay-verify-ach.yaml) |
| BillPay Tokenization | OpenAPI 3.0 | [ingopay-verify-billpay.yaml](https://developers.ingopayments.com/specs/ingopay-verify-billpay.yaml) |
| Check by Mail Tokenization | OpenAPI 3.0 | [ingopay-verify-check.yaml](https://developers.ingopayments.com/specs/ingopay-verify-check.yaml) |
| PayPal / Venmo Tokenization | OpenAPI 3.0 | [ingopay-verify-paypal-venmo.yaml](https://developers.ingopayments.com/specs/ingopay-verify-paypal-venmo.yaml) |
| Retail Card-Present Tokenization | OpenAPI 3.0 | [ingopay-verify-retail-card-present.yaml](https://developers.ingopayments.com/specs/ingopay-verify-retail-card-present.yaml) |
### Push Payments
| Spec | Type | URL |
| ------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Card Push Disbursement | OpenAPI 3.0 | [ingopay-process-card.yaml](https://developers.ingopayments.com/specs/ingopay-process-card.yaml) |
| ACH Push Disbursement | OpenAPI 3.0 | [ingopay-process-ach.yaml](https://developers.ingopayments.com/specs/ingopay-process-ach.yaml) |
| BillPay Push | OpenAPI 3.0 | [ingopay-process-billpay.yaml](https://developers.ingopayments.com/specs/ingopay-process-billpay.yaml) |
| Check by Mail Push | OpenAPI 3.0 | [ingopay-process-check.yaml](https://developers.ingopayments.com/specs/ingopay-process-check.yaml) |
| PayPal / Venmo Push | OpenAPI 3.0 | [ingopay-process-paypal-venmo.yaml](https://developers.ingopayments.com/specs/ingopay-process-paypal-venmo.yaml) |
| Retail Card-Present Push | OpenAPI 3.0 | [ingopay-process-retail-card-present.yaml](https://developers.ingopayments.com/specs/ingopay-process-retail-card-present.yaml) |
### Pull Payments
| Spec | Type | URL |
| --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Card Pull (v12 Debit) | OpenAPI 3.0 | [ingopay-debit-process-card.yaml](https://developers.ingopayments.com/specs/ingopay-debit-process-card.yaml) |
| ACH Pull (v12 Debit) | OpenAPI 3.0 | [ingopay-debit-process-ach.yaml](https://developers.ingopayments.com/specs/ingopay-debit-process-ach.yaml) |
### Risk & Compliance
| Spec | Type | URL |
| ------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| Risk Session + Risk Score | OpenAPI 3.0 | [ingopay-risk.yaml](https://developers.ingopayments.com/specs/ingopay-risk.yaml) |
### Ancillary Services
| Spec | Type | URL |
| ----------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Biller Search | OpenAPI 3.0 | [ingopay-biller-payments-search.yaml](https://developers.ingopayments.com/specs/ingopay-biller-payments-search.yaml) |
| Check Stop | OpenAPI 3.0 | [ingopay-check-stop.yaml](https://developers.ingopayments.com/specs/ingopay-check-stop.yaml) |
| Check Cancel | OpenAPI 3.0 | [ingopay-check-cancel.yaml](https://developers.ingopayments.com/specs/ingopay-check-cancel.yaml) |
| Open Banking Account Data *(Under Development)* | OpenAPI 3.0 | [ingopay-open-banking-account.yaml](https://developers.ingopayments.com/specs/ingopay-open-banking-account.yaml) |
### Webhooks
| Spec | Type | URL |
| ------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------- |
| IngoPay Gateway Webhook Events | AsyncAPI 3.0 | [asyncapi-ingopay.yaml](https://developers.ingopayments.com/specs/asyncapi-ingopay.yaml) |
***
## Embedded Account Capture
### Session Management
| Spec | Type | URL |
| ------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| iFrame Session Management | OpenAPI 3.0 | [iframe-session-create.yaml](https://developers.ingopayments.com/specs/iframe-session-create.yaml) |
### Webhooks
| Spec | Type | URL |
| ------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------- |
| EAC Plugin Webhook Events | AsyncAPI 3.0 | [asyncapi-iframe.yaml](https://developers.ingopayments.com/specs/asyncapi-iframe.yaml) |
***
## Notify — Classic
### Notify
| Spec | Type | URL |
| ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
| Notify v3 — Classic | OpenAPI 3.0 | [ingopay-notify-v3.yaml](https://developers.ingopayments.com/specs/ingopay-notify-v3.yaml) |
### Webhooks
| Spec | Type | URL |
| ----------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Notify Classic Webhook Events | AsyncAPI 3.0 | [asyncapi-notify-v3.yaml](https://developers.ingopayments.com/specs/asyncapi-notify-v3.yaml) |
***
## Notify — Managed Parties
### Notify
| Spec | Type | URL |
| --------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
| Notify v4 — Managed Parties | OpenAPI 3.0 | [ingopay-notify-v4.yaml](https://developers.ingopayments.com/specs/ingopay-notify-v4.yaml) |
### Webhooks
| Spec | Type | URL |
| ------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Notify Managed Parties Webhook Events | AsyncAPI 3.0 | [asyncapi-notify-v4.yaml](https://developers.ingopayments.com/specs/asyncapi-notify-v4.yaml) |
***
## Banking Platform
### API Reference
| Spec | Type | URL |
| -------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Banking Platform API | OpenAPI 3.0 | [ingo-banking-merchant-ledgering.yaml](https://developers.ingopayments.com/specs/ingo-banking-merchant-ledgering.yaml) |
### Webhooks
| Spec | Type | URL |
| ------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Banking Platform Webhook Events | AsyncAPI 3.0 | [asyncapi-banking.yaml](https://developers.ingopayments.com/specs/asyncapi-banking.yaml) |
The Banking Platform webhook spec includes Card Lifecycle and Card Authorization event schemas. These are documented for advance integration planning — Card Issuance is currently **In Development** and these events will not fire until the capability is enabled for your program.
# Authentication
Source: https://developers.ingopayments.com/docs/hub/authentication
HMAC-SHA512 request signing for all Ingo Payments APIs — credentials, signature construction, environments, and product-specific requirements.
All Ingo Payments APIs use **HMAC-SHA512** request signing. This is not an API-key-in-header pattern — every request must be signed using a shared secret that never leaves your server. The `Authorization` header carries the result of that signing process.
Your HMAC credentials are provisioned by your Ingo integration manager at onboarding. You will receive a **username** and a **secret**. The secret is used locally to sign requests and is never transmitted.
***
## Product-specific requirements
The signing process is identical across all products. The table below summarizes any additional requirements per product.
| Product | Auth mechanism | Additional requirement |
| ------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| IngoPay API | HMAC-SHA512 | — |
| Notify — Classic | HMAC-SHA512 | — |
| Notify — Managed Parties | HMAC-SHA512 | — |
| Embedded Account Capture | HMAC-SHA512 (server-side only) | The iFrame SDK handles browser-side session auth automatically — no additional signing required from the client |
| Banking Platform | HMAC-SHA512 + API key | An `api_key` credential must accompany every request (see below) |
### Banking Platform — API key
The Banking Platform requires an additional **API key** on every request alongside the HMAC signature. Both layers are enforced — a valid API key alone will not work without a valid signature.
Pass the API key as a request header (preferred):
```
api_key: YOUR_API_KEY
```
Or as a body field:
```json theme={null}
{
"api_key": "YOUR_API_KEY",
...
}
```
Treat the API key as a secret. Do not expose it in client-side code or commit it to source control.
***
## Credentials
| Credential | Description |
| ---------------- | ------------------------------------------------------------------------- |
| `username` | Identifies your integration in the `Authorization` header |
| `secret` | Used locally to sign each request. Never transmitted. |
| `participant_id` | Numeric identifier included in the request body (IngoPay, Notify, iFrame) |
***
## Authorization header format
Every request must include an `Authorization` header in this exact format:
```
hmac username="{username}", algorithm="hmac-sha512", headers="{header_string}", signature="{signature}"
```
**Example:**
```
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="hAMqhSX6eogO1QpES9Dg9WynJWJPNxFLe1wtV4ppfvmGmqpYCiJYm6lqrHNjcmQUZCyMBdK86Zkm+m3BJwj3XA=="
```
| Parameter | Value |
| ----------- | ------------------------------------------------------- |
| `username` | Your Ingo-issued username |
| `algorithm` | Always `hmac-sha512` |
| `headers` | Space-separated list of signed header names (see below) |
| `signature` | Base64-encoded HMAC-SHA512 signature (see below) |
***
## Building the signature — step by step
Every request must include these headers. Generate them before signing:
**`X-Date`** — Current timestamp in GMT/RFC 1123 format. Ingo allows
a clock skew of ±300 seconds. Requests outside this window are rejected
to prevent replay attacks. Use `X-Date` rather than `Date` to avoid
conflicts with HTTP libraries.
```
X-Date: Fri, 17 Jan 2020 19:59:29 GMT
```
**`Content-sha512`** — Base64-encoded SHA-512 hash of the raw request
body. Ingo uses this to verify body integrity — if the hashes don't
match, the request is rejected. Use RAW (not hex) output from your
hashing library before Base64 encoding.
```
Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08EYbfH...
```
**`Content-Length`** — Byte length of the request body.
```
Content-Length: 398
```
**`Content-Type`** — Always `application/json`.
```
Content-Type: application/json
```
The header string is a space-separated, lowercase list of the header
names you are signing, in the order they appear in the signature string.
Always begin with `request-line`.
```
request-line x-date content-type content-sha512 content-length
```
This exact string becomes the `headers` parameter value in your
`Authorization` header.
The signature string is constructed by concatenating the values of each
item in the header string, separated by newline characters `\n`. No
trailing newline.
For `request-line` — append the HTTP request line:
```
POST /gateway/verify HTTP/1.1
```
For each header — append `lowercased-header-name: value`:
```
x-date: Fri, 17 Jan 2020 19:59:29 GMT
content-type: application/json
content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08EYbfH...
content-length: 398
```
Concatenated signature string:
```
POST /gateway/verify HTTP/1.1\nx-date: Fri, 17 Jan 2020 19:59:29 GMT\ncontent-type: application/json\ncontent-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08EYbfH...\ncontent-length: 398
```
Sign the signature string using **HMAC-SHA512** with your secret key.
Base64-encode the result.
Use **RAW** output from your HMAC library — not hex. Base64-encoding
hex output will produce an incorrect signature.
The resulting value is your `signature` parameter:
```
hAMqhSX6eogO1QpES9Dg9WynJWJPNxFLe1wtV4ppfvmGmqpYCiJYm6lqrHNjcmQUZCyMBdK86Zkm+m3BJwj3XA==
```
Combine all parameters into the `Authorization` header:
```
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="hAMqhSX6eogO1QpES9Dg9WynJWJPNxFLe1wtV4ppfvmGmqpYCiJYm6lqrHNjcmQUZCyMBdK86Zkm+m3BJwj3XA=="
```
***
## Full request example
```http theme={null}
POST /gateway/verify HTTP/1.1
Host: payapi-sandbox.ingo.money
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="hAMqhSX6eogO1QpES9Dg9WynJWJPNxFLe1wtV4ppfvmGmqpYCiJYm6lqrHNjcmQUZCyMBdK86Zkm+m3BJwj3XA=="
X-Date: Fri, 17 Jan 2020 19:59:29 GMT
Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08EYbfHID7zQJXihCxjmGKRULH+QFYxYch05aDPKjWb+Q==
Content-Length: 398
Content-Type: application/json
{
"participant_id": 00000,
"account_type": "CA",
"recipient_first_name": "Tom",
"recipient_last_name": "Smith",
"account": "4264531111111115",
"expiration_date": "2212",
"cvv": "000",
"recipient_address1": "123 Main St.",
"recipient_city": "Smallville",
"recipient_state": "TX",
"recipient_zip": "93245",
"recipient_phone": "8015555555",
"participant_unique_id1": "0001",
"timestamp": 1579291169,
"version": "11"
}
```
***
## Environments
| Product | Sandbox | Production |
| ---------------------------------- | --------------------------------------------------- | ---------------------------------------------- |
| IngoPay API | `https://payapi-sandbox.ingo.money` | `https://payapi.ingo.money` |
| Notify — Classic & Managed Parties | `https://payapi-sandbox.ingo.money` | `https://payapi.ingo.money` |
| Embedded Account Capture | `https://iip-session-management-uat.ingo.money` | `https://iip-session-management.ingo.money` |
| Banking Platform | `https://api.sdev.banking.ingopayments.tech/api/v4` | `https://api.banking.ingopayments.tech/api/v4` |
Use sandbox credentials for all development and testing. Production credentials are issued after sandbox certification is complete.
***
## Common errors
| Error | Cause | Fix |
| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Invalid signature | Verify secret, signature string construction, and RAW (not hex) HMAC output |
| `401 Clock skew` | `X-Date` outside ±300s window | Sync your server clock with NTP |
| `400 Body hash mismatch` | `Content-sha512` doesn't match body | Recompute hash from the exact body bytes being sent |
| `400 Missing header` | Required header absent | Ensure `X-Date`, `Content-sha512`, `Content-Length`, and `Content-Type` are all present |
***
## Implementation notes
* The `secret` is never included in the request — only used locally to generate the signature
* Include `participant_id` in the request **body**, not in the headers
* Additional headers beyond the required set may be included and signed — add them to the header string in the order they appear
* The header string order in your `Authorization` header must exactly match the order used to build your signature string
# Best Practices
Source: https://developers.ingopayments.com/docs/hub/best-practices
Recommended practices for request management, fraud controls, prefunding, communication, and statement descriptors.
Following these practices helps ensure your integration remains stable, secure, and operationally resilient as your disbursement program scales.
***
## Request Management
Ingo Payments enforces rate limits to protect platform stability for all clients. Limit your integration to **no more than five simultaneous requests per second** to avoid triggering rate-limiting controls.
If your program requires higher throughput — for example, during batch processing or high-volume disbursement windows — contact Ingo's Partner Technical Support before you hit the limit. Your team can work with you to evaluate your volume needs and configure appropriate accommodations.
***
## Fraud Controls
Outbound payment programs create a direct cash-out channel that attracts fraud. Implementing layered controls — both internal to your organization and external through your banking and vendor relationships — significantly reduces exposure.
Internal controls should include approval workflows, segregation of duties, and transaction monitoring. External controls — such as Ingo's risk verification services and your banking partner's transaction alerts — provide an independent validation layer. Together they ensure that breakdowns in one layer don't create undetected exposure.
Key principles for outbound payment fraud control:
Maintain strict **segregation of duties** so no single employee can both initiate and approve a payment. Establish a **reconciliation cadence** that identifies discrepancies before they compound. Review **recipient verification configurations** regularly to ensure your risk tolerance matches current fraud patterns. Treat payment failures and unusual return rates as fraud signals and investigate promptly.
***
## Prefunding
If your program is funded exclusively via ACH or wire transfer, maintain a **3–5× projected volume buffer** in your prefund account at all times. ACH and wire rails are subject to bank cutoffs, non-business days, and settlement delays — without a buffer, funding gaps can interrupt disbursements.
Plan your funding schedule around the rolling 15 and 30-day velocity limits configured for your program. Monitor your prefund balance and initiate replenishment well before the buffer is depleted — same-day wires and next-day ACH are not always feasible or timely options.
***
## Communication Management
Maintain a **distribution list** for Ingo operational communications rather than routing them to a single contact. Maintenance schedules, outage notifications, and reconciliation alerts need to reach the right people across operations, finance, and technology simultaneously.
Review and update your distribution list whenever key personnel change. Establish internal escalation paths so your team knows who to contact and what actions to take when critical communications arrive.
***
## Statement Descriptors
Statement descriptors appear on cardholders' and bank account holders' transaction records. A clear descriptor reduces customer inquiries, disputes, and chargebacks.
Limit your descriptor to **10–13 characters** — longer values may be truncated by networks or issuers. Include a reference to your company name so recipients can immediately identify the transaction source. Card networks and issuers may override your configured descriptor at their discretion; this is outside Ingo's control.
Work with your Integration Manager to configure descriptors by transaction type during onboarding.
# Compliance
Source: https://developers.ingopayments.com/docs/hub/compliance
PCI DSS, OFAC, AML, KYB/KYC, and regulatory requirements applicable to your Ingo Payments integration.
Compliance is a foundational requirement for every client integration — not a procedural formality. Payment activities must adhere to applicable regulatory frameworks, and Ingo's compliance team is structured to guide you through this process efficiently and without unnecessary friction.
***
## Our Commitment
Ingo brings deep experience operating within the regulatory landscape that governs modern financial transactions, including NACHA rules, AML obligations, and BSA-related controls. Throughout the integration process, Ingo's compliance team acts as a consultative partner — helping your team interpret requirements, implement the right controls, and understand how compliance activities create a structured path to production readiness rather than a barrier to it. The goal is a seamless onboarding experience that positions your program for long-term success.
***
## What Compliance Covers
**Regulatory frameworks** — ACH processing requires adherence to NACHA operating rules, including authorization standards and return thresholds. FinCEN oversight under the Bank Secrecy Act mandates recordkeeping, reporting, and monitoring for illicit financial activity.
**AML and KYB/KYC** — Anti-money laundering requirements call for robust controls to identify and mitigate risks associated with fraud, money laundering, and terrorist financing. This includes Know Your Business (KYB) and Know Your Customer (KYC) processes, ongoing transaction monitoring, and risk-based due diligence.
**Documentation review** — Ingo's compliance team will request documentation to assess and validate your business model and risk profile. This typically includes corporate formation documents, ownership and beneficial ownership details, financial statements, bank account verification, processing volume projections, use case descriptions, and internal AML or fraud prevention policies. Depending on your industry and risk level, additional documentation may be required.
***
## Sponsor Bank Approval
A key milestone in the compliance process is sponsor bank approval. The sponsor bank conducts its own independent review of your business model, risk profile, and projected transaction activity before granting approval to operate on their rails.
Ingo's compliance team manages this process — gathering, validating, and packaging all required due diligence materials to support the bank's assessment. This includes financial records, business documentation, ownership details, and an overview of your expected payment flows. A thorough and transparent submission is the most effective way to obtain sponsor bank approval efficiently and keep the path to production clear.
***
## Why This Effort Is Required
Compliance requirements exist to protect your program, your customers, and Ingo's platform:
Regulatory adherence ensures your program operates within federal and network rules, reducing the risk of fines, penalties, or program shutdowns. Fraud and financial crime controls establish the safeguards needed to detect and contain suspicious activity before it creates material exposure. Banking partner requirements satisfy the due diligence expectations of sponsor banks and payment network participants — approval cannot be bypassed. And comprehensive risk management enables safe program growth by surfacing and addressing client-specific risks early rather than after launch.
Your Ingo Account Manager coordinates the compliance review process and will connect you with Ingo's compliance team at the appropriate stage of onboarding.
# Custom Domain & DNS Setup
Source: https://developers.ingopayments.com/docs/hub/domain-setup
DNS configuration requirements for Embedded Account Capture and Notify — custom CNAMEs, email authentication records, and domain whitelisting.
Both Embedded Account Capture and Notify require custom domain configuration before going live. These are white-labeled deployments — the URLs your recipients see correspond to your domain, not Ingo's. Your Integration Manager coordinates the domain naming during onboarding and confirms all required values. This page documents what your DNS and IT teams need to configure.
All CNAME records and DNS values shown below use placeholder names. Your Integration Manager provides the exact values — including client-specific CNAME targets and email authentication keys — during the implementation phase.
***
## Embedded Account Capture
The Embedded Account Capture iFrame requires one custom domain per environment. The domain must correspond to the root domain of the application embedding the iFrame — this is used as a security control, as Ingo whitelists authorized application domains on the backend.
### Domain architecture
A single iFrame instance operates under a single `participant_id`. If your application uses multiple domain naming conventions (e.g., different subdomains per brand or environment), each requires a separate iFrame configuration, a separate `participant_id`, and a separate set of HMAC credentials.
Work with your Integration Manager early to map your application domain structure to the required iFrame and credential topology.
### CNAME records
Create the following DNS CNAME records in your DNS provider:
**Sandbox**
```
webplugin-uat.{your-domain}.com CNAME {your-client-name}.webplugin.uat.ingo.money
```
**Production**
```
webplugin.{your-domain}.com CNAME {your-client-name}.webplugin.ingo.money
```
Replace `{your-domain}` with your organization's root domain and `{your-client-name}` with the identifier provided by your Integration Manager.
***
## Notify — Classic & Managed Parties
Notify is a fully hosted solution and requires two custom domains: one for the visible Digital Payment Center URL presented to recipients, and one for the embedded iFrame within that experience. Both must be configured per environment.
### CNAME records
Create the following DNS CNAME records in your DNS provider:
**Production**
```
digitalpay.{your-domain}.com CNAME {your-domain}.digitalpay.ingo.money
webplugin.{your-domain}.com CNAME {your-domain}.webplugin.ingo.money
```
If you support multiple brands requiring distinct Digital Payment Center experiences, you will need two production URLs per branded experience. Your Integration Manager will assist in defining the naming convention for each.
### Email DNS records
Notify uses your domain to send email notifications to recipients — this preserves your domain reputation and improves deliverability with inbox providers. Four DNS records are required.
Your Integration Manager provides the exact values for your organization during onboarding. The record types and their structure are:
**SPF record** — authorizes Ingo's sending infrastructure to deliver email on behalf of your domain:
```
{your-domain}.com. TXT "v=spf1 ip4:{ingo-smtp-ip} -all"
```
**DKIM record** — cryptographic signature proving email authenticity:
```
spop1024._domainkey.{your-domain}.com IN TXT "k=rsa; p={your-dkim-public-key}"
```
**Yahoo Verification Key** — required for deliverability to Yahoo and AOL inboxes:
```
{your-domain}.com. TXT "yahoo-verification-key={your-yahoo-verification-key}"
```
**DMARC record** — instructs receiving mail servers how to handle unauthenticated email from your domain:
```
_dmarc.{your-domain}.com TXT "v=DMARC1; p=none; rua=mailto:dmarc@{your-domain}.com"
```
The DMARC policy (`p=none`, `p=quarantine`, or `p=reject`) should align with your organization's existing email security posture. Your Integration Manager can advise on a policy compatible with Ingo's sending infrastructure if you do not have an existing DMARC policy in place.
### SMS delivery options
Notify can deliver recipient notifications via SMS through two supported approaches — you choose based on your program's infrastructure and brand requirements:
**Ingo-managed SMS** — Ingo sends SMS notifications directly to recipients on your behalf. Prior to activation, Ingo must obtain documented recipient consent. Ingo provides a consent form for this purpose, though it identifies Ingo as the notification sender rather than your brand. This approach is well-suited for programs where transparency about Ingo's role as a service provider is acceptable.
**Client-managed SMS** — Many clients prefer to send SMS notifications through their own SMS platform (e.g., Twilio, Bandwidth, or a similar provider) for full brand control. Recipients see only your brand in the notification. Your system delivers the notification and directs recipients to the Ingo-hosted disbursement URL. This approach gives you complete control over the recipient communication experience and works well for programs with existing SMS infrastructure.
Both approaches are supported and can coexist within a single program. Contact your Integration Manager to confirm which configuration is appropriate for your use case.
***
## What to prepare
Before your kickoff call, confirm the following with your IT and DNS teams:
* The root domain(s) of your application(s) embedding the iFrame
* Whether you support multiple domain naming conventions requiring multiple iFrame instances
* Whether you have an existing DMARC policy in place
* Whether you have an existing SMS platform you intend to integrate, or plan to use Ingo-managed SMS
Your Integration Manager will provide exact CNAME targets, DKIM keys, Yahoo verification keys, and authorized domain values once your program configuration is confirmed.
# Embedded Documents
Source: https://developers.ingopayments.com/docs/hub/embedded-documents
Display a client-hosted document to recipients inside the Digital Payment Center during the disbursement flow — configured with an AWS S3 pre-signed URL and CORS. Available for Notify — Classic and Notify — Managed Parties.
Embedded Documents lets you present a document you host — for example, an explanation of benefits, a policy summary, or terms — to the recipient inside the Digital Payment Center (DPC). The document renders early in the acceptance flow, before the recipient selects how they want to receive their disbursement, and remains accessible from the payment confirmation screen.
The mechanism is the same for **Notify — Classic** and **Notify — Managed Parties**: you host a single document, generate a time-limited pre-signed URL, and configure CORS so Ingo hosts can load it. Ingo enables the service and places the document at a fixed point in the flow.
This feature **displays a document only**. It does not capture or report recipient acknowledgement or consent, and it does not provide e-signature or document generation. If you need proof of acknowledgement, that is a separate requirement — talk to your Integration Manager.
***
## How it works
Host the document in an AWS S3 bucket and generate a single time-limited pre-signed URL. You control the link's lifetime at generation time.
Add the Ingo host URLs to your bucket's CORS `AllowedOrigins` list (GET method) so Ingo can load the document.
Provide Ingo the hosted URL and your chosen display presentation. Ingo enables the Embedded Document service on your Notify configuration and places the document at the fixed point in the flow.
At disbursement time the recipient is shown the document early in the flow, then proceeds to select their payment method. The document is also reachable from the payment confirmation screen.
***
## What you configure vs. what Ingo configures
Host the document, generate the pre-signed URL, combine multiple documents into one file, set link expiration to meet or exceed your payment expiration window, and add Ingo hosts to CORS `AllowedOrigins`.
Provide the exact Ingo host URLs for whitelisting, confirm your payment expiration window, enable the Embedded Document service, place the document at the fixed flow position, and configure your selected display presentation.
Placement in the flow is fixed and not configurable. You choose the **display presentation** (below); you do not choose where in the flow the document appears.
***
## Single document only
The feature renders **one** hosted URL. To display multiple documents, combine them into a single file (for example, one PDF) and provide Ingo with one hosted URL.
***
## AWS S3 configuration
AWS S3 is the only validated hosting path. A non-AWS solution must support time-limited pre-signed URLs and a CORS-equivalent origin allowlist; supporting it may require additional Ingo assessment before it can be enabled. Confirm your hosting solution with your Integration Manager early.
### Pre-signed links
Generate a single time-limited pre-signed link for the document. The maximum lifetime depends on how you sign it:
| Signing method | Maximum link lifetime |
| ----------------------------------- | --------------------- |
| S3 Console (temporary credentials) | Up to 12 hours |
| S3 CLI / SDK (IAM user credentials) | Up to 7 days |
You own the expiration and any refresh cadence. See the AWS guides on [sharing a pre-signed URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html) and [using pre-signed URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html).
**Align link expiration with your payment expiration window.** The S3 link expiration (which you own) must meet or exceed the payment expiration window (a configuration Ingo holds for you). If the link expires before the payment does, a recipient who returns later will not be able to view the document. Confirm your payment expiration window with your Integration Manager and set your link lifetime — and any refresh approach — to match or exceed it.
### CORS
CORS lets a web application loaded on one domain (your Ingo Money host) load a resource from another domain (your S3 bucket). To display your document, your Ingo hosts must be whitelisted in the bucket's CORS configuration in the S3 **Permissions** console.
Add the Ingo host URLs to the `AllowedOrigins` array, each in quotes and comma-separated, with `GET` in `AllowedMethods`:
```json theme={null}
[
{
"AllowedHeaders": ["*"],
"AllowedMethods": ["GET"],
"AllowedOrigins": [
"https://{ingo-host-url-1}",
"https://{ingo-host-url-2}"
],
"ExposeHeaders": []
}
]
```
Request your exact Ingo host URLs (sandbox and production) from your Integration Manager. Whitelist the sandbox hosts for UAT and the production hosts before go-live. See the AWS [CORS configuration examples](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html).
***
## Display presentations
Two display presentations are available. You choose one; placement in the flow is fixed regardless of the option.
The default mode. The document is hosted in a frame with controls to toggle between pages, download, print, and more.
![Digital Payment Center showing a document in a framed viewer with page, download, and print controls]()
Displays all pages of the document in a vertical layout on the page.
![Digital Payment Center showing all pages of a document rendered vertically inline]()
Screenshots are illustrative using sample content; your recipients see your branded Digital Payment Center and your hosted document.
Some browser components, such as ad blockers, can interfere with document display. If a recipient reports a blank or missing document, an extension is a likely cause.
***
## Confirmation screen access
Regardless of the display presentation, the document is also reachable from the payment confirmation screen as a labeled link, so recipients can revisit it after completing their selection.
![Payment confirmation screen with a labeled button linking to the document]()
***
## Prerequisites
* A document hosting solution that supports time-limited pre-signed URLs (AWS S3 is the validated path).
* Ability to configure CORS to whitelist Ingo host URLs for GET requests.
* A single hosted document URL (multiple documents combined into one file).
* A confirmed display presentation (Full Window or In-Line).
* You are already live or in-flight on Notify — Classic or Notify — Managed Parties. Embedded Documents is a feature add, not a standalone integration.
***
## Testing
During UAT, validate that the document renders at the correct step before payment-method selection, across your entry points (email, SMS, and web). Confirm the pre-signed link resolves, CORS is correctly configured, link-expiry behavior matches your payment expiration window, and the selected display presentation renders as expected. Your Integration Manager provides a test plan and validation support.
# Code Reference
Source: https://developers.ingopayments.com/docs/hub/errors
API response codes, code families, and handling guidance across all Ingo Payments products.
Ingo Payments returns numeric status codes across both synchronous API responses and asynchronous webhook events. Understanding the code structure helps you build reliable integrations that handle outcomes correctly — whether the code arrives in a response body or a webhook payload, the category and description apply the same way.
***
## Code families at a glance
Every response code falls into a family that signals the category of outcome. Use this table to understand the meaning of any code range at a high level and determine the right action for your integration.
| Code Range | Category | Meaning | Recommended Action |
| ---------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `100–110` | **Success** | Transaction completed, in progress, or idempotent result returned | No action required |
| `111–129, 131–132` | **Soft Verification Results** | Transaction approved; a verification check returned a partial or inconclusive result | Proceed; review the specific code if downstream action is needed |
| `4xx` | **Request & Auth Errors** | The request was rejected due to bad input, invalid credentials, or a suspended account | Fix the request before retrying — these errors will not self-resolve |
| `5xx` | **System & Communication Failures** | A timeout, routing failure, or unexpected error occurred | Retry with exponential backoff; contact Ingo support if persistent |
| `600–616` | **Validation & Velocity Errors** | A field failed validation or a program limit was reached | Correct the field value, amount, or transaction timing |
| `700–742` | **Transaction & Routing** | A transaction-level outcome — destination unavailable, limit exceeded, or routing issue | Check the specific code; most are terminal for the current attempt |
| `750–815` | **Card Data & Token Errors** | Card input is invalid, a token is missing or incorrect, or track data is required | Correct input or re-tokenize the account |
| `851–867` | **Card Issuer Declines** | The card issuer rejected the transaction | Do not retry automatically; direct the recipient to contact their card issuer |
| `9xx` | **General System Errors** | An unclassified internal error occurred | Contact Ingo support; include the timestamp and `participant_unique_id1` |
| `780–787` | **Notify Transaction Status** | A Notify disbursement is in an incompatible state for the requested action | Check the transaction's current state before retrying |
| `1100–1170` | **Notify — Auth, Verification & Payment Events** | Authentication, identity verification, OFAC screening, and payment status codes shared across all Notify products | Informational — review the specific code for the lifecycle stage |
| `1123–1124, 1171–1172` | **Notify — Managed Parties Approvals** | Approval decision, completion, and payment suspended codes specific to multi-party disbursement flows | Informational — approval decisions gate payment release |
| `1200–1246` | **Notify — Notification Events** | Email and SMS notification delivery codes sent to recipients and parties throughout the disbursement lifecycle | Informational — confirms what communication was sent |
| `1300–1303` | **Banking Platform** | Entity, ledger, transaction, and hold lookup failures specific to the Ingo Banking Platform | Check the specific resource identifier in the request |
Codes in the `1100–1246` range are Notify product event codes. They appear in webhook payloads and, in some cases, synchronous API responses depending on the integration point. Codes in the `130` and `1106–1108` range appear in both contexts depending on your program configuration.
***
## Status & Event Code Reference
| Code | Message | Applicable Call | Description |
| ----- | --------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `100` | Success | Verify, Process, Search | Transaction completed successfully. |
| `101` | Success — Idempotent Response | Verify, Process | The `participant_unique_id1` was previously processed successfully. No new transaction was created. |
| `102` | Success — Pending Issuer Response | Process | Response from issuer not received within the configured timeout. Applicable to push transactions. |
| `103` | Success — Payment Request Queued | Async Process | Async process request accepted and queued for processing. |
| `104` | In Progress — Idempotent Response | Process | A prior request with this `participant_unique_id1` is still processing. No new posting attempt was initiated. |
These codes indicate the transaction was approved but a verification check returned a partial, inconclusive, or non-matching result. Review the specific code to determine whether downstream action is appropriate for your program configuration.
**Card — AVS (Address Verification Service)**
| Code | Description |
| ----- | ----------------------------------------------------------------------- |
| `111` | Street address matches; zip does not |
| `112` | Street address matches; zip could not be verified (incompatible format) |
| `113` | Street address and zip could not be verified (incompatible formats) |
| `114` | Issuer is not an AVS participant or did not return a result |
| `115` | Address information not verified |
| `116` | No Match |
| `117` | Zip matches; street address could not be verified (incompatible format) |
| `118` | Issuer unavailable or timed out |
| `119` | Zip matches; street address does not |
**Card — ANI (Account Name Identification)**
| Code | Description |
| ----- | -------------------------- |
| `127` | Account name partial match |
| `128` | Account name no match |
| `131` | Match not performed |
| `132` | Match not supported |
**Bank Account — ANV / NAV (Account & Name Validation)**
| Code | Description |
| ----- | ----------------------------------------------------- |
| `122` | No data available or non-participating issuer (ANV) |
| `123` | No data available from issuer (NAV) |
| `124` | Address did not match (NAV) |
| `125` | Customer name or name and address did not match (NAV) |
| `126` | Customer or business name did not match (NAV) |
These codes indicate the request was rejected before processing. Correct the issue before retrying — they will not self-resolve.
| Code | Message | Description |
| ----- | ------------------- | -------------------------------------------------------------------- |
| `400` | Transaction Failure | One or more required parameters are missing or null |
| `401` | Transaction Failure | Request parameters are incorrect |
| `402` | Transaction Failure | Timestamp in signature is too distant from current time (clock skew) |
| `403` | Transaction Failure | API key does not exist |
| `404` | Transaction Failure | API key has been suspended |
| `405` | Transaction Failure | Client has been temporarily suspended |
| `406` | Transaction Failure | Participant ID does not exist |
| `407` | Transaction Failure | Participant signature does not match expected value |
| `408` | Transaction Failure | Authorization failure |
| `412` | Transaction Failure | Unsupported HTTP method |
| `413` | Transaction Failure | Invalid S2P type |
| `414` | Transaction Failure | Invalid debit type |
| `415` | Transaction Failure | Route API disabled |
| `516` | Transaction Failure | Unauthorized distribution type |
| `530` | Transaction Failure | Unauthorized account type |
| `609` | Transaction Failure | Invalid request to payment gateway |
| `612` | Unauthorized | Invalid or unauthorized value for `source_of_funds` |
| `613` | Unauthorized | Participant not enabled for `third_party_token` |
| `614` | Unsupported | Third-party token provider not currently supported |
These codes indicate a timeout, routing failure, or unexpected system error. They are transient and retry-eligible. See the [Retry Logic guide](/docs/hub/retry-logic) for recommended retry intervals based on your customer experience model. Contact Ingo support if the error persists, and include the timestamp and `participant_unique_id1` from the failed request.
| Code | Description |
| ----- | --------------------------------------------------------- |
| `500` | General error — contact Ingo Payments support immediately |
| `501` | Response from endpoint was invalid |
| `502` | Process timeout |
| `523` | AVS service connection error |
| `524` | AVS response parse failure |
| `525` | AVS response bad structure |
| `706` | Transaction routing failure |
| `707` | Transaction routing failure |
| `709` | Transaction routing failure |
| `717` | Transaction routing failure |
| `718` | Transaction routing failure |
| `750` | Response from endpoint not recognized |
| `751` | Response from endpoint not defined |
| `763` | Route not configured for client processing |
| `802` | Banking Platform transaction routing failure |
| `900` | Account identity lookup error |
| `901` | Account identity lookup error |
| `990` | General error — contact Ingo Payments support |
| `999` | General error — contact Ingo Payments support |
These codes indicate a field validation failure or a program limit has been reached. Correct the field value, transaction amount, or verify the transaction is within your configured program limits before retrying.
| Code | Description |
| ----- | --------------------------------------------------------------------------- |
| `600` | Field validation error — see validation error details in the response |
| `603` | Transaction amount is outside your allowed range (above max or below min) |
| `604` | Insufficient funds — amount exceeds prefund balance or daily processing cap |
| `615` | Invalid transaction amount |
| `616` | Invalid transaction type |
| `711` | Exceeds single transaction amount limit |
| `712` | Exceeds daily transaction amount limit |
| `713` | Exceeds rolling 7-day transaction amount limit |
| `714` | Exceeds rolling 30-day transaction amount limit |
| `715` | Exceeds maximum transactions per rolling 30-day period |
| `716` | Exceeds rolling 15-day transaction amount limit |
| `719` | Transaction amount is below the issuer minimum |
| `720` | Transaction amount is above the issuer maximum |
| `722` | Exceeds maximum amount per store daily limit (retail clients) |
| `723` | Exceeds maximum transactions per store daily limit (retail clients) |
| `724` | Store not authorized for this transaction type (retail clients) |
| `975` | Routing disabled by sponsor bank — contact Ingo support |
| Code | Description |
| ------ | ------------------------------------------------------------------------------------ |
| `700` | Account not currently available for processing |
| `701` | Payment destination no longer available for processing |
| `703` | Issuer or Payee ID does not exist |
| `708` | Transaction attempted is invalid |
| `710` | Issuer declined — customer should contact their card issuer |
| `721` | Payment causes card balance to exceed the total allowable limit |
| `790` | Declined — Stand In; issuer response not received within timeout (pull transactions) |
| `1130` | Real-Time Payments (RTP) attempted; retried via standard bank account network |
Hard declines from card verification services. These are terminal for the current attempt — the recipient's card data does not pass the configured verification checks.
**AVS Hard Declines**
| Code | Description |
| ----- | -------------------------------------------------- |
| `510` | AVS timeout |
| `513` | AVS unknown error |
| `753` | Declined — street matches, zip does not |
| `754` | Declined — street matches, zip incompatible format |
| `755` | Declined — street and zip incompatible formats |
| `756` | Declined — issuer not participant or no result |
| `757` | Declined — address not verified |
| `758` | Declined — no match |
| `759` | Declined — zip matches, street incompatible format |
| `760` | Declined — retry; issuer unavailable or timed out |
| `764` | Declined — zip matches, street does not |
**CVV Hard Declines**
| Code | Description |
| ----- | ----------------- |
| `512` | CVV timeout |
| `515` | CVV unknown error |
| `765` | CVV declined |
**ANI Hard Declines**
| Code | Description |
| ----- | ------------------------------------- |
| `788` | Declined — account name partial match |
| `789` | Declined — account name no match |
| `791` | Declined — match not supported |
| `792` | Declined — match not performed |
**Card Data & Token Errors**
| Code | Description |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| `800` | Card swipe required — track data required for this card type |
| `801` | Invalid track1 data — retry card swipe |
| `802` | Invalid track2 data — retry card swipe |
| `803` | Invalid card expiration date |
| `804` | Invalid token |
| `805` | Token not found — the supplied token does not exist |
| `806` | PAN data unavailable — the token is valid but no account (PAN) data could be retrieved; re-tokenize the account |
| `815` | Invalid BillPay token — invalid token used with BP account type |
| `1041` | Bad check digit test |
| `1042` | Check digit rejected — account number failed validation |
Hard declines from bank account verification services (Routing Number Validation, Account Number Validation, Name on Account Validation). These are terminal for the current attempt.
**RNV — Routing Number Validation**
| Code | Description |
| ----- | --------------------------------------------------- |
| `743` | Invalid routing number — not available or incorrect |
**ANV — Account Number Validation**
| Code | Description |
| ----- | ---------------------------------------------- |
| `767` | Declined — no data or non-participating issuer |
| `768` | Declined — invalid routing number |
| `769` | Declined — invalid account number |
**NAV — Name on Account Validation**
| Code | Description |
| ----- | ---------------------------------------------------------- |
| `776` | Declined — no data from issuer |
| `777` | Declined — address did not match |
| `778` | Declined — customer name or name and address did not match |
| `779` | Declined — customer or business name did not match |
The card issuer rejected the transaction. Do not retry automatically. Direct the recipient to contact their card issuer for more information. The specific decline reason may indicate a card status issue (lost, stolen, restricted) or an account limit that cannot be resolved without issuer action.
| Code | Description |
| ----- | ----------------------------------------------------------------------------- |
| `851` | Issuer declined — do not honor |
| `852` | Issuer declined — invalid account number (no such number) |
| `853` | Issuer declined — invalid transaction |
| `854` | Issuer declined — transaction not permitted to cardholder |
| `855` | Network routing failure — issuer not found, not supported, or routing unknown |
| `856` | Issuer declined — stolen card; pick up requested |
| `857` | Issuer declined — pick up card requested |
| `858` | Issuer declined — exceeds account approval amount limit |
| `859` | Issuer declined — restricted card |
| `860` | Issuer declined — lost card; pick up requested |
| `861` | Routing network inoperative or malfunctioning |
| `862` | Issuer declined — insufficient funds |
| `863` | Issuer declined — exceeds account frequency limit |
| `864` | Issuer declined — no checking or credit account |
| `865` | Issuer declined — invalid transaction amount |
| `866` | Account blocked by cardholder |
| `867` | Account blocked by Ingo |
**Workflow Events**
| Code | Description |
| ----- | ------------------------------------------------------------------------------------------------------------ |
| `130` | OFAC Suspended — initial hit detected; transaction processing suspended pending review by Ingo Risk Services |
**System Errors**
| Code | Description |
| ----- | ------------------ |
| `511` | OFAC timeout |
| `514` | OFAC unknown error |
**Hard Decline**
| Code | Description |
| ----- | ------------------------------------------------------- |
| `752` | OFAC declined — potential match confirmed; do not honor |
Code `130` is a success-class code — the transaction was accepted but is held pending OFAC review. It is distinct from `752`, which is a terminal decline. Codes `1106` (suspended), `1107` (cleared), and `1108` (failure) are the corresponding Notify webhook event codes and are documented in the **Notify — Verification & Payment Events** section above.
| Code | Description |
| ----- | -------------------------------------------------------------------------- |
| `540` | Check Stop service error — request unsupported by endpoint |
| `541` | Check Stop unknown error — endpoint timeout or error |
| `744` | Check Cancel failure — check already canceled or in a non-cancelable state |
| `745` | Check Stop failure — check already stopped or in a non-stoppable state |
| `746` | Check Stop failure — check already posted today |
| `747` | Check Stop failure — teller check hold on account |
| `748` | Check Stop failure — error locating DDA |
| `749` | Check Stop failure — temporarily unable to place stop; retry |
These codes are returned by the Notify API when a staged disbursement is in an incompatible state for the requested action. Check the transaction's current state before retrying.
| Code | Description |
| ----- | --------------------------------------------------------- |
| `780` | Transaction has already been claimed by the recipient |
| `781` | Transaction is not in a claimable state |
| `782` | Transaction has already been terminated |
| `783` | Staged transaction amount and process amount do not match |
| `784` | Unauthorized to use staged transactions |
| `786` | Transaction in progress — awaiting network response |
| `787` | Transaction has already been canceled |
Shared across Notify — Classic and Notify — Managed Parties.
**Party Authentication**
| Code | Message | Description |
| ------ | --------------------------- | --------------------------------------------------------------------------- |
| `1100` | Authentication Success | Recipient or party successfully authenticated to the Digital Payment Center |
| `1101` | Authentication Soft Failure | Authentication succeeded with a soft failure condition |
| `1102` | Authentication Failure | Recipient or party failed authentication to the Digital Payment Center |
| `1131` | SSO Authentication Success | Recipient successfully authenticated via Single Sign-On |
**OTAC (One-Time Authentication Code)**
| Code | Message | Description |
| ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `1151` | OTAC Send Limit Reached | Maximum number of OTACs for this transaction, party, and role has been reached — no further OTACs can be generated |
| `1152` | OTAC Authentication Failure | Provided OTAC did not match the outstanding code for this transaction, party, and role |
| `1153` | OTAC Generated — SMS | A new OTAC was generated and sent via SMS |
| `1154` | OTAC Generated — Email | A new OTAC was generated and sent via email |
| `1155` | OTAC Authentication Success | Provided OTAC matched the outstanding code |
**Overall Authentication Outcome**
| Code | Message | Description |
| ------ | ------------------------------ | ------------------------------------------------------------------------------------- |
| `1160` | Overall Authentication Success | User completed authentication and was granted access |
| `1161` | Overall Authentication Failure | Maximum failed attempts for dynamic party authentication reached — access not granted |
| `1162` | Overall Authentication Failure | OTAC send limit reached — access not granted |
| `1163` | Overall Authentication Failure | OTAC inaccessible — access not granted |
| `1164` | Overall Authentication Failure | Maximum failed OTAC attempts reached — access not granted |
Shared across Notify — Classic and Notify — Managed Parties.
**Recipient Verification — RVDM**
| Code | Message | Description |
| ------ | ----------------- | ----------------------------------------------------------- |
| `1103` | RVDM Success | Recipient Verification Data Matching completed successfully |
| `1104` | RVDM Soft Failure | RVDM succeeded with a soft failure condition |
| `1105` | RVDM Failure | Recipient Verification Data Matching failed |
**Recipient Verification — OFAC**
| Code | Message | Description |
| ------ | -------------- | -------------------------------------------------------------------------- |
| `1106` | OFAC Suspended | Initial OFAC hit detected; transaction processing suspended pending review |
| `1107` | OFAC Cleared | OFAC hit cleared as false positive; processing resumes |
| `1108` | OFAC Failure | OFAC hit confirmed; transaction processing terminated |
**Account Verification — PayPal**
| Code | Message | Description |
| ------ | --------------------------------- | ------------------------------------------------------------------- |
| `1148` | Account Verification Success | PayPal account verification completed successfully |
| `1149` | Account Verification Soft Failure | PayPal account verification succeeded with a soft failure condition |
| `1150` | Account Verification Failure | PayPal account verification failed |
**Payment Events**
| Code | Message | Description |
| ------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `1109` | Disbursement Expired | Disbursement reached the configured expiration period without being claimed — payment terminated |
| `1110` | Disbursement Canceled | Disbursement canceled by the client |
| `1111` | Check Disbursement — Address Verified | Recipient confirmed the address provided by the client |
| `1112` | Check Disbursement — Address Not Verified | Recipient did not confirm the address provided by the client |
| `1113` | Payment Terminated | Recipient could not complete a payment transaction — request terminated |
| `1114` | Payment Returned | Previously processed payment was returned by the account issuer |
| `1125` | Payment Success — Card | Card payment to recipient completed |
| `1126` | Payment Success — ACH | ACH payment to recipient completed |
| `1132` | Payment Terminated | Transaction canceled by recipient |
| `1133` | Payment Success — Check | Check payment originated to recipient |
| `1134` | Payment Success — PayPal | PayPal payment to recipient completed |
| `1135` | Elected Termination | Recipient elected not to receive disbursement — cancellation requested |
| `1136` | Elected Termination | Recipient elected not to receive disbursement — direct vendor disbursement requested |
| `1137` | Elected Termination | Recipient elected not to receive disbursement — alternate recipient requested |
| `1138` | Elected Termination | Recipient elected not to receive disbursement — reason unspecified |
| `1139` | Elected Termination | Recipient elected not to receive disbursement — reason indicated by reported reason code |
| `1170` | Payment Success — Real-Time Payment | RTP payment to recipient completed |
Codes specific to multi-party disbursement flows. These do not appear in Notify — Classic.
| Code | Message | Description |
| ------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `1120` | Unknown Party | Specified party could not be identified for this transaction |
| `1123` | Approval — Approved | Approver acted and approved the disbursement |
| `1124` | Approval — Declined | Approver acted and declined the disbursement |
| `1171` | Approvals Complete | All designated approvers have acted; disbursement released for processing |
| `1172` | Approvals — Payment Suspended | Transaction could not complete due to pending approvals; system will attempt to complete upon receipt of pending approvals |
These codes confirm the email or SMS notification that was sent to a recipient, joint recipient, or approver at each stage of the disbursement lifecycle. They appear in webhook event payloads. Codes marked **Managed Parties** do not appear in Notify — Classic.
| Code | Notification | Delivery |
| ------ | --------------------------------------------------- | --------------------------- |
| `1200` | Payment notification | Email |
| `1201` | Payment notification | SMS |
| `1202` | Payment notification reminder | Email |
| `1203` | Payment notification reminder | SMS |
| `1204` | Notification timeout | Email |
| `1206` | Authentication failure | Email |
| `1208` | RVDM terminal failure | Email |
| `1210` | Account not supported — terminal failure | Email |
| `1212` | OFAC clearing failure | Email |
| `1214` | Account verification terminal failure | Email |
| `1216` | Payment processing terminal failure | Email |
| `1217` | Payment processing terminal failure | SMS — **Managed Parties** |
| `1218` | Transaction receipt — digital transfers | Email |
| `1219` | Transaction receipt — digital transfers | SMS — **Managed Parties** |
| `1222` | Payment return | Email |
| `1224` | Transaction receipt — check by mail | Email |
| `1226` | Transaction terminated | Email |
| `1228` | Transaction cancelled | Email |
| `1232` | Transaction cancelled — beneficiary | Email |
| `1234` | Transaction cancelled — beneficiary invalid address | Email |
| `1236` | Check cancelled — client-internal request | Email |
| `1238` | Check payment stop | Email |
| `1240` | Approval pending notice | Email — **Managed Parties** |
| `1241` | Approver no consent notice | Email — **Managed Parties** |
| `1243` | Payment notice | Email — **Managed Parties** |
| `1244` | Consent approval alert | Email — **Managed Parties** |
| `1245` | Consent approval alert reminder | Email — **Managed Parties** |
| `1246` | Consent approval confirmation | Email — **Managed Parties** |
Code `1242` (Delegated Payment Confirmation) is reserved for role delegation, which is not yet available. It will be documented here when role delegation ships.
These codes are specific to the Ingo Banking Platform API.
| Code | Description |
| ------ | --------------------------------------------------------- |
| `552` | Multiple Banking Platform requests running simultaneously |
| `617` | Duplicate Banking Platform idempotent key |
| `620` | Duplicate Banking Platform request |
| `621` | Banking Platform validation error |
| `793` | Banking Platform transaction limit exceeded |
| `820` | Banking Platform route failure |
| `1300` | Banking entity not found |
| `1301` | Banking ledger not found |
| `1302` | Banking transaction not found |
| `1303` | Banking hold not found |
# Legal
Source: https://developers.ingopayments.com/docs/hub/legal
Terms of service, agreements, and legal documentation governing your integration with Ingo Payments.
Legal contracting is a structured part of the Ingo onboarding process. The framework of your agreements is shaped by your corporate structure, your payment use case, the flow of funds, and the third parties involved. Ingo's legal team is built for this — experienced in payments technology, consultative by approach, and focused on getting you to execution efficiently.
***
## Our Commitment
Ingo brings extensive experience structuring agreements across a wide range of client models and integration complexities. Rather than simply exchanging redlines, Ingo's legal team takes a consultative approach — helping your team understand the rationale behind each provision, how it supports a secure and scalable partnership, and what tradeoffs exist. The goal is to streamline negotiations, reduce delays, and align all stakeholders on a clear path to execution while maintaining strong legal and operational protections for both parties.
***
## What Shapes Your Agreement
Several factors determine the structure and scope of your legal agreements:
**Corporate structure** — Single-entity clients typically require a simpler agreement framework than multi-entity organizations or programs involving third-party program managers, processors, or platforms.
**Flow of funds** — How money moves between end users, the client, and underlying financial institutions directly influences liability allocation, data ownership, and the required agreement types.
**Use case and product mix** — Programs involving payouts, collections, or stored value may introduce licensing requirements, compliance obligations, and jurisdictional considerations that require tailored provisions.
All agreements must clearly define roles and responsibilities, service levels, dispute handling, indemnification, and termination rights. Aligning these elements early ensures the legal framework supports both operational execution and long-term scalability.
***
## Navigating the Process
Ingo's legal team prioritizes high-impact provisions first — liability, flow of funds, pricing, and compliance responsibilities. This approach accelerates agreement on the terms that matter most while keeping the overall process moving.
Legal negotiations require input from compliance, finance, and product teams on both sides to ensure terms reflect operational realities. Establishing clear decision-makers and escalation channels at the start helps resolve impasses efficiently and keeps the integration timeline on track.
Prolonged legal review cycles are one of the most common causes of implementation delays. Early engagement from both legal teams — and responsiveness throughout the process — is the most reliable way to avoid becoming a blocker.
Your Ingo Account Manager is your first point of contact for legal questions and will connect you with the appropriate Ingo legal counsel to begin the contracting process.
# Developer Hub
Source: https://developers.ingopayments.com/docs/hub/overview
APIs, SDKs, and integration guides for every stage of your build — from first call to production launch.
Ingo Payments · Developer Hub
Build the future of intelligent disbursements
APIs, SDKs, and integration guides for every stage of your build — from first call to production launch.
**Ingo Banking Platform is now live.** Routable accounts, card issuance,
KYC/KYB, and ledger management for fintech programs — available to beta
clients today. [See what's new →](/docs/banking/overview)
## Choose your integration path
Every Ingo Payments product is built on the same HMAC-SHA512 authenticated
REST foundation. Choose the product that fits your architecture — or combine
them to build end-to-end disbursement workflows.
**API · Direct integration**
Push payments via card, ACH, check, PayPal, Venmo, and BillPay.
Full verify → process → webhook lifecycle. Best for teams that
want direct API control over every disbursement.
**SDK · Drop-in UI**
PCI-compliant iFrame SDK for recipient account tokenization.
Zero card data on your servers — Ingo returns a
`customer_account_token` for future process calls.
**SaaS · Single recipient**
Managed recipient engagement for disbursements. Ingo handles
authentication, identity verification, OFAC screening, and
risk controls on your behalf.
**SaaS · Orchestrated flow**
Everything in Notify — Classic, plus full party orchestration
across recipients, approvers, and joint recipients with role
delegation and engagement lifecycle management.
**BaaS · Now live**
Routable bank accounts, debit cards, KYC/KYB, and ledger management
for fintech programs. Full Banking-as-a-Service API — live with beta
clients today and scaling rapidly. Contact your integration manager
to get started.
***
What to expect during onboarding.
Client-level risk and product config options.
Terms of service and legal docs.
PCI DSS, OFAC, SOC 2, and regulatory strength.
# Partnership Onboarding
Source: https://developers.ingopayments.com/docs/hub/partnership-onboarding
What to expect from your first conversation with Ingo Payments through to live disbursements — timelines, phases, and key milestones.
Becoming an Ingo Payments partner is a structured, collaborative process designed to move efficiently from initial interest to a live, production-ready disbursement program. This page walks you through what to expect at every stage — who's involved, what happens, and how long it takes.
***
## The partnership journey
Ingo's business development team identifies prospective partners whose use case
aligns with our disbursement capabilities. An introductory meeting is scheduled
to understand your business need and explore how Ingo fits. If the opportunity
is qualified, a Mutual Non-Disclosure Agreement (MNDA) is executed to enable
open technical and commercial discussion. Your Ingo Account Manager then leads
a structured discovery of your disbursement program — payment volumes, recipient
populations, payment rails required, and any industry-specific considerations.
This shapes the scope of the proposed solution.
Your Ingo Integration Manager joins to explore your architecture, integration
approach, and technical requirements. Initial decisions around payment rail
selection, authentication model, webhook architecture, and configuration options
are discussed. A draft solution document is developed alongside preliminary
pricing.
Ingo's Compliance and Risk team conducts a preliminary review of your program
to assess alignment with Ingo's risk standards, payment network requirements,
and regulatory obligations. This is a lightweight initial screen — not the full
compliance review, which occurs later.
Final pricing is confirmed and a formal proposal is prepared and sent for
signature. Once countersigned, the deal moves to implementation. Your signed
proposal and discovery documents are handed off to Ingo's onboarding team,
and a warm introduction to your Integration Manager is made.
A formal kickoff call establishes the implementation timeline, assigns owners
on both sides, and confirms your technical architecture and configuration
selections. Ingo grants access to a secure shared collaboration folder and
begins sandbox environment setup.
The full legal and compliance review runs in parallel with your integration
build. This phase includes execution of all required agreements, third-party
provider contracts, payment network registrations, and Ingo's due diligence
process. Your development team builds against the Ingo sandbox environment
using your credentials, configured webhooks, and custom domain setup.
**Developer resource assignment is a critical factor in achieving the
timeline established at kickoff.** Delays in committing dedicated development
capacity are the most common cause of implementation timeline slippage.
Ingo recommends confirming your assigned developer(s) before the kickoff
call and ensuring they are available to begin work immediately. Your
Integration Manager will flag resource availability as a dependency at
kickoff and throughout this phase.
Your team completes internal testing of your application and processes against
the Ingo sandbox. Ingo provides test plan documentation and guidance. Custom
configuration selections are validated — including risk controls, authentication
modes, and account type support.
Ingo conducts formal sandbox certification testing to validate your integration
against Ingo's requirements. Successful certification is required to advance to
production. Your Ingo Integration Manager reviews results and confirms readiness.
Final risk configuration elections are collected.
Your production environment is configured — credentials, custom domains, webhook
endpoints, and any SFTP setup are established. Your pre-fund bank account is
opened and funded via wire. Invoicing processes, replenishment procedures, and
internal program support structures are confirmed on your side. Your Ingo
Integration Manager then coordinates the production release, validates
end-to-end functionality, and confirms all systems are operating as expected.
Production release testing is completed before your program is formally declared
live.
Following go-live, your program transitions to Ingo's dedicated support team.
Your Account Manager remains your primary relationship contact for program
growth, configuration changes, and escalations.
***
## Timeline
Timeline from proposal signature to live — including network registrations,
compliance approvals, bank approvals, and legal agreement execution.
**4 – 6 weeks**
Typical for single-rail implementations with straightforward compliance
profiles. Examples include push-to-card or ACH disbursement programs
with established program structures.
**8 – 12+ weeks**
Multi-rail programs, novel use cases, programs requiring extensive
payment network registrations, or clients with more involved compliance
and legal review processes.
Timelines begin with scheduling of the Implementation Kickoff call post proposal
signature and depend on the responsiveness of both parties, third-party approvals
outside Ingo's control (payment networks, banking partners), the complexity of
your compliance profile, and the availability of your dedicated development
resources. Your Integration Manager will establish a detailed project timeline
at kickoff.
***
## Who's involved
* **Account Manager** — your primary commercial relationship contact throughout the partnership
* **Integration Manager** — leads your technical implementation from kickoff through go-live
* **Compliance & Risk Officers** — oversee regulatory review, due diligence, and ongoing risk management
* **Legal Counsel** — manages contract execution and agreement review
* **Support Team** — provides ongoing operational support post-launch
* **Program Stakeholder** — executive sponsor accountable for the partnership and program outcomes
* **Project Manager** — coordinates timelines, dependencies, and cross-functional alignment
* **Product Manager** — defines use case requirements and configuration decisions
* **Development Team** — builds and tests the integration; availability from kickoff is critical to timeline
* **Legal Counsel** — reviews and negotiates agreements
* **Compliance & Risk Officers** — supports due diligence and regulatory requirements
***
## What to prepare
The more prepared your team is at kickoff, the faster your implementation moves.
Consider having the following ready before your kickoff call:
**Before your kickoff call, we recommend having:**
* A clear description of your disbursement use case and recipient population
* Estimated monthly payment volume and average transaction size
* Preferred payment rail(s) — card, ACH, check, PayPal, Venmo, or a combination
* Your technical architecture — existing systems, APIs, and integration approach
* Developer(s) identified and available to begin work immediately following kickoff
* Internal contacts confirmed for legal, compliance, and development
* Any known regulatory, network, or banking requirements specific to your industry
Your Ingo Account Manager can help you think through any of these before
the formal kickoff.
***
## What the onboarding process covers
Your Integration Manager will guide you through four structured phases:
**Legal, Compliance & Third-Party Agreements** — contract execution, implementation fee, third-party provider agreements, Ingo due diligence, and payment network registrations are completed before technical work begins.
**Product & Marketing** — your advertising approach, projected payment volumes, and sub-client onboarding procedures (if applicable) are reviewed and documented to ensure your program is designed for scale.
**Sandbox Implementation & Testing** — Ingo configures your sandbox environment with credentials, custom domains, webhook endpoints, and SFTP. You build and test your integration against this environment, complete Ingo's test plan, and receive formal sandbox certification approval before a production promotion decision is made.
**Production Release & Ramp** — Your Integration Manager works with your team to plan and coordinate the production go-live. This includes release sequencing, a phased rollout approach if applicable, initial transaction ramp targets and volume milestones, and monitoring expectations during the ramp period. Projected payment volumes and ramp timelines are documented and agreed upon so both teams have aligned expectations going into launch. Escalation contacts and support handoff are confirmed before your program is declared live.
# Product & Risk Configurations
Source: https://developers.ingopayments.com/docs/hub/product-risk-configurations
Client-level configuration options for identity verification, card and bank account risk controls, authentication, OFAC, and velocity limits.
Ingo Payments offers a range of configurable risk controls that can be tailored to your program's requirements. Your Integration Manager will guide you through selecting the right configuration for your use case during onboarding. This page describes each control, the behaviors it enables, and the risk values available.
***
## Recipient Authentication (RA)
Recipient Authentication is a required feature for programs using Notify — Classic and Notify — Managed Parties. It is used as a fraud prevention mechanism supplementing your KYC process, verifying that the recipient engaging in the disbursement flow is the intended party.
Recipients are challenged against authentication data you provide in the Notify API request. You configure the challenge fields, field order, input format, and the behavior on match and mismatch.
**Risk value definitions:**
| Value | Behavior |
| ----- | ---------------------------------------------------------------------------------------------- |
| Hard | Reject authentication or prompt the recipient to re-enter (subject to configured max attempts) |
| Soft | Record the event and approve the transaction for the next step |
***
## Recipient Verification Data Matching (RVDM)
RVDM is an optional feature for programs using the IngoPay API and Embedded Account Capture. It compares customer-entered account data against recipient information provided in the API request to detect mismatches that may indicate fraud.
You configure your risk tolerance for each field independently, allowing you to set different responses for high-confidence fields (e.g., name) vs. lower-confidence fields (e.g., address).
**Risk value definitions:**
| Value | Behavior |
| ------ | ----------------------------------------------------------------------------------- |
| Hard | Reject verification or prompt the recipient to re-enter (configurable max attempts) |
| Soft | Record the event and approve the transaction for the next step |
| Bypass | Do not perform verification for this field |
**Configurable fields:**
| Field | Risk Values |
| ---------------- | -------------------- |
| First Name | Hard / Soft / Bypass |
| Last Name | Hard / Soft / Bypass |
| Address Line 1 | Hard / Soft / Bypass |
| Address Line 2 | Hard / Soft / Bypass |
| City | Hard / Soft / Bypass |
| State | Hard / Soft / Bypass |
| Zip Code | Hard / Soft / Bypass |
| Maximum Attempts | 1–10 |
***
## Address Verification Service — AVS (Card Only)
AVS is an optional feature for card-based disbursements. It compares the billing address entered by the recipient against the cardholder address on file at the issuing bank. Ingo collects the address from the recipient, submits it to the issuer, and handles the response according to your configured risk profile.
AVS is performed during the verify call, via the IngoPay API or the Embedded Account Capture SDK.
Issuers control their own matching algorithms. Ingo has no visibility into individual issuer matching logic — results may vary. Many issuers use fuzzy matching for near-match scenarios.
**Risk value definitions:**
| Value | Behavior |
| ----- | -------------------------------------------------------------- |
| Hard | Reject the transaction or prompt the recipient to re-enter |
| Soft | Record the event and approve the transaction for the next step |
**Configurable AVS responses:**
| Issuer / Network Response | Risk Values |
| --------------------------------------------------- | ------------ |
| Street address matches; zip does not | Hard or Soft |
| Street address matches; zip incompatible format | Hard or Soft |
| Street and zip incompatible formats | Hard or Soft |
| Zip matches; street address does not | Hard or Soft |
| Zip matches; street incompatible format | Hard or Soft |
| Issuer not an AVS participant or no result returned | Hard or Soft |
| Address information not verified | Hard or Soft |
| Retry — issuer unavailable or timed out | Hard or Soft |
| Maximum attempts | 1–10 |
***
## Card Verification Value — CVV (Card Only)
CVV is an optional feature for card-based disbursements. It verifies that the recipient is in possession of the physical card by requiring entry of the 3-digit security code printed on the card.
When enabled, a full CVV match is required. A mismatch results in a hard failure and the recipient is given a configurable number of re-entry attempts before a terminal event is recorded.
CVV is performed during the verify call, via the IngoPay API or the Embedded Account Capture SDK.
| Setting | Behavior |
| ------- | ------------------------------------------------- |
| ON | Full CVV match required for disbursement approval |
| OFF | CVV verification not performed |
***
## Account Name Inquiry — ANI (Card Only)
ANI is an optional feature for card-based disbursements. It verifies that the cardholder name provided by the recipient matches the name held by the issuing bank, providing an additional fraud check during card tokenization.
ANI results are included in the `network_validation` object within the tokenization success webhook event.
**Risk value definitions:**
| Network Validation Response | Risk Values |
| --------------------------- | ------------ |
| Partial Match | Hard or Soft |
| No Match | Hard or Soft |
| Match Not Performed | Hard or Soft |
| Match Not Supported | Hard or Soft |
**`network_validation` payload example:**
```json theme={null}
{
"network_validation": {
"validation_provider_id": "1",
"name_validation": {
"name_match_status": 1,
"name_match_decision": 3,
"first_name_match_decision": 1,
"last_name_match_decision": 3
}
}
}
```
**Name match status codes:**
| ID | Description |
| --- | ------------------------------------ |
| `1` | Name match was performed |
| `2` | Name match was not performed |
| `3` | Name match not supported by provider |
| `4` | Client not configured for name match |
**Name match decision codes:**
| ID | Description |
| --- | ------------- |
| `1` | Match |
| `2` | Partial match |
| `3` | No match |
***
## Account Number Validation — ANV (Bank Account Only)
ANV is an optional feature for bank account (ACH) disbursements. It verifies the active status of the bank account number provided by the recipient against the issuing bank's records.
ANV is performed during the verify call via the IngoPay API or the Embedded Account Capture SDK.
**Risk value definitions:**
| Value | Behavior |
| ----- | --------------------------------------------------------------------- |
| Hard | Reject the transaction or prompt re-entry (configurable max attempts) |
| Soft | Record the event and approve the transaction for the next step |
**Configurable ANV responses:**
| Network Validation Response | Risk Values |
| ---------------------------------------- | ------------- |
| No data or non-participating issuer | Hard or Soft |
| Positive data — non-participating issuer | Hard or Soft |
| Invalid account number | Hard (always) |
| Invalid routing number | Hard (always) |
***
## Name on Account Validation — NAV (Bank Account Only)
NAV is an optional feature for bank account (ACH) disbursements. It verifies that the recipient's name — and optionally their address — matches the account holder information held by the issuing bank.
**Risk value definitions:**
| Value | Behavior |
| ----- | --------------------------------------------------------------------- |
| Hard | Reject the transaction or prompt re-entry (configurable max attempts) |
| Soft | Record the event and approve the transaction for the next step |
**Configurable NAV responses:**
| Network Validation Response | Risk Values |
| ------------------------------------------ | ------------ |
| No data from issuer | Hard or Soft |
| Customer name or name and address no match | Hard or Soft |
| Customer or business name no match | Hard or Soft |
| Address no match | Hard or Soft |
***
## PayPal Risk Verification Service
PayPal account verification, upon recipient consent, matches the recipient's PayPal account data against client-provided recipient information for risk management purposes. Acceptance or rejection is based on your configurable matching criteria. If rejected, the recipient cannot reattempt verification with an alternate PayPal account.
**Configurable verification fields:**
| Field | Risk Values |
| ---------------------- | ------------ |
| First Name | Hard or Soft |
| Last Name | Hard or Soft |
| Address | Hard or Soft |
| City | Hard or Soft |
| State | Hard or Soft |
| Zip Code | Hard or Soft |
| Primary email match | Hard or Soft |
| Associated email match | Hard or Soft |
| Value | Behavior |
| ----- | ----------------------------------------------------------------------- |
| Soft | Record event and approve transaction for next steps |
| Hard | Record event and prompt recipient to select an alternate payment method |
***
## One-Time Authorization Code — OTAC
OTAC may be used as a primary, secondary, or dual authentication mechanism for Notify — Managed Parties programs. It delivers a time-limited code to the recipient via SMS or email, confirming they have access to the registered contact method.
**Configurable OTAC options:**
| Option | Description |
| ----------------------------- | --------------------------------------------------------- |
| Code length | Number of digits in the generated code |
| Code expiration | Minutes before the code expires |
| Allow same delivery method | Whether OTAC can be re-sent via the same delivery channel |
| Maximum code requests | Total OTACs that can be generated per session |
| Maximum unsuccessful attempts | Failed entry attempts before the session is terminated |
***
## OFAC Screening
OFAC screening may be required depending on your program's use case and integration. Ingo can perform OFAC checks for each recipient presented in the payment processing gateway. When configured, an OFAC check runs during the process call for any recipient whose last OFAC validation exceeds 30 days.
A suspended transaction is placed on hold pending review by Ingo's Risk Services team. Results are delivered asynchronously via webhook. See [Webhooks](/docs/ingopay/webhooks/overview) for the applicable event codes.
***
## Transactional Velocity Limits
Velocity limits apply to all disbursement methods at the individual Customer Account Number level. Your Integration Manager will work with you to configure program-specific limits within the boundaries set by card networks, Ingo, and your sponsor bank.
All time periods are rolling except the daily limit, which resets at midnight Mountain Time.
| Velocity Limit |
| ---------------------------------------------- |
| Maximum single transaction amount |
| Maximum daily total amount |
| Maximum rolling 7-day total amount |
| Maximum rolling 15-day total amount |
| Maximum rolling 30-day total amount |
| Maximum transactions per rolling 30-day period |
Transactions that breach any configured limit are declined. The applicable error code is returned in the synchronous process response.
# Quick Start
Source: https://developers.ingopayments.com/docs/hub/quick-start
Make your first successful Ingo Payments API call — credentials, authentication, and your first verify and process request.
## Start building in 4 steps
Contact your Ingo integration manager to receive your HMAC username,
HMAC secret, and participant identifier. All Ingo products use
HMAC-SHA512 request signing — the same authentication standard
across every API. See [Authentication](/docs/hub/authentication)
for signature construction details.
Call `POST /gateway/verify` (IngoPay API) or launch the iFrame SDK
(Embedded Account Capture) to validate and tokenize the recipient's
payment account. Store the returned `customer_account_token` — you'll
use it on every future process request for that account.
Call `POST /gateway/process` with the `customer_account_token` and
your disbursement amount. Ingo routes the payment across the
appropriate rail — card, ACH, check, PayPal, or Venmo — based on
the `account_type` you tokenized.
Subscribe your endpoint to receive real-time event callbacks for
payment status, OFAC screening updates, tokenization results, and
more. Configure retry logic and authentication in your Ingo
integration settings. See [Webhooks](/docs/ingopay/webhooks/overview)
for the full event reference.
***
## Choose your starting point
Not sure which product to start with? Use this guide:
Start with **IngoPay API** — call verify, then process. Full
control over every disbursement request.
Start with **Embedded Account Capture** — drop in the iFrame SDK
and let Ingo handle PCI-compliant account tokenization.
Start with **Notify — Classic** — stage a disbursement and let
Ingo handle authentication, verification, and OFAC screening.
Start with **Notify — Managed Parties** — full party orchestration
with role delegation and engagement lifecycle management.
***
## What you'll need
Before you begin, contact your Ingo integration manager to receive:
* **HMAC username** — identifies your integration in the `Authorization` header
* **HMAC secret** — used locally to sign requests, never transmitted
* **Participant identifier** — identifies your account within API requests
* **Sandbox credentials** — for testing before go-live
All credentials are provisioned at onboarding. See
[Authentication](/docs/hub/authentication) for the complete
signature construction guide.
# Reporting
Source: https://developers.ingopayments.com/docs/hub/reporting
Daily transaction reporting, file delivery, reconciliation cadence, and SFTP setup for Ingo Payments clients.
Ingo delivers daily transaction reports 365 days a year covering all prior-day activity — successful disbursements, returns, refunds, and adjustments — aligned with sponsor bank settlement timelines. Reports are distributed via secure SFTP in `.csv` format and are designed to integrate directly into your existing reconciliation and financial workflows.
***
## Daily Reporting
Reports are generated on a 24-hour cycle and cover the full prior day's activity. Delivery is via secure SFTP. Ingo can push files directly to your host environment or provide pull-based access — both are supported. Authentication supports either username/password or SSH key configurations. File encryption is available but not required, as reports do not contain PII or PCI-sensitive data.
### File naming conventions
Each daily report file follows a standard naming pattern that identifies the client, direction (push or pull), and timestamp:
```
Dly_Sttlmnt_Rpt_{ClientName-Push}_YYMMDDHHMMSS.csv
Dly_Sttlmnt_Rpt_{ClientName-Pull}_YYMMDDHHMMSS.csv
```
The push file covers outbound transactions; the pull file covers inbound transactions. Your `Participant-ID` value is a 5 Integer value assigned by Ingo at onboarding.
***
## Reconciliation
Running both daily and monthly reconciliation gives you the most complete picture of your disbursement activity. Daily reconciliation catches errors, duplicates, and unauthorized payments in near real-time — before discrepancies compound. Monthly reconciliation validates that all transactions are fully recorded, correctly classified, and aligned with your general ledger. Together, they maintain cash visibility, support financial forecasting, and produce the audit-ready documentation needed for financial close.
***
## Transaction Types
Every transaction in the daily report carries a type code that identifies its nature. Seven transaction types may appear across your push and pull activity:
| Type Code | Name | Description |
| --------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `1` | Credit Origination | An original push transaction that credits funds to a consumer's account. |
| `5` | Debit Origination | An original pull transaction that debits funds from a consumer's account. |
| `10` | Return — Push | The original push transaction was not accepted by the issuing bank and has been returned to Ingo. Most common on push-to-credit-card transactions. Also triggered by consumer or issuer-initiated disputes and chargebacks. Returns typically occur days after the original disbursement. |
| `14` | Refund | The original push or pull transaction was accepted by Ingo but declined by the issuing bank or payment network — typically because the consumer's account is not in good standing. Refunds are generally created in real time. |
| `19` | Return — Pull | The original pull transaction was not accepted by the issuing bank and has been returned to Ingo. Most common on pull-from-account transactions. Also triggered by consumer or issuer-initiated disputes and chargebacks. Returns typically occur days after the original request. |
| `24` | Adjustment Credit | A settlement credit adjustment to an original push or pull transaction that was accepted by both Ingo and the issuer. Issued in response to a transaction-related event after the transaction has settled. |
| `25` | Adjustment Debit | A settlement debit adjustment to an original push or pull transaction that was accepted by both Ingo and the issuer. Issued in response to a transaction-related event after the transaction has settled. The reason for the adjustment is indicated by the reported reason code. |
***
## Account Types
The `account_type` field in each report record uses the following codes:
| Code | Payment Type |
| ---- | ------------------------ |
| `AC` | Standard ACH |
| `BP` | BillPay |
| `CA` | Card |
| `CK` | Check by Mail |
| `PD` | PayPal (Verified) |
| `PE` | PayPal (Unverified) |
| `RT` | Real-Time Payments (RTP) |
| `SD` | Same-Day ACH |
| `VE` | Venmo |
***
## SFTP Setup
### IP addresses to whitelist
Your firewall must allow inbound connections from all seven Ingo Payments IP addresses:
```
108.166.110.227
162.209.88.50
166.78.4.133
162.209.88.71
162.209.88.50
54.242.10.220
52.32.40.162
```
### Information required from your team
Before production credentials are issued, provide the following to your Ingo integration manager:
| Contact Details | SFTP Configuration |
| ------------------------------- | ------------------ |
| Company name | Host address |
| Name and title | IP address |
| Email address | Port |
| Phone number | Username |
| Date connectivity is needed | Password |
| File path / folder for delivery | — |
# Retry Logic
Source: https://developers.ingopayments.com/docs/hub/retry-logic
How to identify retry-eligible status codes, design a retry strategy aligned to your customer experience, and avoid retrying codes that will not self-resolve.
Implementing retry logic is strongly recommended for all Ingo Payments integrations. A subset of status codes represent transient infrastructure failures — timeouts, routing issues, and temporary system errors — that are recoverable with a subsequent attempt. Failing to retry these codes results in unnecessary transaction failures that require manual intervention and degrade the customer experience.
The retry codes and strategy below apply to IngoPay API integrations. Clients using Notify products should work with their Integration Manager to confirm how retry handling applies to their specific flow.
***
## Stand-In Responses and No-Response Handling
For push and pull transactions where Ingo makes a real-time downstream call to a payment network, Ingo holds awaiting a response from the network before issuing a stand-in. The hold duration is generally up to **60 seconds**, though the specific timeout varies depending on the payment network your program is configured to use. To prevent your application from waiting indefinitely, Ingo issues a **stand-in response** when the network has not responded within your program's configured threshold. Stand-in settings are configured once at the program level during onboarding with your Integration Manager. Push and pull thresholds are configured separately.
This behavior is most prevalent for real-time transactions — card push disbursements and RTP — where a synchronous downstream network call is required. ACH, check, and similar rails process asynchronously and are less likely to encounter stand-in conditions.
### Push — Stand-In Success (102)
If the downstream network does not respond within your configured push stand-in threshold, Ingo returns code `102` (Success — Pending Issuer Response). Treat `102` as a success equivalent to `100`. The transaction is considered complete and no additional webhook follows. The `102` is the final, definitive response for that request.
Ingo recommends a push stand-in threshold of **15 seconds or higher**. The longer your program can hold, the more actual network outcomes your integration receives directly rather than stand-in responses. Work with your Integration Manager to align the threshold to your customer experience model.
### Pull — Stand-In Decline (790)
If the downstream network does not respond within your configured pull stand-in threshold, Ingo returns code `790` (Declined — Stand In) and reverses the transaction. The reversal typically appears as a refund in reporting.
A `790` stand-in decline can be safely retried using the same `participant_unique_id1`. Because the original transaction was declined and reversed, the retry is treated as a fresh attempt. A successful retry returns `100`.
Ingo recommends a pull stand-in threshold of **30 seconds or higher** for the same reasons described above.
### If no response is received after the stand-in window
Ingo will always issue a stand-in response before your configured threshold elapses. Clients should wait for that response before initiating any retry — do not retry based on an immediate connection error or timeout on your side.
If your stand-in window has elapsed and no response has been received, retry using the same `participant_unique_id1`. Possible outcomes on the retry:
| Response | Meaning |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| `100` | Ingo did not receive the original request. The retry was processed as a new transaction and succeeded. |
| `101` | The original request was received and processed successfully. No new transaction was created. |
| `102` | The original request was received and a stand-in success was issued. Treat as a confirmed success. |
| `103` | The original request was received and queued for async processing. |
| `104` | The original request is still processing. See [Code 104 handling](#code-104--in-progress-transactions) below. |
Idempotency codes `101`, `102`, and `103` only emit when the original request was previously marked successful. Receiving any of these on a retry confirms the original transaction was processed — no further action is needed.
***
## Code 104 — In-Progress Transactions
Code `104` requires special handling. It is not a failure — it means a prior request with the same `participant_unique_id1` is still processing and a new posting attempt was not initiated.
When you receive a `104`:
* **Do not generate a new `participant_unique_id1`.** The original transaction is active. Submitting a new ID will create a second transaction attempt, which is likely not your intent.
* **Retry with the same `participant_unique_id1`** after a brief wait. The transaction will either complete and return a success code, or fail and return a terminal code on a subsequent attempt.
* If you are subscribed to webhooks, the outcome will also be delivered asynchronously when processing concludes.
***
## Retry-Eligible Codes
The following codes represent transient conditions. A retry with the same request is appropriate for all of them.
| Code | Description | Applicable Call |
| ----- | ------------------------------------------------------------------ | ----------------------- |
| `104` | In progress — idempotent response (prior request still processing) | Process |
| `500` | General error | Search, Verify, Process |
| `501` | Response from endpoint was invalid | Verify, Process |
| `502` | Process timeout | Verify, Process |
| `511` | OFAC timeout | Process |
| `514` | OFAC unknown error | Process |
| `523` | AVS service connection error | Process |
| `524` | AVS response parse failure | Process |
| `525` | AVS response bad structure | Process |
| `706` | Transaction routing failure | Process |
| `707` | Transaction routing failure | Process |
| `709` | Transaction routing failure | Process |
| `717` | Transaction routing failure | Process |
| `718` | Transaction routing failure | Process |
| `750` | Response from endpoint not recognized | Verify, Process |
| `751` | Response from endpoint not defined | Process |
| `900` | Account identity lookup error | Verify, Process |
| `901` | Account identity lookup error | Verify, Process |
| `990` | General error | Verify, Process |
| `999` | General error | Verify, Process |
Codes `511` and `514` indicate that the OFAC screening service timed out or returned an unexpected error — not that the recipient was matched against the OFAC list. These are transient and retry-eligible. A confirmed OFAC match returns code `130` and is **never** retry-eligible.
Codes `523`, `524`, and `525` indicate infrastructure-level failures communicating with the AVS service — a connection error, an unparseable response, or a response missing expected fields. These are distinct from AVS verification declines (`510`, `513`, `753–764`) which are terminal for the current attempt. See [Code Reference](/docs/hub/errors) for details.
If all retry attempts are exhausted on any of these codes, contact Ingo Payments support and include the `participant_unique_id1` and timestamp from the failed request.
***
## Retry Strategy
The right retry interval depends on your customer experience model — specifically, whether your end customer is actively waiting for a response or has already been acknowledged and released from the interaction.
### Customer is waiting on screen
If your program holds the customer on a confirmation or loading screen while awaiting a result, retries need to complete quickly. The customer has no feedback and every second of delay increases drop-off risk.
**Recommendation:** 3 retry attempts within a 1 to 2 minute window. Space attempts progressively — for example, retry at 15 seconds, 30 seconds, and 60 seconds. If all three attempts fail, surface a meaningful response to the customer rather than leaving them on a loading screen.
This model applies to programs where a customer initiates a payment in real time and stays in the flow until receiving a confirmation.
### Customer has been acknowledged and released
If your program has already confirmed receipt of the request to the customer — for example, displaying a message such as "We have received your request and will process it shortly" — there is no active wait and retry intervals can be much wider.
**Recommendation:** 3 retry attempts with intervals up to one hour between each attempt. This accommodates programs that queue requests internally before submitting to Ingo, batch and submit payment requests at set intervals, or stage payments for a scheduled processing run.
In these flows, the customer's expectation has already been set and a delay in processing does not create an immediate experience gap.
### High-volume programs
If your program submits high transaction volumes and experiences a burst of retry-eligible errors simultaneously — for example, during an OFAC service timeout — avoid retrying all requests at the exact same interval. Staggering retry timing across your queue reduces the risk of compounding load on the same endpoint. A small random offset added to each retry interval (commonly called jitter) is an effective way to achieve this automatically.
***
## What Not to Retry
Not all failures are transient. Retrying the following code families will not produce a different outcome and may trigger rate limiting or flag your integration for unusual behavior.
**Request and auth errors (4xx)** indicate the request was rejected due to bad input, invalid credentials, or a suspended account. Correct the request before retrying.
**Validation and velocity errors (600-616, 711-725)** indicate a field failed validation or a program limit was reached. Correct the field value or transaction amount, or verify the transaction is within your configured program limits.
**OFAC match (130)** indicates the recipient was matched against the OFAC sanctions list. This is a compliance-level outcome and is terminal. Do not retry.
**Card issuer declines (851-867)** indicate the card issuer rejected the transaction. These cannot be resolved by retrying — the recipient needs to contact their card issuer.
**Hard verification declines (753-815)** indicate card or account data failed a configured verification check. Correct or re-verify the account data before attempting again.
**Notify authentication and verification failures (1100-1170)** indicate the recipient did not pass authentication or identity verification. These are event-driven outcomes, not transient errors.
If you are uncertain whether a specific code warrants a retry, refer to the recommended action column in the [Code Reference](/docs/hub/errors) or contact your Integration Manager.
# Testing & Certification
Source: https://developers.ingopayments.com/docs/hub/testing
Build confidence in your implementation before go-live with Ingo's comprehensive sandbox environment and structured certification framework.
## Why Payment Testing Demands More
Releasing a software update and releasing a payment integration are fundamentally different events. Most software failures are recoverable — you can roll back a deployment, issue a patch, ask users to retry. A failed or misdirected payment is not so forgiving. Funds held in limbo, a recipient who didn't receive their disbursement, a compliance event that wasn't handled — these carry real consequences for real people.
That reality shapes how Ingo structures the testing process. The goal is not to verify that your integration works in ideal conditions. It is to give you comprehensive evidence that it can handle the full spectrum of what money movement looks like in production — the happy paths, the edge cases, and the failure modes you hope never to encounter but must be prepared for.
***
## The Sandbox Environment
Ingo's sandbox is a full-fidelity pre-production environment. It is not a mock — it runs the same payment routing logic, risk and compliance services, OFAC screening, account verification protocols, and webhook delivery infrastructure as production.
Testing in the sandbox means your integration encounters the same decision points it will face on day one of go-live:
* Real payment network routing logic with configurable outcomes
* OFAC screening with test scenarios for suspension, clearance, and failure
* AVS and CVV risk management with deterministic test accounts
* ACH account verification through GIACT
* Recipient authentication with configurable pass/fail thresholds
* Webhook delivery with retry behavior identical to production
Sandbox credentials and any client-specific velocity limits are provisioned during your onboarding engagement with your Ingo integration manager.
***
## A Three-Tier Certification Framework
Testing is structured across three tiers, each designed to progressively build confidence before you advance to the next.
Your team works independently in the sandbox to validate core flows, happy paths, and common error scenarios. No Ingo coordination required. Complete these at your own pace.
Certain scenarios — OFAC screening events, AVS/CVV risk outcomes, GIACT verification responses — require Ingo to enable a specific configuration flag before testing can proceed. Schedule these with your integration manager.
Complex orchestration scenarios benefit from a live session with your Ingo integration team. These include multi-party approval flows, returned payment handling, and scenarios that require coordinated timing across systems.
Reaching certification readiness typically means completing all self-service and controlled scenarios, and attending at least one guided session for the complexity tier relevant to your product configuration.
***
## What Certification Coverage Looks Like
A complete certification pass addresses five dimensions of confidence:
**Core payment flows** — every account type you intend to offer to recipients has been successfully tested end-to-end, from notification or request through to disbursement completion.
**Failure handling** — your system correctly receives, processes, and responds to error conditions at every stage of the flow. A recipient failing authentication, an account failing verification, a payment being returned by the issuer — your system handles each gracefully and your recipients receive the right outcome.
**Compliance scenarios** — OFAC screening events have been triggered and your system correctly handles suspension, clearance, and failure states. For clients using risk management services, AVS, CVV, and account verification outcomes have been exercised.
**Webhook processing** — webhook events are being received, acknowledged with a 2xx response, and acted upon correctly by your downstream systems. Every event type relevant to your product configuration has fired at least once.
**Velocity and limits** — your sandbox has been stress-tested against the velocity limits configured for your program, confirming your implementation handles limit-related responses without unintended behavior.
***
## Certifying Your Implementation
When your team has completed the applicable test scenarios and your integration manager has reviewed the results, Ingo issues a certification confirmation that your implementation is ready for production.
Certification is not a checkbox — it is a structured attestation that your integration has been validated against the behavioral complexity inherent to live payment processing. Partners who complete the full certification framework go live with a significantly higher degree of confidence and historically experience fewer integration-related incidents in production.
***
## Product Testing Guides
Your integration team can find detailed scenario-based testing guides for each Ingo product:
Direct API integration testing for Verify, Process, Debit, and Risk endpoints.
iFrame plugin session, account tokenization, and verification flow testing.
Single-party staged disbursement testing across all payment types.
Multi-party orchestrated disbursement testing including approval flows.
# Webhooks
Source: https://developers.ingopayments.com/docs/hub/webhooks
Real-time event delivery across all Ingo products. Configure your endpoint, verify signatures, and handle the full transaction lifecycle as it happens.
Ingo delivers real-time updates to your configured webhook endpoint as events occur — recipient engagement, identity screening, payment outcomes, and session activity. The connection is one-way: Ingo posts to you. Your endpoint acknowledges receipt with a 2xx response, and the event payload is the authoritative record for everything that follows.
Every Ingo product fires webhooks. Event types, payload schemas, and correlation fields differ per product — the setup and verification requirements below apply to all of them.
***
## Endpoint Requirements
Register a static HTTPS endpoint with your Ingo integration manager before onboarding. Ingo posts webhook payloads as JSON to that URL on every qualifying event.
| Requirement | Detail |
| ------------ | ----------------------------------------------------------------- |
| Protocol | HTTPS only — HTTP endpoints are not accepted |
| TLS version | TLS 1.2 minimum; TLS 1.3 recommended |
| Response | Return any `2xx` status within 10 seconds |
| Content-Type | Ingo posts `application/json` |
| URL | Must be static — dynamic or session-scoped URLs are not supported |
If your endpoint does not return a `2xx` response within the timeout window, Ingo will retry delivery. Design your handler to be idempotent — the same event may arrive more than once.
***
## TLS Requirements
Your endpoint must support at least one cipher suite from the lists below.
**TLS 1.3**
| Cipher Suite | Key Exchange | Strength |
| --------------------------------------- | ------------ | -------- |
| `TLS_AES_256_GCM_SHA384` (0x1302) | ECDH x25519 | 256-bit |
| `TLS_CHACHA20_POLY1305_SHA256` (0x1303) | ECDH x25519 | 256-bit |
| `TLS_AES_128_GCM_SHA256` (0x1301) | ECDH x25519 | 128-bit |
**TLS 1.2**
| Cipher Suite | Key Exchange | Strength |
| ------------------------------------------------------ | ------------ | -------- |
| `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` (0xc030) | ECDH x25519 | 256-bit |
| `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` (0xcca8) | ECDH x25519 | 256-bit |
| `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` (0xc02f) | ECDH x25519 | 128-bit |
***
## IP Allowlist
Add the following Ingo IP addresses to your allowlist so webhook traffic can reach your endpoint.
| IP Address |
| ---------------- |
| `18.189.65.27` |
| `23.253.209.42` |
| `23.253.213.126` |
| `23.253.22.48` |
| `3.130.108.242` |
| `3.134.254.69` |
| `3.142.181.231` |
| `104.130.74.57` |
| IP Address |
| -------------- |
| `64.88.183.84` |
| `50.56.42.59` |
| `50.56.46.146` |
| `50.57.62.142` |
***
## Handling Events
**Acknowledge first, process second.** Return a `2xx` response immediately, then process the payload asynchronously. Handlers that hold the connection open risk timeout retries and duplicate delivery.
**Design for idempotency.** Ingo retries unacknowledged deliveries. Use the `metadata.id` in the payload to detect and discard duplicates before they affect your system state.
**The API response is the source of truth.** Webhooks are an optional subscription layer for real-time status updates — they do not supersede the synchronous response. All transaction statuses, regardless of payment type, are always reflected in your daily SFTP reporting.
***
## Testing During Development
Webhook endpoints are registered by your Ingo integration manager — there is no self-service portal to update the URL your program is configured to call. Before beginning sandbox development, confirm your endpoint URL with your integration manager so it can be registered as part of your program setup.
If you need to receive webhooks on a local development machine, use a tunnel tool that provides a **persistent, stable URL** — a fixed subdomain or custom domain that does not change between sessions. Register that stable URL with your integration manager once. Ephemeral tunnels that generate a new URL on every restart require a configuration change with your integration manager each time, which is not practical for active development.
Contact your Ingo integration manager to update your registered webhook URL. Plan for this lead time when coordinating environment changes or moving from sandbox to production.
***
## Webhook References
Event types, payload schemas, retry behavior, and signature details are documented per product.
Transaction outcomes for verify, process, and debit calls across all payment types.
Recipient engagement events from notification sent through funded.
Full party lifecycle events including approvals, role delegation, and multi-party flows.
Session events for the hosted iFrame enrollment and payment selection experience.
# Embedded Account Capture
Source: https://developers.ingopayments.com/docs/iframe/overview
PCI-compliant drop-in iFrame SDK for recipient account tokenization. Zero card data on your servers — Ingo returns a customer_account_token for use in any IngoPay process call.
Ingo Payments · Embedded Account Capture
Capture accounts. Zero PCI scope.
Drop-in iFrame SDK. Card data never touches your servers. Ingo returns a reusable token.
Embedded Account Capture is a PCI-compliant drop-in iFrame SDK that handles recipient account tokenization inside a secure hosted session. Your server makes one API call to create a session and receives an `authorized_url`. Your client application mounts the iFrame SDK using that URL, and the recipient enters their account details directly into Ingo's hosted environment — card data, bank account numbers, and payment credentials never pass through your servers. When the recipient completes the flow, Ingo fires a `TOKEN_SUCCESS` event containing a `customer_account_token`. That token is then used with any IngoPay verify or process call to initiate a disbursement or debit.
***
## How It Works
Your server calls the Session Management API with the recipient's information.
Ingo establishes a secure, point-in-time session and returns an
authorized\_url valid for 30 seconds. This server-side call is the
only step that requires HMAC-SHA512 authentication.
Include the Ingo SDK script in your page, call IngoInstantPayments.create()
to attach it to a DOM element, then call mount(authorizedUrl, fundingDestination)
to launch the iFrame. The SDK handles the full recipient-facing UI — account entry,
verification, and confirmation — inside the hosted session.
The recipient enters their account details inside Ingo's hosted iFrame. Ingo runs
your configured identity and account verification checks, and on success fires a
TOKEN\_SUCCESS event containing the customer\_account\_token.
No payment credentials are exposed to your application at any point.
The customer\_account\_token returned by the SDK passes directly into
any IngoPay process or debit call — no additional verify step required. The token
never expires and can be reused for future transactions without re-running the
iFrame flow. If your product mix includes the Banking Platform, include the ledger
routing object in the IngoPay call to direct the transaction to the correct entity's
ledger; otherwise no additional fields are needed beyond the token.
***
## Using Your Token with IngoPay
The `customer_account_token` from Embedded Account Capture is interchangeable with any token produced by the IngoPay verify endpoint. Use it directly in IngoPay process calls to push funds, or in IngoPay debit calls to pull funds — across every payment type the iFrame supports.
**Supported payment types:**
| Payment Type | Push | Pull |
| ------------------ | ------------------------ | ---- |
| Debit Card | ✓ | ✓ |
| Credit Card | ✓ | — |
| Bank Account (ACH) | ✓ | ✓ |
| BillPay | ✓ | — |
| PayPal | ✓ | — |
| Venmo | Coming Soon | — |
Use your token to disburse to card, ACH, PayPal, BillPay, and more via the
IngoPay process endpoint.
Use your token to debit a card or bank account via the IngoPay debit
process endpoint.
# Quick Start
Source: https://developers.ingopayments.com/docs/iframe/quick-start
Create a session, mount the iFrame SDK, and receive a customer_account_token.
This guide walks through the complete Embedded Account Capture flow end to end: creating a session server-side, mounting the iFrame SDK in your browser application, and handling the `TOKEN_SUCCESS` event to capture the `customer_account_token`.
You'll need your **username**, **secret**, and **participant\_id** to follow this guide. These are provisioned by your Ingo integration manager at onboarding. See [Authentication](/docs/iframe/authentication) for the signing guide.
The Embedded Account Capture iFrame enforces application-level domain whitelisting. **It will not load under `localhost` or any domain not registered to your program.** Before testing in a browser, confirm your development domain with your Ingo integration manager so it can be added to your program's allowlist. Plan for this before beginning front-end integration work.
***
## Environments
| Environment | Base URL (Session API) |
| ----------- | ----------------------------------------------- |
| Sandbox | `https://iip-session-management-uat.ingo.money` |
| Production | `https://iip-session-management.ingo.money` |
***
Your server calls the Session Management API with the recipient's details. This is
the only step that requires HMAC-SHA512 signing. The response returns an
`authorized_url` that your client uses to mount the SDK.
```http theme={null}
POST /api/v1/sessions/point-in-time/plugin HTTP/1.1
Host: iip-session-management-uat.ingo.money
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="..."
X-Date: Fri, 17 Jan 2020 19:59:29 GMT
Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08=
Content-Length: 285
Content-Type: application/json
{
"participant_unique_id1": "70646041-01ea-4cd6-b657-18ff88e465c7",
"recipient_information": {
"first_name": "Jane",
"last_name": "Doe",
"address_line1": "123 Main St",
"city": "Anytown",
"state": "GA",
"zip_code": "30301",
"email_address": "jane.doe@example.com"
}
}
```
Successful response:
```json theme={null}
{
"status": 100,
"client_message": "Success",
"data": {
"session_identifier": "7830227a-ba47-4d28-9416-cad41a446db7",
"authorized_url": "https://iip-webplugin-uat.ingo.money/session/7830227a-...",
"authorized_url_expiration_utc": "2024-01-17T20:14:19Z",
"participant_unique_id1": "70646041-01ea-4cd6-b657-18ff88e465c7"
}
}
```
The `authorized_url` is valid for **30 seconds**. Pass it to your client immediately — do not store it. If it expires before mounting, use idempotency to refresh it without creating a new session. See [Session Management](/docs/iframe/session/session-management) for details.
Add the Ingo Instant Payments SDK script to your page:
```html theme={null}
```
Add a container element in your HTML where the iFrame will be mounted:
```html theme={null}
```
Create an SDK instance attached to your container element, then mount it using the
`authorized_url` from step 1 and the desired funding destination:
```js theme={null}
// Create SDK instance
var webPlugin = IngoInstantPayments.create(
document.getElementById("ingo-container"),
{
autoHeight: true,
scrolling: false
}
);
// Mount with the authorized URL and funding destination
webPlugin.mount(
authorizedUrl,
IngoInstantPayments.FUNDING_DESTINATIONS.DEBIT
);
```
Available funding destinations:
| Constant | Payment Type |
| ------------------------------ | ------------------ |
| `FUNDING_DESTINATIONS.DEBIT` | Debit card |
| `FUNDING_DESTINATIONS.CREDIT` | Credit card |
| `FUNDING_DESTINATIONS.ACH` | Bank account (ACH) |
| `FUNDING_DESTINATIONS.BILLPAY` | BillPay |
| `FUNDING_DESTINATIONS.PAYPAL` | PayPal |
Register an event listener for `TOKEN_SUCCESS` before or immediately after mounting.
This event fires when the recipient has successfully entered and confirmed their
account details — it contains the `customer_account_token` you'll use for all
future IngoPay calls.
```js theme={null}
webPlugin.addEventListener(
IngoInstantPayments.EVENTS.TOKEN_SUCCESS,
function(data) {
var token = data.customer_account_token;
// Send the token to your server, then pass it into
// an IngoPay process call to push funds, or an IngoPay
// debit call to pull funds.
}
);
```
The full event payload:
```json theme={null}
{
"session_identifier": "7830227a-ba47-4d28-9416-cad41a446db7",
"tracer_token": "12345_07834f31-9ff3-48ff-a7e7-072242331688",
"customer_account_token": "0bef3f2d-3e17-4320-a865-39ffb6b96c2e",
"event_name": "iip.webplugin.token_success",
"funding_destination": "debit"
}
```
Also register listeners for `TERMINAL_FAILURE` and `MAX_VERIFICATION_ATTEMPTS_EXCEEDED` to handle cases where the recipient cannot be verified. See [SDK Events](/docs/iframe/session/events) for the full event reference.
Once you have the token, pass it into any IngoPay process call to push funds or any IngoPay debit call to pull funds. If your product mix includes the Banking Platform, include the ledger routing object in the IngoPay call to direct the transaction to the correct entity's ledger; otherwise no additional fields are required. See [Push Funds to an Account](/docs/ingopay/overview#push-funds-to-an-account) and [Pull Funds from an Account](/docs/ingopay/overview#pull-funds-from-an-account) for the complete payment type reference.
***
## What's next
Idempotency, locale configuration, and session lifecycle.
Full SDK method reference — create, mount, and addEventListener.
All event types, payloads, and error codes.
HMAC-SHA512 signing for the Session Create API.
# Create Session
Source: https://developers.ingopayments.com/docs/iframe/session/create
specs/iframe-session-create.yaml POST /api/v1/sessions/point-in-time/plugin
Initialize a point-in-time iFrame session. Returns an authorized_url for mounting the SDK.
# SDK Events
Source: https://developers.ingopayments.com/docs/iframe/session/events
All iFrame SDK event types, payloads, and error codes for the Ingo Instant Payments plugin.
Register event listeners using `webPlugin.addEventListener()` to track the recipient's progress through the iFrame and respond to outcomes. Every event payload includes `session_identifier`, `tracer_token`, and `event_name`. Additional fields are event-specific and documented below.
```js theme={null}
webPlugin.addEventListener(IngoInstantPayments.EVENTS.TOKEN_SUCCESS, function(data) {
// handle event
});
```
***
## Base Events
These events represent the primary outcomes of the account capture flow. At minimum, your integration should handle `TOKEN_SUCCESS`, `TERMINAL_FAILURE`, and `MAX_VERIFICATION_ATTEMPTS_EXCEEDED`.
### `TOKEN_SUCCESS`
Fired when the recipient has successfully tokenized an account. This is the terminal success event — no further interaction is needed for this session.
**Additional payload fields:**
| Field | Description |
| ------------------------ | --------------------------------------------------------------------- |
| `customer_account_token` | The token to use with IngoPay process calls for future disbursements. |
| `funding_destination` | The funding destination that was tokenized. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_07834f31-9ff3-48ff-a7e7-072242331688",
"customer_account_token": "0bef3f2d-3e17-4320-a865-39ffb6b96c2e",
"event_name": "iip.webplugin.token_success",
"funding_destination": "debit"
}
```
***
### `FUNDING_CANCELED`
Fired when the recipient cancels on the confirmation page or elects to choose a different funding option.
**Additional payload fields:**
| Field | Description |
| --------------------- | ------------------------------------------------- |
| `funding_destination` | The funding destination that was being tokenized. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_db4781bc-aff5-430b-9451-7821972a7079",
"event_name": "iip.webplugin.funding_canceled",
"funding_destination": "credit"
}
```
***
### `TERMINAL_FAILURE`
Fired when the plugin reaches a terminal failure page due to account verification. The session remains active and can be retried — re-initialize the session using idempotency and mount again with the desired funding destination.
**Additional payload fields:**
| Field | Description |
| --------------------- | -------------------------------------------------------------------- |
| `funding_destination` | The funding destination being tokenized. |
| `error` | The error code that caused the failure. See error code tables below. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_396ba7d7-303a-4b05-a6d5-952f7acc2719",
"event_name": "iip.webplugin.terminal_failure",
"funding_destination": "credit",
"error": "4"
}
```
***
### `TERMINAL_FAILURE_ACKNOWLEDGED`
Fired when the recipient has acknowledged the terminal failure page and pressed the continue button. The session remains active.
**Additional payload fields:** same as `TERMINAL_FAILURE`.
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_0df67d09-5670-45de-a87b-ba54bd58f6ed",
"event_name": "iip.webplugin.terminal_failure_acknowledged",
"funding_destination": "credit",
"error": "4"
}
```
***
### `MAX_VERIFICATION_ATTEMPTS_EXCEEDED`
Fired when the recipient exceeds the maximum allowed verification failures. The session is **permanently terminated** and cannot be reused. A new session must be created.
```json theme={null}
{
"session_identifier": "54f59bcb-040d-40d8-928d-39895b4ad455",
"tracer_token": "12345_f63b668e-bb3e-4e70-9df1-1215b1fe7dc8",
"event_name": "iip.webplugin.max_verification_attempts_exceeded"
}
```
***
## BillPay Events
These events fire only when `FUNDING_DESTINATIONS.BILLPAY` is mounted.
### `ACCOUNT_COULD_NOT_BE_VERIFIED`
Fired when a recipient does not have their card present during BillPay account verification.
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_db4781bc-aff5-430b-9451-7821972a7079",
"event_name": "iip.webplugin.account_could_not_be_verified",
"funding_destination": "billpay"
}
```
### `BILLPAY_SEARCH_NO_MATCH_FOUND`
Fired when the recipient exceeds the allowed number of no-result biller searches. The session is **permanently terminated**. A new session must be created.
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_db4781bc-aff5-430b-9451-7821972a7079",
"event_name": "iip.webplugin.billpay_search_no_match_found",
"funding_destination": "billpay"
}
```
***
## Informative Events
These events provide visibility into the recipient's progress through the iFrame but do not represent outcomes.
### `PAGE_LOAD`
Fired each time a new page loads within the iFrame as the recipient navigates through the flow.
**Additional payload fields:**
| Field | Description |
| -------------- | ------------------------------------------------------------------ |
| `content.page` | Name of the current plugin page. See plugin pages reference below. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_01467df7-d00b-42a6-a824-f620fd93ef51",
"content": { "page": "DebitFunding" },
"event_name": "iip.webplugin.page_load"
}
```
**Account Verification**
| Page | Description |
| ------------------------------------ | ------------------------------------------------ |
| `MAX_VERIFICATION_ATTEMPTS_EXCEEDED` | Max failure exceeded page. |
| `ACCOUNT_COULD_NOT_BE_VERIFIED` | BillPay "I don't have my card" termination page. |
**ACH Funding**
| Page | Description |
| ------------------------------ | -------------------------------------------------------- |
| `ACH_FUNDING` | Bank account entry page. |
| `ACH_FUNDING_CONFIRM` | Bank account confirmation page. |
| `ACH_FUNDING_TERMINAL_RVDM` | Terminal — Recipient Verification Data Matching failure. |
| `ACH_FUNDING_TERMINAL_ANV` | Terminal — Account Number Validation failure. |
| `ACH_FUNDING_TERMINAL_NAV` | Terminal — Name on Account Validation failure. |
| `ACH_FUNDING_TERMINAL_RNV` | Terminal — Routing Number Validation failure. |
| `ACH_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure. |
**BillPay Funding**
| Page | Description |
| ---------------------------------- | ---------------------------------------- |
| `BILLPAY_FUNDING` | Biller search page. |
| `BILLPAY_FUNDING_CONFIRM` | Biller account confirmation page. |
| `BILLPAY_FUNDING_SEARCH_RESULTS` | Biller search results page. |
| `BILLPAY_FUNDING_NO_MATCH_FOUND` | Biller search no-match termination page. |
| `BILLPAY_FUNDING_TERMINAL_AV` | Terminal — Account verification failure. |
| `BILLPAY_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure. |
**Credit Card Funding**
| Page | Description |
| --------------------------------- | ------------------------------------------------ |
| `CREDIT_FUNDING` | Credit card entry page. |
| `CREDIT_FUNDING_CONFIRM` | Credit card confirmation page. |
| `CREDIT_FUNDING_TERMINAL_RVDM` | Terminal — RVDM failure. |
| `CREDIT_FUNDING_TERMINAL_AVS` | Terminal — Address Verification Service failure. |
| `CREDIT_FUNDING_TERMINAL_CNS` | Terminal — Card Not Supported. |
| `CREDIT_FUNDING_TERMINAL_CVV` | Terminal — CVV failure. |
| `CREDIT_FUNDING_TERMINAL_CD` | Terminal — Check Digit failure. |
| `CREDIT_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure. |
**Debit Card Funding**
| Page | Description |
| -------------------------------- | ------------------------------- |
| `DEBIT_FUNDING` | Debit card entry page. |
| `DEBIT_FUNDING_CONFIRM` | Debit card confirmation page. |
| `DEBIT_FUNDING_TERMINAL_RVDM` | Terminal — RVDM failure. |
| `DEBIT_FUNDING_TERMINAL_AVS` | Terminal — AVS failure. |
| `DEBIT_FUNDING_TERMINAL_CNS` | Terminal — Card Not Supported. |
| `DEBIT_FUNDING_TERMINAL_CVV` | Terminal — CVV failure. |
| `DEBIT_FUNDING_TERMINAL_CD` | Terminal — Check Digit failure. |
| `DEBIT_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure. |
**PayPal Funding**
| Page | Description |
| --------------------------------- | ---------------------------------------- |
| `PAYPAL_FUNDING` | PayPal entry page. |
| `PAYPAL_FUNDING_CONFIRM` | PayPal confirmation page. |
| `PAYPAL_FUNDING_TERMINAL_LOGIN` | Terminal — Login failure. |
| `PAYPAL_FUNDING_TERMINAL_CONSENT` | Terminal — User consent rejection. |
| `PAYPAL_FUNDING_TERMINAL_AV` | Terminal — Account verification failure. |
| `PAYPAL_FUNDING_TERMINAL_UNKNOWN` | Terminal — Unknown failure. |
**Session Management**
| Page | Description |
| ---------------------- | ------------------------------------------------------------- |
| `SESSION_UNAUTHORIZED` | Authorized URL has expired or funding destination is invalid. |
| `SESSION_INVALID` | Session has been canceled, terminated, or expired. |
| `SESSION_COMPLETED` | Session has already been completed. |
| `SESSION_TIMEOUT` | User's web session expired due to inactivity. |
***
### `PLUGIN_RESIZE`
Fired when the dimensions of the plugin contents change.
**Additional payload fields:**
| Field | Description |
| ---------------- | --------------------------------- |
| `content.width` | Current content width in pixels. |
| `content.height` | Current content height in pixels. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "12345_bf5f2aa7-2b25-494d-8cb7-1bc1773caa4c",
"content": { "width": 800, "height": 600 },
"event_name": "iip.webplugin.plugin_resize"
}
```
***
### `UNSUPPORTED_BROWSER_DETECTED`
Fired when the recipient's browser is not supported by the SDK.
**Additional payload fields:**
| Field | Description |
| -------------------- | ------------------------- |
| `browser.name` | Browser name. |
| `browser.version` | Browser version. |
| `browser.os` | Operating system name. |
| `browser.os_version` | Operating system version. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "",
"event_name": "iip.webplugin.unsupported_browser_detected",
"browser": {
"name": "Internet Explorer",
"version": "9.0",
"os": "Windows",
"os_version": "7"
}
}
```
***
## Warning / Error Events
### `PLUGIN_ERROR`
Fired when an unhandled exception occurs inside the plugin.
**Additional payload fields:**
| Field | Description |
| --------------- | ----------------------------------------- |
| `error.message` | Description of the unhandled exception. |
| `error.source` | Source file where the exception occurred. |
| `error.lineno` | Line number of the exception. |
| `error.colno` | Column number of the exception. |
| `error.err` | Exception name. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "",
"event_name": "iip.webplugin.plugin_error",
"error": {
"message": "Uncaught error",
"source": "...",
"lineno": 1,
"colno": 1,
"err": "Error message"
}
}
```
***
### `SESSION_ERROR`
Fired when the plugin reaches a session error page. The `content.status_code` identifies the specific error.
**Additional payload fields:**
| Field | Description |
| --------------------- | ------------------------------------------ |
| `content.page` | Session error page name. |
| `content.status_code` | Numeric status code identifying the error. |
**Status codes:**
| Code | Meaning |
| ------- | --------------------------------------------------- |
| `13404` | Transaction session has expired. |
| `13405` | Transaction has been canceled or terminated. |
| `13412` | Unauthorized — invalid or expired `authorized_url`. |
| `13413` | Transaction session has been completed. |
| `13414` | User's web session expired due to inactivity. |
```json theme={null}
{
"session_identifier": "55af9b73-5dcb-4a05-a490-1bdbf12e9fe7",
"tracer_token": "",
"event_name": "iip.webplugin.session_error",
"content": {
"page": "SessionExpired",
"status_code": 13414
}
}
```
***
## Error codes by payment type
These codes appear in the `error` field of `TERMINAL_FAILURE` and `TERMINAL_FAILURE_ACKNOWLEDGED` events.
### ACH (`IngoInstantPayments.ERROR_CODES.ACH`)
| Code | Constant | Meaning |
| ---- | --------- | ------------------------------------- |
| `0` | `UNKNOWN` | Unknown error. |
| `1` | `ANV` | Account Number Validation. |
| `2` | `NAV` | Name on Account Validation. |
| `3` | `RNV` | Routing Number Validation. |
| `4` | `RVDM` | Recipient Verification Data Matching. |
### Card — Credit & Debit (`IngoInstantPayments.ERROR_CODES.CARD`)
| Code | Constant | Meaning |
| ---- | --------- | ------------------------------------- |
| `0` | `UNKNOWN` | Unknown error. |
| `1` | `AVS` | Address Verification Service. |
| `2` | `CNS` | Card Not Supported. |
| `4` | `RVDM` | Recipient Verification Data Matching. |
| `5` | `CVV` | Card Verification Value. |
| `6` | `CD` | Check Digit. |
### BillPay (`IngoInstantPayments.ERROR_CODES.BILLPAY`)
| Code | Constant | Meaning |
| ---- | --------- | --------------------- |
| `0` | `UNKNOWN` | Unknown error. |
| `1` | `AV` | Account Verification. |
### PayPal (`IngoInstantPayments.ERROR_CODES.PAYPAL`)
| Code | Constant | Meaning |
| ---- | --------- | ------------------------- |
| `0` | `UNKNOWN` | Unknown error. |
| `1` | `LOGIN` | Login Failure. |
| `2` | `CONSENT` | PayPal Consent Rejection. |
| `3` | `AV` | Account Verification. |
# SDK Reference
Source: https://developers.ingopayments.com/docs/iframe/session/mounting
Methods and constants for the Ingo Instant Payments iFrame SDK.
The Ingo Instant Payments SDK is a JavaScript library that mounts the iFrame inside your web application. Include it via a `
```
***
## Methods
### `IngoInstantPayments.create(domElement, options?)`
Creates an instance of the SDK and attaches it to a DOM element in your page. Returns a `webPlugin` object that exposes the `mount` and `addEventListener` methods.
**Arguments**
| Argument | Required | Type | Description |
| ------------ | -------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `domElement` | Yes | Element or string | The DOM element or CSS selector where the iFrame will be injected (e.g. `document.getElementById("container")` or `"#container"`). |
| `options` | No | Object | Initialization options (see below). |
**Options**
| Option | Type | Default | Description |
| ------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `cssName` | string | — | A CSS class name to add to the iFrame element. |
| `autoHeight` | boolean | `false` | When `true`, the iFrame height adjusts automatically as its content changes or the window is resized. |
| `scrolling` | boolean | `false` | Enables or disables the iFrame's default scroll bars. |
```js theme={null}
var webPlugin = IngoInstantPayments.create(
document.getElementById("container"),
{
cssName: "web-plugin",
autoHeight: true,
scrolling: false
}
);
```
***
### `webPlugin.mount(authorizedUrl, fundingDestination)`
Mounts the iFrame and launches the account capture flow for the specified funding destination. Must be called after `create()`.
**Arguments**
| Argument | Required | Type | Description |
| -------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
| `authorizedUrl` | Yes | string | The `authorized_url` returned from the Session Create API. Valid for 30 seconds after creation. |
| `fundingDestination` | Yes | Constant | The account type to tokenize. Must be a valid `IngoInstantPayments.FUNDING_DESTINATIONS` value. |
**`FUNDING_DESTINATIONS` constants**
| Constant | Payment Type |
| -------------------------------------------------- | ------------------ |
| `IngoInstantPayments.FUNDING_DESTINATIONS.DEBIT` | Debit card |
| `IngoInstantPayments.FUNDING_DESTINATIONS.CREDIT` | Credit card |
| `IngoInstantPayments.FUNDING_DESTINATIONS.ACH` | Bank account (ACH) |
| `IngoInstantPayments.FUNDING_DESTINATIONS.BILLPAY` | BillPay |
| `IngoInstantPayments.FUNDING_DESTINATIONS.PAYPAL` | PayPal |
```js theme={null}
webPlugin.mount(
authorized_url,
IngoInstantPayments.FUNDING_DESTINATIONS.DEBIT
);
```
***
### `webPlugin.addEventListener(event, handler)`
Registers a callback function for a specific SDK event. This is the only way to receive data from the iFrame. Register listeners before or immediately after calling `mount()`.
**Arguments**
| Argument | Required | Type | Description |
| --------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `event` | Yes | Constant | The event to listen for. Must be a valid `IngoInstantPayments.EVENTS` value. |
| `handler` | Yes | function | Callback invoked when the event fires. Receives an event data object. |
**Common event payload fields**
Every event payload includes at minimum:
| Field | Description |
| -------------------- | ------------------------------------------------------------- |
| `session_identifier` | Unique identifier for the current session. |
| `tracer_token` | Token used for debugging across systems. |
| `event_name` | Name of the event fired (e.g. `iip.webplugin.token_success`). |
Additional fields are event-specific. See [SDK Events](/docs/iframe/session/events) for the full payload reference per event.
```js theme={null}
webPlugin.addEventListener(
IngoInstantPayments.EVENTS.TOKEN_SUCCESS,
function(data) {
var token = data.customer_account_token;
// use token with IngoPay process API
}
);
webPlugin.addEventListener(
IngoInstantPayments.EVENTS.PAGE_LOAD,
function(data) {
console.log(data.content.page); // e.g. "DebitFunding"
}
);
```
# Session Lifecycle
Source: https://developers.ingopayments.com/docs/iframe/session/session-management
Session states, idempotency, and locale configuration for Embedded Account Capture sessions.
Each session is a point-in-time object created by the Session Management API. It carries the recipient's information, governs the iFrame interaction lifecycle, and expires or terminates based on the outcome of the recipient's account capture flow.
***
## Session states
| State | Meaning |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Active | Session has been created and the `authorized_url` is valid. |
| Expired | The `authorized_url` was not mounted within 30 seconds. The session itself remains valid — use idempotency to generate a new `authorized_url`. |
| Completed | The recipient successfully tokenized an account (`TOKEN_SUCCESS`). The session cannot be mounted again. |
| Canceled / Terminated | The recipient canceled, or the session was terminated due to a terminal failure. A new session must be created to retry. |
| Max Attempts Exceeded | The recipient exceeded the configured verification attempt threshold. The session is terminated and cannot be reused. |
***
## Idempotency
The Session Management API supports idempotency to prevent duplicate sessions from being created when a network error or session event requires you to generate a new `authorized_url` for an existing session.
To make an idempotent request, include the `Idempotency-Key` header with the same value used in the original request:
```http theme={null}
Idempotency-Key: 70646041-01ea-4cd6-b657-18ff88e465c7
```
| Header | Description | Max Length |
| ----------------- | ---------------------------------------------------------------------- | ---------- |
| `Idempotency-Key` | A unique value you generate per session. Recommended: V4 UUID or GUID. | 250 |
When the server receives a request with a previously used idempotency key, it returns the original session with a new `authorized_url` — no new session is created. Idempotency keys remain active for **2 hours**. After expiration, the same key will generate a new session. If the incoming request parameters do not match the original, the server returns an error to prevent accidental misuse.
### Response codes
| Status | Message | Description |
| ------- | ------------------------ | ------------------------------------------------------------------------------- |
| `100` | Success | New session created. |
| `101` | Success - Idempotent | Existing session returned; new `authorized_url` issued. No new session created. |
| `13723` | Idempotency key mismatch | Incoming parameters do not match the original request. |
### Common scenarios
**Network error on session create** — If the initial request times out before you receive a response, retry with the same idempotency key. You are guaranteed to receive at most one session regardless of how many retries are sent.
**Non-terminal verification failure** — If the recipient fails verification (e.g., RVDM mismatch) but has not yet exceeded the maximum attempt threshold, the session remains active. Retry with the same idempotency key to generate a fresh `authorized_url` and allow the recipient to re-enter the flow.
```json theme={null}
{
"status": 101,
"client_message": "Success - Idempotent",
"data": {
"session_identifier": "5cf34a7d-25b6-4400-b19d-53a171d324e1",
"authorized_url": "https://iip-webplugin-uat.ingo.money/session/5cf34a7d-...",
"authorized_url_expiration_utc": "2024-01-17T20:30:30Z",
"participant_unique_id1": "2639d2ce-2e74-48a4-be74-9bb90a62b40b",
"participant_unique_id2": ""
}
}
```
***
## Locale
The iFrame UI can be rendered in any of the supported languages by passing the `language_locale_code` parameter in the session create request. If omitted, the iFrame defaults to the first configured language for your program.
```json theme={null}
{
"language_locale_code": "es-US",
...
}
```
### Supported locale codes
| Code | Language / Region |
| ---------- | ------------------------ |
| `ar-SA` | Arabic (Saudi Arabia) |
| `cs-CZ` | Czech (Czech Republic) |
| `da-DK` | Danish (Denmark) |
| `de-DE` | German (Germany) |
| `en-GB` | English (United Kingdom) |
| `en-US` | English (United States) |
| `es-ES` | Spanish (Spain) |
| `es-US` | Spanish (United States) |
| `fa-IR` | Farsi (Iran) |
| `fi-FI` | Finnish (Finland) |
| `fr-FR` | French (France) |
| `hmn-Latn` | Hmong (Latin) |
| `it-IT` | Italian (Italy) |
| `ja-JP` | Japanese (Japan) |
| `km-KH` | Khmer (Cambodia) |
| `ko-KR` | Korean (Korea) |
| `nb-NO` | Norwegian (Norway) |
| `nl-NL` | Dutch (Netherlands) |
| `pl-PL` | Polish (Poland) |
| `pt-BR` | Portuguese (Brazil) |
| `ru-RU` | Russian (Russia) |
| `sv-SE` | Swedish (Sweden) |
| `tl-PH` | Tagalog (Philippines) |
| `tr-TR` | Turkish (Turkey) |
| `vi-VN` | Vietnamese (Vietnam) |
| `zh-CN` | Chinese (China) |
| `zh-Hans` | Chinese (Simplified) |
| `zh-TW` | Chinese (Taiwan) |
# Testing
Source: https://developers.ingopayments.com/docs/iframe/testing
Scenario-based testing guide for the Embedded Account Capture iFrame plugin — session management, account tokenization, and payment processing.
## Sandbox Environment
Your sandbox mirrors production behavior including account verification services, OFAC screening, and webhook delivery. Sandbox credentials and velocity limits are provisioned during onboarding.
Sandbox velocity limits are client-specific and configured by your Ingo integration manager during onboarding.
***
## Test Categories
| Category | Description | How to initiate |
| ---------------- | ------------------------------------------------------- | -------------------------------------------- |
| **Self-Service** | Complete independently in the sandbox at your own pace | Your sandbox credentials |
| **Controlled** | Requires an enablement flag or pre-loaded test accounts | Contact your integration manager to schedule |
***
## Understanding Soft Failures
**Soft failure** — A partial match that does not stop the flow. The recipient experiences no interruption and proceeds transparently. Your system is notified of the result in the background via the correlated **success** webhook carrying the soft-fail status code. No failure webhook emits.
**Hard failure** — A mismatch on a field your configuration has designated as requiring a hard failure. How each verification field's mismatch is treated is defined during your implementation setup via the configuration form. When a hard failure occurs, the recipient is stopped and must retry. If maximum attempts are exhausted, the session or transaction terminates.
***
## How EAC Testing Works
The Embedded Account Capture flow has two distinct phases, each with its own API call and webhook events:
**Phase 1 — Session API + iFrame Plugin**
Call `POST /api/v1/sessions/point-in-time/plugin` to create a session. Mount the plugin in your application. The recipient interacts with the iFrame — RVDM verification and account tokenization happen within the session. Plugin events use `plugin.*` webhook topics.
**Phase 2 — Process API**
After the recipient's account is tokenized, call `POST /gateway/process` to initiate the disbursement. Payment status events use `gateway.*` webhook topics.
***
## Self-Service Scenarios
**Category:** Self-Service
**Scenario:** Send a Session API request with valid recipient information. Mount the plugin successfully in your application.
**Success criteria:** Session created, `authorized_url` returned, plugin mounts
**Category:** Self-Service
**Scenario:** Resend the same Session API request using the same `Idempotency-Key` header. Confirms that no duplicate session is created.
**Success criteria:** Response `status: 101` — existing session returned, no new session created
**Category:** Self-Service
**Scenario:** Resend a Session API request using the same `Idempotency-Key` but with modified request body parameters. Confirms that idempotency key mismatch is rejected.
**Success criteria:** Error response indicating idempotency key conflict
**Category:** Self-Service
**Scenario:** Create a session and mount the plugin. Allow the session to expire without any recipient input. Confirms your system handles session expiry correctly.
**Success criteria:** Session expired event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | -------------------------------------------- | --------------- |
| — | Session Expired | `plugin.transaction.session.request.expired` | 1128 |
**Category:** Self-Service
**Scenario:** Create a session. Mount the plugin. The recipient enters card details with session recipient information that fully matches. Account is tokenized successfully.
**Success criteria:** RVDM success and tokenization success events fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | -------------------------------------------------------- | --------------- |
| 1 | RVDM Success | `plugin.transaction.recipient.verification.rvdm.success` | 1103 |
| 2 | Tokenization Success | `plugin.transaction.account.tokenization.success` | 100 |
**Category:** Self-Service
**Scenario:** The recipient enters card details with partially matching session recipient information. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial match in the background via the RVDM success webhook carrying the soft-fail status code. Tokenization still succeeds.
**Success criteria:** RVDM success fires with soft-fail code; tokenization success follows
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | -------------------------------------------------------- | --------------- |
| 1 | RVDM Success | `plugin.transaction.recipient.verification.rvdm.success` | 1104 |
| 2 | Tokenization Success | `plugin.transaction.account.tokenization.success` | 100 |
**Category:** Self-Service
**Scenario:** The recipient enters card details with non-matching session recipient information. The RVDM hard failure stops the flow. The recipient may retry until max attempts are reached, at which point the session terminates.
**Success criteria:** RVDM failure fires; session terminates after max attempts
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | -------------------------------------------------------- | --------------- |
| 1 | RVDM Failure | `plugin.transaction.recipient.verification.rvdm.failure` | 1105 |
| 2 | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
**Category:** Self-Service
**Scenario:** The recipient enters a card account number not supported for disbursement. The plugin stops the recipient and the session eventually terminates.
**Success criteria:** CNS/CD failure fires; session terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | ------------------------------------------------------------- | --------------- |
| 1 | CNS/CD Failure | `plugin.transaction.account.verification.card.cns_cd.failure` | 700 |
| 2 | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
**Category:** Self-Service
**Scenario:** The recipient exhausts all attempts across verification failures. The session terminates.
**Success criteria:** Session terminated event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | ----------------------------------------------- | --------------- |
| — | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
**Category:** Self-Service
**Scenario:** Create a session. Mount the plugin. The recipient enters a valid routing and account number with fully matching session recipient information. Account is tokenized successfully.
**Success criteria:** RVDM success and tokenization success events fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | -------------------------------------------------------- | --------------- |
| 1 | RVDM Success | `plugin.transaction.recipient.verification.rvdm.success` | 1103 |
| 2 | Tokenization Success | `plugin.transaction.account.tokenization.success` | 100 |
**Category:** Self-Service
**Scenario:** The recipient enters ACH details with partially matching session recipient information. The recipient experiences no interruption. Your system is notified of the partial match in the background. Tokenization still succeeds.
**Success criteria:** RVDM success fires with soft-fail code; tokenization success follows
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | -------------------------------------------------------- | --------------- |
| 1 | RVDM Success | `plugin.transaction.recipient.verification.rvdm.success` | 1104 |
| 2 | Tokenization Success | `plugin.transaction.account.tokenization.success` | 100 |
**Category:** Self-Service
**Scenario:** The recipient enters ACH details with non-matching session recipient information until max attempts are reached. The session terminates.
**Success criteria:** RVDM failure fires; session terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | -------------------------------------------------------- | --------------- |
| 1 | RVDM Failure | `plugin.transaction.recipient.verification.rvdm.failure` | 1105 |
| 2 | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
**Category:** Self-Service
**Scenario:** Create a session. Mount the plugin. The recipient searches for and selects a biller, enters their account number, and a single biller match is found. Account is tokenized successfully.
**Success criteria:** Tokenization success event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | ------------------------------------------------- | --------------- |
| — | Tokenization Success | `plugin.transaction.account.tokenization.success` | 100 |
**Category:** Self-Service
**Scenario:** The biller search returns multiple matches. The recipient selects the correct biller and the account is tokenized successfully.
**Success criteria:** Tokenization success event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | ------------------------------------------------- | --------------- |
| — | Tokenization Success | `plugin.transaction.account.tokenization.success` | 100 |
**Category:** Self-Service
**Scenario:** The biller search returns no matches for the account data entered. The session terminates.
**Success criteria:** Session terminated event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | ----------------------------------------------- | --------------- |
| — | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
Process API testing — including successful payments, idempotency, velocity limits, and mocked issuer responses — is documented in the [IngoPay API testing guide](/ingopay/testing). The `customer_account_token` returned from the iFrame plugin is used directly in the IngoPay Process API request.
***
## Controlled Scenarios
The following scenarios require your Ingo integration manager to enable a specific configuration or pre-load test accounts before testing can begin. Contact your integration team to schedule these.
**Category:** Controlled
**Scenario:** A card account tokenization where the AVS check returns a soft failure. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial address match in the background via the tokenization success webhook carrying the soft-fail status code.
**Success criteria:** Tokenization success fires with AVS soft-fail status code
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | -------------------------------------------------------- | --------------- |
| 1 | RVDM Success | `plugin.transaction.recipient.verification.rvdm.success` | 1103 or 1104 |
| 2 | Tokenization Success | `plugin.transaction.account.tokenization.success` | 111–119 range |
**Category:** Controlled
**Scenario:** A card account tokenization where the AVS check returns a hard decline. Your system is notified via the AVS/CVV failure webhook. The session terminates.
**Success criteria:** AVS/CVV failure fires; session terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | -------------------------------------------------------------- | --------------- |
| 1 | AVS/CVV Failure | `plugin.transaction.account.verification.card.avs_cvv.failure` | 753–759 range |
| 2 | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
**Category:** Controlled
**Scenario:** A card account tokenization where the CVV check returns a hard decline. Your system is notified via the AVS/CVV failure webhook. The session terminates.
**Success criteria:** AVS/CVV failure fires; session terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | -------------------------------------------------------------- | --------------- |
| 1 | AVS/CVV Failure | `plugin.transaction.account.verification.card.avs_cvv.failure` | — |
| 2 | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
**Category:** Controlled
**Scenario:** An ACH account verification returns a soft failure on account number (ANV) or name/address (NAV) validation. The recipient experiences no interruption. Your system is notified of the partial match in the background via the tokenization success webhook carrying the soft-fail status code.
**Success criteria:** Tokenization success fires with soft-fail status code
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | -------------------------------------------------------- | --------------------- |
| 1 | RVDM Success | `plugin.transaction.recipient.verification.rvdm.success` | 1103 or 1104 |
| 2 | Tokenization Success | `plugin.transaction.account.tokenization.success` | Soft-fail status code |
**Category:** Controlled
**Scenario:** ACH account verification returns a hard decline on routing number, account number, or name/address validation. Your system is notified via the appropriate failure webhook. The session terminates.
**Success criteria:** Applicable failure event fires; session terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | --------------------------------------------------------- | --------------- |
| — | RNV Failure | `plugin.transaction.account.verification.ach.rnv.failure` | 743 |
| — | *or* ANV Failure | `plugin.transaction.account.verification.ach.anv.failure` | 767–769 |
| — | *or* NAV Failure | `plugin.transaction.account.verification.ach.nav.failure` | 776–778 |
| — | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
***
## Webhook Events Reference
| Event | Topic | Expected Status |
| ------------------ | ----------------------------------------------- | --------------- |
| Session Expired | `plugin.transaction.session.request.expired` | 1128 |
| Session Terminated | `plugin.transaction.session.request.terminated` | 1127, 1129 |
| Event | Topic | Expected Status |
| ------------ | -------------------------------------------------------- | ----------------------------- |
| RVDM Success | `plugin.transaction.recipient.verification.rvdm.success` | 1103 (full), 1104 (soft fail) |
| RVDM Failure | `plugin.transaction.recipient.verification.rvdm.failure` | 1105 |
| Event | Topic | Expected Status |
| -------------------- | -------------------------------------------------------------- | --------------- |
| Card CNS/CD Failure | `plugin.transaction.account.verification.card.cns_cd.failure` | 700 |
| Card AVS/CVV Failure | `plugin.transaction.account.verification.card.avs_cvv.failure` | 753–759 |
| ACH RNV Failure | `plugin.transaction.account.verification.ach.rnv.failure` | 743 |
| ACH ANV Failure | `plugin.transaction.account.verification.ach.anv.failure` | 767–769 |
| ACH NAV Failure | `plugin.transaction.account.verification.ach.nav.failure` | 776–778 |
| PayPal AV Failure | `plugin.transaction.account.verification.paypal.failure.av` | 1150 |
| Event | Topic | Expected Status |
| -------------------- | ------------------------------------------------- | ----------------------------------- |
| Tokenization Success | `plugin.transaction.account.tokenization.success` | 100 (full), 111–119 (AVS soft fail) |
# Webhooks
Source: https://developers.ingopayments.com/docs/iframe/webhooks/overview
Server-side event notifications for Embedded Account Capture — verification outcomes, account tokenization, and session lifecycle events.
The Embedded Account Capture SDK fires both client-side JavaScript events (handled in your browser application) and server-side webhook events posted to your registered HTTPS endpoint. This page covers the server-side webhooks. For the client-side SDK events — `TOKEN_SUCCESS`, `SESSION_EXPIRED`, and others — see the [SDK Events reference](/docs/iframe/sdk-events).
Webhooks are delivered as JSON via HTTP POST to your registered endpoint. Return any `2xx` status to acknowledge receipt. See [Webhooks](/docs/hub/webhooks) for endpoint requirements, IP allowlist, and retry behavior.
***
## Event categories
| Category | What it covers |
| -------------------------- | ----------------------------------------------------------------------------- |
| **Recipient Verification** | RVDM identity matching success and failure outcomes |
| **OFAC Screening** | Compliance hold, clearance, and failure events |
| **Account Verification** | Card (CNS/CD, AVS/CVV), ACH (RNV, ANV, NAV), and PayPal verification outcomes |
| **Account Tokenization** | Successful account tokenization — includes the `customer_account_token` |
| **Session Lifecycle** | Session expired and session terminated events |
***
## Event reference
All Embedded Account Capture webhook events are documented in the AsyncAPI spec. Each channel page includes the full payload schema and an example.
Full event catalog — payload schemas, field definitions, and examples for every server-side EAC webhook event.
# Biller Search
Source: https://developers.ingopayments.com/docs/ingopay/ancillary/biller-search
specs/ingopay-biller-payments-search.yaml POST /gateway/v1/biller/search
Search for available billers and retrieve the payee_id required for BillPay verify.
# Check Cancel
Source: https://developers.ingopayments.com/docs/ingopay/ancillary/check-cancel
specs/ingopay-check-cancel.yaml POST /gateway/checkcancel
Cancel an Ingo-issued check in routed or check_issued status.
# Check Stop
Source: https://developers.ingopayments.com/docs/ingopay/ancillary/check-stop
specs/ingopay-check-stop.yaml POST /gateway/checkstop
Request a stop payment on an Ingo-issued check in check_issued status.
# Retrieve Account Data via Open Banking
Source: https://developers.ingopayments.com/docs/ingopay/ancillary/open-banking-account
specs/ingopay-open-banking-account.yaml POST /gateway/v1/open-banking-account
Retrieve detailed account information, balances, owners, or transaction history from a supported open banking provider.
**Under Development — Coming Soon.** This endpoint is currently under development and is not yet available for integration. Specifications are subject to change prior to general availability. Contact your Ingo integration manager for availability updates.
# Debit Process — ACH
Source: https://developers.ingopayments.com/docs/ingopay/debit/process-ach
specs/ingopay-debit-process-ach.yaml POST /gateway/v12/debit/process--ach
Pull funds from a bank account via Standard ACH or Same-Day ACH (v12 debit gateway).
# Debit Process — Card
Source: https://developers.ingopayments.com/docs/ingopay/debit/process-card
specs/ingopay-debit-process-card.yaml POST /gateway/v12/debit/process--card
Pull funds from a debit or credit card (v12 debit gateway).
# Pull Funds via Wire Drawdown
Source: https://developers.ingopayments.com/docs/ingopay/debit/process-wire
specs/ingopay-debit-process-wire.yaml POST /gateway/v12/debit/process--wire
Initiate a wire transfer drawdown request to pull funds from a wire-enabled recipient account.
**Under Development — Coming Soon.** This endpoint is currently under development and is not yet available for integration. Specifications are subject to change prior to general availability. Contact your Ingo integration manager for availability updates.
# IngoPay API
Source: https://developers.ingopayments.com/docs/ingopay/overview
Single-endpoint verify and process APIs for push and pull payments across card, bank accounts, check, PayPal, Venmo, and BillPay.
Ingo Payments · IngoPay API
Verify once. Disburse anywhere, anytime.
Two endpoints. Every payment type. Full risk intelligence built in.
The IngoPay API is built on a deliberately simple two-step model. A single **verify** call tokenizes any recipient account type — card, ACH, check, PayPal, Venmo, or BillPay — while simultaneously executing every downstream identity and account verification check your risk profile requires. There is no cascade of individual verification calls to manage; Ingo orchestrates your configured risk mitigation controls in a single round trip and returns a reusable `customer_account_token`. That token represents both the customer and their account, never expires, and can be reused for any number of future transactions. A single **process** call then moves funds using that token — regardless of payment type, always through the same endpoint. The acceptance of each transaction attempt for most payment types is determined in real time against the current standing of the account at the financial institution, keeping your risk posture current without adding integration complexity.
***
## Push Funds to an Account
Send disbursements to any supported payment method. The same verify → process flow applies across all types — your integration scope stays constant regardless of how many payment methods you enable.
Push funds instantly to any elegible debit or prepaid card. A single
verify call validates the card and executes your configured identity and account
checks, returning a reusable token. Use that token to push funds on demand —
no re-verification required.
Transfer funds directly into a bank account via standard or same-day ACH or through
the Real-Time Payments (RTP) network. Verify once to tokenize the account
and run your configured identity and account checks — then process disbursements
whenever needed using the same persistent token.
Disburse funds directly to a recipient's PayPal or Venmo digital wallet. A single
verify call confirms the wallet account and runs your configured checks, returning
a token that can be reused for any future disbursements to that wallet.
Issue a physical check disbursement to any mailing address. Verify returns a token — process
then queues the check for printing and delivery with no additional workflow required
on your end.
Enable recipients to direct disbursements toward bill payments across utilities,
loans, healthcare, and more. Search the biller network, tokenize the recipient's
biller account, and process payments directly to the biller on their behalf.
Enable recipients to direct a disbursement toward their credit card balance,
reducing the amount they owe. The card account is tokenized and the disbursement
is routed to the card issuer — the same verify → process flow as every other
IngoPay payment type.
***
## Pull Funds from an Account
Debit a recipient account and pull funds into your program. Each payment type follows the same verify → debit process flow — a single verify call tokenizes the account and runs your configured checks, and a single debit process call initiates the pull.
Pull funds from a debit card account. Verify tokenizes the card and runs your
configured identity and account checks — debit process initiates the pull against
that token on demand.
Pull funds from a bank account via standard or same-day ACH. One verify call
tokenizes the account and runs your checks — reuse that token to initiate ACH
debits at any point going forward.
Pull funds via domestic wire transfer. Verify tokenizes the wire account and
executes your configured checks — debit process initiates the wire when you're
ready to move funds.
# Payment Methods
Source: https://developers.ingopayments.com/docs/ingopay/payment-methods
Delivery speeds, use cases, and eligibility across every IngoPay payment type.
IngoPay supports push (credit) and pull (debit) transactions across eight payment types through a single verify → process architecture. The right payment type depends on your recipients' preferences, required delivery speed, and the nature of the disbursement. Many clients enable multiple types simultaneously — the integration scope remains the same regardless of how many you activate.
***
## Push Payments — Send Funds to a Recipient
| Payment Type | Delivery Speed | Best For |
| --------------------------------------- | -------------------------- | ------------------------------------------------------------------ |
| Debit & Prepaid Card | Minutes | Gig worker pay, insurance claims, instant rebates, gaming payouts |
| Bank Account (ACH / Same-Day ACH / RTP) | Minutes to 3 business days | Payroll, large disbursements, unbanked-friendly use cases |
| PayPal | Minutes | Recipients who prefer digital wallets over bank accounts |
| Venmo | Minutes | Consumer-facing programs targeting younger demographics |
| Check by Mail | 3–7 business days | Recipients without bank accounts or digital wallets |
| BillPay | 1–3 business days | Directing disbursements toward a recipient's existing bills |
| Credit Card Balance Paydown | 1–3 business days | Reducing a recipient's credit card balance with their disbursement |
Push funds in minutes to any eligible Visa or Mastercard debit or prepaid card via Visa Direct and Mastercard Send. This is the fastest delivery method for recipients with a debit card and the most common choice for real-time disbursement programs such as gig economy payouts, earned wage access, and insurance claims settlement.
Transfer funds directly into a checking or savings account. Three delivery rails are available under the same verify → process flow — the rail is determined by the `account_type` value sent in the process request:
| Rail | `account_type` | Delivery Speed | Notes |
| ------------------ | -------------- | ----------------- | ---------------------------------------------------------------------------------------- |
| Standard ACH | `AC` | 1–3 business days | Broadest compatibility — virtually every U.S. bank account can receive an ACH credit |
| Same-Day ACH | `SD` | Same business day | Available for time-sensitive disbursements; subject to network cutoffs and amount limits |
| Real-Time Payments | `RT` | Minutes | Instant credit; availability depends on recipient bank participation in the RTP network |
ACH is the most broadly compatible choice. Same-Day ACH and RTP are ideal for programs where speed matters — earned wage access, emergency disbursements, and on-demand payouts.
Disburse to a recipient's PayPal or Venmo digital wallet. Both networks deliver funds in minutes. PayPal offers broader global reach; Venmo is predominantly used by U.S. consumers and tends to perform well in younger-demographic programs such as student refunds, gaming, and loyalty rewards.
Issue a physical check to any U.S. mailing address. While the slowest delivery option, check by mail remains the most accessible — reaching recipients who have no bank account, no debit card, and no digital wallet. Commonly offered as a fallback option in multi-rail programs to ensure 100% recipient coverage.
Enable recipients to direct a disbursement toward an existing bill — utilities, loans, healthcare, insurance premiums, and more — rather than receiving cash. Ingo routes the payment directly to the biller on the recipient's behalf. Particularly effective in healthcare, government benefits, and financial wellness programs where directing funds toward specific obligations is a program goal.
Enable recipients to direct a disbursement toward their credit card balance, reducing the amount they owe to the card issuer. Rather than receiving funds directly, the disbursement is routed to the card network on their behalf. Uses the same verify → process flow as all other IngoPay payment types.
***
## Pull Payments — Collect Funds from a Recipient
| Payment Type | Settlement Speed | Best For |
| --------------------------------- | ------------------------------------ | ------------------------------------------ |
| Debit Card | Minutes | Instant collection at point of interaction |
| Bank Account (ACH / Same-Day ACH) | Same business day to 3 business days | Recurring collections, large amounts |
| Wire Transfer | Same day (domestic) | High-value, time-sensitive collections |
Pull funds from a debit card account in minutes using the same card token generated during verify. Commonly used in insurance premium collection, loan repayment, and any scenario where instant debit against a known card is preferred.
Pull funds from a checking or savings account via standard ACH (1–3 business days) or same-day ACH. The same `account_type` values used for push apply here — use `AC` for standard ACH or `SD` for same-day. The most common collection method for recurring programs, as the reusable token eliminates re-collecting account details on subsequent pulls.
Pull funds via domestic wire for high-value, time-sensitive collections. Wires settle the same business day when initiated before the network cutoff. Typically used in B2B scenarios, treasury operations, and large settlement flows.
# Process — ACH
Source: https://developers.ingopayments.com/docs/ingopay/process/ach
specs/ingopay-process-ach.yaml POST /gateway/process--ach
Push a disbursement via Standard ACH, Same-Day ACH, or Real-Time rails.
# Process — BillPay
Source: https://developers.ingopayments.com/docs/ingopay/process/billpay
specs/ingopay-process-billpay.yaml POST /gateway/process--billpay
Push a disbursement to a tokenized biller account.
# Process — Card
Source: https://developers.ingopayments.com/docs/ingopay/process/card
specs/ingopay-process-card.yaml POST /gateway/process--card
Push a disbursement to a tokenized debit or credit card account.
# Process — Check by Mail
Source: https://developers.ingopayments.com/docs/ingopay/process/check
specs/ingopay-process-check.yaml POST /gateway/process--check
Disburse funds via Ingo-issued check mailed to the recipient.
# Process — PayPal / Venmo
Source: https://developers.ingopayments.com/docs/ingopay/process/paypal-venmo
specs/ingopay-process-paypal-venmo.yaml POST /gateway/process--paypal-venmo
Push a disbursement to a PayPal Verified, PayPal Unverified, or Venmo account.
# Process — Retail Card Present
Source: https://developers.ingopayments.com/docs/ingopay/process/retail-card-present
specs/ingopay-process-retail-card-present.yaml POST /gateway/process--retail
Push disbursement for retail card-present configured clients.
# Quick Start
Source: https://developers.ingopayments.com/docs/ingopay/quick-start
Make your first IngoPay verify and process call — tokenize an account and push a payment in minutes.
This guide walks through the core IngoPay flow end to end: signing a request, verifying a card account to get a reusable token, and using that token to push a payment. The card example shown here applies structurally to every other payment type — the only differences are the account fields you send and the `account_type` code you use.
You'll need your **username**, **secret**, and **participant\_id** to follow this guide. These are issued by your Ingo integration manager during onboarding. If you don't have credentials yet, contact your integration manager before proceeding.
***
## Environments
| Environment | Base URL |
| ----------- | ----------------------------------- |
| Sandbox | `https://payapi-sandbox.ingo.money` |
| Production | `https://payapi.ingo.money` |
Use sandbox credentials for all development and testing. Production credentials are issued after sandbox certification is complete.
***
Every IngoPay request must be signed using **HMAC-SHA512**. Your secret never leaves your server — it is used locally to produce a signature that Ingo verifies on each request.
Before sending any request, generate these four headers:
| Header | Description |
| ---------------- | --------------------------------------------------------------------------------- |
| `X-Date` | Current timestamp in RFC 1123 / GMT format. Clock skew tolerance is ±300 seconds. |
| `Content-sha512` | Base64-encoded SHA-512 hash of the raw request body. Use RAW output — not hex. |
| `Content-Length` | Byte length of the request body. |
| `Content-Type` | Always `application/json`. |
Then build your `Authorization` header:
```
Authorization: hmac username="{username}", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="{signature}"
```
The signature is an HMAC-SHA512 hash of a string assembled from the request line and each signed header value, Base64-encoded. See [Authentication](/docs/hub/authentication) for the full step-by-step construction guide.
Use **RAW** (binary) output from your HMAC library before Base64 encoding — not hex. Base64-encoding hex output produces an incorrect signature and a `401 Unauthorized` response.
The verify call tokenizes the recipient account and runs every identity and account check configured in your risk profile — in a single request. Submit the card details; Ingo returns a `customer_account_token` you'll use for all future transactions with this account.
```http theme={null}
POST /gateway/verify HTTP/1.1
Host: payapi-sandbox.ingo.money
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="hAMqhSX6eogO1QpES9Dg..."
X-Date: Fri, 17 Jan 2020 19:59:29 GMT
Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08=
Content-Length: 245
Content-Type: application/json
{
"participant_id": 12345,
"account_type": "CA",
"recipient_first_name": "Tom",
"recipient_last_name": "Smith",
"account": "4264531111111115",
"expiration_date": "2212",
"cvv": "000",
"recipient_address1": "123 Main St",
"recipient_city": "Smallville",
"recipient_state": "TX",
"recipient_zip": "93245",
"recipient_phone": "8015555555",
"participant_unique_id1": "VRF-0001",
"timestamp": 1579291169,
"version": "11"
}
```
A successful response returns an `approved` status and your token:
```json theme={null}
{
"status": "approved",
"participant_id": 12345,
"customer_account_token": "cust_tok_abc123xyz..."
}
```
The `customer_account_token` never expires. Store it alongside the customer record in your system. You will use it — not raw card data — for every future disbursement and debit to this account.
Use the `customer_account_token` from the verify response to push funds. You never re-submit raw account data — the token is all the process call needs to identify and disburse to the account.
```http theme={null}
POST /gateway/process HTTP/1.1
Host: payapi-sandbox.ingo.money
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="kJNrpSY7fphR2PqFT0Eh9..."
X-Date: Fri, 17 Jan 2020 20:01:14 GMT
Content-sha512: BqMnXk8rEbtPLWmJIRpu5DKzBSe+NCeVdpIC6QMko19=
Content-Length: 158
Content-Type: application/json
{
"participant_id": 12345,
"account_type": "CA",
"customer_account_token": "cust_tok_abc123xyz...",
"amount": "100.00",
"participant_unique_id1": "TXN-0001",
"timestamp": 1579291274,
"version": "11"
}
```
A successful response confirms the transaction:
```json theme={null}
{
"status": "approved",
"participant_id": 12345,
"transaction_id": "ING-20200117-00001",
"amount": "100.00",
"customer_account_token": "cust_tok_abc123xyz..."
}
```
After a process call, Ingo posts a real-time webhook to your configured endpoint with the final transaction outcome. Do not rely solely on the synchronous response — some payment types complete asynchronously and the webhook carries the authoritative result.
See [Webhooks](/docs/ingopay/webhooks/overview) for payload structure, event types, and signature verification.
***
## What's next
Full HMAC-SHA512 construction guide, header reference, and common signing errors.
Delivery speeds, use cases, and eligibility across every supported payment type.
Event types, payload structure, and how to verify webhook signatures.
Status codes, decline reasons, and retry guidance.
# Risk Score
Source: https://developers.ingopayments.com/docs/ingopay/risk/risk-score
specs/ingopay-risk.yaml POST /risk/riskscore/v2
Evaluate the risk of a transaction and obtain a risk assessment token for use in subsequent process calls.
# Risk Session
Source: https://developers.ingopayments.com/docs/ingopay/risk/risk-session
specs/ingopay-risk.yaml POST /risk/risksession/v2
Initialize a risk evaluation session token for use with the Risk Score endpoint.
# Testing
Source: https://developers.ingopayments.com/docs/ingopay/testing
Scenario-based testing guide for IngoPay API direct payment integrations — Verify, Process, risk management, and payment error handling.
## Sandbox Environment
Your sandbox mirrors production behavior including payment routing logic, risk management services, OFAC screening, and webhook delivery. Sandbox credentials and velocity limits are provisioned during onboarding.
Sandbox velocity limits are client-specific and configured by your Ingo integration manager during onboarding.
***
## Test Categories
| Category | Description | How to initiate |
| ---------------- | -------------------------------------------------------- | -------------------------------------------- |
| **Self-Service** | Complete independently in the sandbox at your own pace | Your sandbox credentials |
| **Controlled** | Requires an enablement flag or pre-loaded test accounts | Contact your integration manager to schedule |
| **Guided** | Live session with your Ingo integration team recommended | Contact your integration manager to schedule |
***
## How IngoPay Testing Works
IngoPay is a synchronous REST API. Verification and process results are returned directly in the API response — your integration handles routing logic based on the status code returned. A small number of scenarios (OFAC screening, returned payments) also generate asynchronous `gateway.*` webhook events after the initial response.
***
## Self-Service Scenarios
**Category:** Self-Service
**Scenario:** Submit a Verify request with a valid test account. The account is tokenized and a `customer_account_token` is returned for use in subsequent Process requests.
**API call:** `POST /gateway/verify`
**Success criteria:**
* Response `status: 100`
* `customer_account_token` present in response data
**Key response fields to verify:**
| Field | Expected |
| ----------------------------- | --------------- |
| `status` | `100` |
| `client_message` | `Success` |
| `data.customer_account_token` | Non-null string |
**Category:** Self-Service
**Scenario:** Submit a second Verify request using the `customer_account_token` returned from a prior successful verify. Confirms the token can be reused without re-entering account credentials.
**API call:** `POST /gateway/verify`
**Success criteria:** Response `status: 101`
**Key response fields to verify:**
| Field | Expected |
| ---------------- | ---------------------- |
| `status` | `101` |
| `client_message` | `Success - Idempotent` |
**Category:** Self-Service
**Scenario:** Submit a Verify or Process request with an account number not supported for disbursement. Confirms correct handling of unsupported account types.
**Success criteria:** Response `status: 700`
**Key response fields to verify:**
| Field | Expected |
| ---------------- | --------------------------------------------------------- |
| `status` | `700` |
| `client_message` | `Account not currently available for processing via Ingo` |
**Category:** Self-Service
**Scenario:** Submit a Verify request with a malformed card account number that fails the check digit algorithm.
**Success criteria:** Response `status: 1042`
**Key response fields to verify:**
| Field | Expected |
| ---------------- | ----------------------------------------------------------------- |
| `status` | `1042` |
| `client_message` | `Check Digit Failure - Please check account number and try again` |
**Category:** Self-Service
**Scenario:** Submit a Process request using a valid `customer_account_token`. The payment is processed successfully.
**API call:** `POST /gateway/process`
**Applicable account types:** CA, AC, PD, BP, CK
**Success criteria:** Response `status: 100`
**Key response fields to verify:**
| Field | Expected |
| --------------------- | --------------- |
| `status` | `100` |
| `client_message` | `Success` |
| `data.transaction_id` | Non-null string |
**Category:** Self-Service
**Scenario:** Resubmit the same Process request using the same `participant_unique_id1`. Confirms duplicate payment protection is working correctly.
**Success criteria:** Response `status: 101`
**Key response fields to verify:**
| Field | Expected |
| ---------------- | ---------------------- |
| `status` | `101` |
| `client_message` | `Success - Idempotent` |
**Category:** Self-Service
**Scenario:** Submit Process requests that exceed your configured velocity limits. Confirms your system handles each limit condition gracefully.
**Success criteria:** Appropriate status code returned for each limit condition
**Key response fields to verify:**
| Scenario | Expected Status |
| ---------------------------------- | --------------- |
| Amount below issuer minimum | `603` |
| Exceeds single transaction limit | `711` |
| Exceeds daily amount limit | `712` |
| Exceeds weekly amount limit | `713` |
| Exceeds monthly amount limit | `714` |
| Exceeds max transactions per month | `715` |
| Exceeds 15-day amount limit | `716` |
***
## Controlled Scenarios
The following scenarios require your Ingo integration manager to enable a specific configuration or pre-load test accounts before testing can begin. Contact your integration team to schedule these.
**Category:** Controlled
**Scenario:** Submit a Verify request with a card account configured to trigger an AVS soft failure. The verification proceeds and the account is tokenized. Your system receives the soft-fail status code in the Verify response.
**Success criteria:** Verify response contains AVS soft-fail status code; `customer_account_token` present
**Key response fields to verify:**
| Field | Expected |
| ----------------------------- | --------------- |
| `status` | `111–119` range |
| `data.customer_account_token` | Non-null string |
**Category:** Controlled
**Scenario:** Submit a Verify request with a card account configured to trigger an AVS hard decline. The request fails and no token is issued.
**Success criteria:** Verify response returns AVS decline status code; no token issued
**Key response fields to verify:**
| Field | Expected |
| -------- | -------------- |
| `status` | `750` or `751` |
**Category:** Controlled
**Scenario:** Submit a Verify request with a card account configured to trigger a CVV hard decline.
**Success criteria:** Verify response returns CVV decline status code; no token issued
**Key response fields to verify:**
| Field | Expected |
| -------- | -------- |
| `status` | `765` |
**Category:** Controlled
**Scenario:** Submit a Verify request with an ACH account configured to trigger a soft failure on account number validation (ANV) or name/address validation (NAV). The verification proceeds and the account is tokenized. Your system receives the soft-fail status code in the Verify response.
**Success criteria:** Verify response contains soft-fail status code; `customer_account_token` present
**Key response fields to verify:**
| Field | Expected |
| ----------------------------- | ----------------------------------- |
| `status` | `122–126` range (ANV/NAV soft fail) |
| `data.customer_account_token` | Non-null string |
**Category:** Controlled
**Scenario:** Submit a Verify request with an ACH account configured to trigger a hard decline on routing number (RNV), account number (ANV), or name/address (NAV) validation. The request fails and no token is issued.
**Success criteria:** Verify response returns applicable decline status code; no token issued
**Key response fields to verify:**
| Scenario | Expected Status |
| ------------ | ----------------------------- |
| RNV Declined | `743` |
| ANV Declined | `767`, `768`, or `769` |
| NAV Declined | `776`, `777`, `778`, or `779` |
**Category:** Controlled
**Scenario:** Submit a Process request using a test account configured to trigger an OFAC hit. The initial Process response returns `status: 130` confirming OFAC suspension. After OFAC review, the transaction is cleared and payment completes.
**Success criteria:** Process response `status: 130`; suspended and cleared webhooks fire; payment ultimately succeeds
**Key response fields to verify:**
| Field | Expected |
| ---------------- | -------------------------- |
| `status` | `130` |
| `client_message` | `Success - OFAC Suspended` |
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------- | ------------------------------------------------------------------ | --------------- |
| 1 | OFAC Suspended | `gateway.transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Cleared | `gateway.transaction.recipient.verification.ofac.status.cleared` | 1107 |
**Category:** Controlled
**Scenario:** An OFAC suspension is reviewed and confirmed. The transaction is terminated.
**Success criteria:** Process response `status: 130`; suspended and failure webhooks fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------- | ------------------------------------------------------------------ | --------------- |
| 1 | OFAC Suspended | `gateway.transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Failure | `gateway.transaction.recipient.verification.ofac.status.failure` | 1108 |
Mocked response testing requires pre-loaded test accounts provisioned by your Ingo integration manager. These scenarios simulate issuer declines, application errors, and edge cases not reachable through standard sandbox requests.
**Category:** Controlled
**Scenario:** Submit Process requests using pre-loaded test accounts that simulate issuer decline conditions — insufficient funds, do not honor, invalid account, stolen card, restricted card, transaction limits, and other issuer-specific declines.
**Success criteria:** Appropriate decline status code returned for each scenario (`851`–`865` range)
**Category:** Controlled
**Scenario:** Submit Process requests using pre-loaded test accounts that simulate Ingo application error conditions — transaction failures, routing network errors, validation errors, and timeout scenarios.
**Success criteria:** Appropriate error status code returned for each scenario (`400`–`999` range)
**Category:** Controlled
**Scenario:** Submit Process requests that simulate a pending issuer response (`102`) or an idempotent in-progress state (`104`). Confirms your system handles non-terminal success states correctly.
**Success criteria:**
| Scenario | Expected Status |
| ----------------------------------- | --------------- |
| Pending issuer response | `102` |
| Idempotent — processing in progress | `104` |
Retail card-present scenarios apply only to clients configured for retail processing. Contact your integration manager to confirm your configuration before running these tests.
**Category:** Controlled
**Scenario:** Submit Process requests that exceed retail store-level velocity limits — max daily transaction amount and max daily transaction count per store.
**Success criteria:** Appropriate error response returned for each limit condition
**Category:** Controlled
**Scenario:** Submit a request for a transaction type not authorized for the store configuration.
**Success criteria:** Appropriate error response indicating unauthorized transaction type
**Category:** Controlled
**Scenario:** Submit a Process request that requires track data without providing it, or with invalid track1/track2 data. Confirms your system handles track data validation errors.
**Success criteria:** Appropriate error response for each track data condition
***
## Guided Scenarios
The following scenarios require coordination with your Ingo integration team. Contact your integration manager to schedule a guided session.
**Category:** Guided
**Scenario:** Submit a Process request for an account type your participant configuration does not permit.
**Success criteria:** Appropriate error response returned
**Category:** Guided
**Scenario:** Submit a Process request that fails due to insufficient funds in the issuer network.
**Success criteria:** Appropriate decline response returned
**Category:** Guided
**Scenario:** Submit a Process request for a destination that has been disabled.
**Success criteria:** Appropriate error response returned
**Category:** Guided
**Scenario:** Submit a Process request for an account that is no longer supported or whose token has expired.
**Success criteria:** Appropriate error response returned
**Category:** Guided
**Scenario:** A previously completed payment is returned by the issuer. Confirms your system correctly handles the returned payment webhook and updates your records.
**Success criteria:** Returned payment webhook received and processed correctly
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | ------------------------------------------------------- | --------------- |
| — | Payment Returned | `gateway.transaction.recipient.payment.status.returned` | 1114 |
***
## Webhook Events Reference
IngoPay API responses are synchronous — most results are returned directly in the API response. The following webhook events fire asynchronously for a small number of scenarios.
| Event | Topic | Expected Status |
| -------------- | ------------------------------------------------------------------ | --------------- |
| OFAC Suspended | `gateway.transaction.recipient.verification.ofac.status.suspended` | 1106 |
| OFAC Cleared | `gateway.transaction.recipient.verification.ofac.status.cleared` | 1107 |
| OFAC Failure | `gateway.transaction.recipient.verification.ofac.status.failure` | 1108 |
| Event | Topic | Expected Status |
| ---------------- | ------------------------------------------------------------- | --------------- |
| Payment Returned | `gateway.transaction.recipient.payment.status.returned` | 1114 |
| Check Issued | `gateway.transaction.recipient.payment.status.check.issued` | 100 |
| Check Paid | `gateway.transaction.recipient.payment.status.check.paid` | 100 |
| Check Canceled | `gateway.transaction.recipient.payment.status.check.canceled` | 100 |
| Check Stopped | `gateway.transaction.recipient.payment.status.check.stopped` | 100 |
| Check Returned | `gateway.transaction.recipient.status.payment.check.returned` | 1114 |
# Verify — ACH
Source: https://developers.ingopayments.com/docs/ingopay/verify/ach
specs/ingopay-verify-ach.yaml POST /gateway/verify--ach
Tokenize a bank account for Standard ACH or Same-Day ACH disbursements.
# Verify — BillPay
Source: https://developers.ingopayments.com/docs/ingopay/verify/billpay
specs/ingopay-verify-billpay.yaml POST /gateway/verify--billpay
Tokenize a biller account for BillPay push disbursements.
# Verify — Card
Source: https://developers.ingopayments.com/docs/ingopay/verify/card
specs/ingopay-verify-card.yaml POST /gateway/verify--card
Tokenize a debit or credit card account for future push-to-card disbursements.
# Verify — Check by Mail
Source: https://developers.ingopayments.com/docs/ingopay/verify/check
specs/ingopay-verify-check.yaml POST /gateway/verify--check
Tokenize a recipient address for check by mail disbursements.
# Tokenize via Open Banking
Source: https://developers.ingopayments.com/docs/ingopay/verify/open-banking
specs/ingopay-verify-open-banking.yaml POST /gateway/verify--open-banking
Tokenize an account using open banking account data for use in subsequent Process requests.
**Under Development — Coming Soon.** This endpoint is currently under development and is not yet available for integration. Specifications are subject to change prior to general availability. Contact your Ingo integration manager for availability updates.
# Verify — PayPal / Venmo
Source: https://developers.ingopayments.com/docs/ingopay/verify/paypal-venmo
specs/ingopay-verify-paypal-venmo.yaml POST /gateway/verify--paypal-venmo
Tokenize a PayPal or Venmo account for push disbursements.
# Verify — Retail Card Present
Source: https://developers.ingopayments.com/docs/ingopay/verify/retail-card-present
specs/ingopay-verify-retail-card-present.yaml POST /gateway/verify--retail
Account tokenization for retail card-present configurations.
# Tokenize a Wire Transfer Account
Source: https://developers.ingopayments.com/docs/ingopay/verify/wire
specs/ingopay-verify-wire.yaml POST /gateway/verify--wire
Validate and tokenize a wire transfer account for use in subsequent Debit requests.
**Under Development — Coming Soon.** This endpoint is currently under development and is not yet available for integration. Specifications are subject to change prior to general availability. Contact your Ingo integration manager for availability updates.
# Webhooks
Source: https://developers.ingopayments.com/docs/ingopay/webhooks/overview
Post-transaction event notifications for IngoPay — check lifecycle, payment exceptions, and compliance status changes.
IngoPay fires server-side webhooks for asynchronous events that occur after a transaction is submitted.
# Cancel Disbursement
Source: https://developers.ingopayments.com/docs/notify-classic/notify/cancel
specs/ingopay-notify-v3.yaml POST /gateway/v3/notifycancel
Cancel a staged disbursement that has not yet been claimed by the recipient.
# Stage Disbursement
Source: https://developers.ingopayments.com/docs/notify-classic/notify/stage
specs/ingopay-notify-v3.yaml POST /gateway/v3/notify
Stage a disbursement notification for a single recipient via Notify v3.
# Notify — Classic
Source: https://developers.ingopayments.com/docs/notify-classic/overview
Managed single-recipient disbursement engagement. One API call triggers the full lifecycle — recipient notification, identity verification, compliance screening, payment selection, and delivery.
Ingo Payments · Notify — Classic
Notify once. Recipients choose. Ingo delivers.
One API call. Fully managed recipient engagement from notification to funded.
Notify — Classic is a fully managed disbursement engagement product. You submit a single API call with the recipient's details and disbursement intent — Ingo handles everything that follows. Ingo notifies the recipient, verifies their identity, runs OFAC and compliance screening, presents the payment options you have configured for your program, tokenizes their chosen account, and delivers the funds. You receive real-time webhook updates at every stage. Your integration scope is two endpoints: one to stage the notification, and one to cancel it if needed before the recipient has claimed.
The payment options presented to a recipient are determined entirely by your program configuration. You elect which payment types to support — card, ACH, check, PayPal, Venmo — and optionally set amount-based thresholds for each. When a disbursement is staged, Ingo automatically filters the available options to only those your program supports at or above the transaction amount, ensuring recipients are only shown choices that are valid for their specific disbursement.
**SMS delivery options** — Notify can send recipient notifications via SMS through Ingo-managed delivery or through your own SMS infrastructure. With Ingo-managed SMS, Ingo sends directly to recipients and manages consent collection — though notifications identify Ingo as the sender rather than your brand. Many clients integrate their own SMS platform for full brand control, directing recipients to the Ingo-hosted disbursement URL. Both approaches are supported. See [Custom Domain & DNS Setup](/docs/hub/domain-setup#sms-delivery-options) for details, or ask your Integration Manager which approach fits your program.
***
## How It Works
You stage a notification with recipient details and disbursement amount. Ingo
immediately contacts the recipient via SMS and email with a secure, branded
prompt to claim their funds — no recipient-facing UI for you to build or host.
As the recipient engages, Ingo automatically performs identity verification and
OFAC screening based on your configured risk profile. Approved recipients proceed
to payment selection; flagged transactions are held and surfaced via webhook for
your review.
The recipient selects their preferred payment method from the options your program
has enabled. Amount-based thresholds are enforced automatically — payment types
below your configured limits for the disbursement amount are not presented,
ensuring every selection is within your approved parameters.
Ingo processes the payment to the recipient's chosen account and posts real-time
webhook events to your endpoint at every status change — from notification sent
through identity screening, account tokenization, and final payment confirmation.
***
## API Reference
Notify — Classic exposes two endpoints. Stage initiates the full managed lifecycle;
Cancel terminates it at any point before the recipient has claimed the disbursement.
Submit a recipient notification and disbursement intent. Ingo immediately begins
the managed engagement lifecycle on your behalf.
Cancel a previously staged notification before the recipient has claimed their
disbursement. Once claimed, cancellation is no longer available.
***
**Notify — Managed Parties** builds on everything in Classic and adds full party
orchestration across recipients, approvers, and joint recipients — with role
delegation and engagement lifecycle management. It supports single-recipient
disbursements as well, making it the preferred choice for new integrations.
# Quick Start
Source: https://developers.ingopayments.com/docs/notify-classic/quick-start
Stage your first Notify — Classic disbursement and handle the recipient engagement webhooks.
This guide walks through the complete Notify — Classic flow: signing a request, staging a disbursement notification, and handling the webhook events Ingo posts as the recipient engages. Unlike a direct API integration where the synchronous response carries the final outcome, Notify is primarily an async product — you stage a notification and then listen for webhooks to know what's happening.
You'll need your **username**, **secret**, and **participant\_id** to follow this guide. These are issued by your Ingo integration manager during onboarding.
***
## Environments
| Environment | Base URL |
| ----------- | ----------------------------------- |
| Sandbox | `https://payapi-sandbox.ingo.money` |
| Production | `https://payapi.ingo.money` |
***
All Notify — Classic requests use the same **HMAC-SHA512** signing as every other Ingo API. Build the `X-Date`, `Content-sha512`, `Content-Length`, and `Content-Type` headers, then assemble the `Authorization` header before sending.
See [Authentication](/docs/notify-classic/authentication) for the full construction guide.
Use **RAW** (binary) output from your HMAC library before Base64 encoding — not hex. Base64-encoding hex output produces an incorrect signature and a `401 Unauthorized` response.
A single `POST /gateway/v3/notify` call submits the recipient's details, the disbursement amount, and the identity challenge your program uses to verify the recipient. Ingo immediately notifies the recipient via email and SMS.
```http theme={null}
POST /gateway/v3/notify HTTP/1.1
Host: payapi-sandbox.ingo.money
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="hAMqhSX6eogO1QpES9Dg9..."
X-Date: Fri, 17 Jan 2020 19:59:29 GMT
Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08=
Content-Length: 512
Content-Type: application/json
{
"participant_id": 12345,
"amount": "250.00",
"workflow_id": 1,
"participant_unique_id1": "a4f1b2c3-d456-789e-f012-34567890abcd",
"recipient": {
"customer_id": "cust-001",
"first_name": "Alex",
"last_name": "Rivera",
"email": "alex.rivera@example.com",
"mobile": "5555550100",
"address1": "100 Innovation Way",
"city": "Anytown",
"state": "GA",
"zip": "00000"
},
"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"
}
]
}
```
A successful staging response returns a `notification_id` you can use to reference this transaction:
```json theme={null}
{
"status": 100,
"client_message": "Success",
"data": {
"notification_id": 9876543,
"tracer_id": "trc-20260422-001"
}
}
```
The `status: 100` response confirms the notification was **staged** — not that the recipient has been paid. The disbursement lifecycle continues asynchronously via webhooks.
After staging, Ingo posts webhook events to your configured endpoint as the recipient moves through the engagement flow. Your system needs to handle these events to track transaction status accurately.
Key events to handle in order:
| Event | Meaning |
| ----------------------------------------------------- | ------------------------------------------------------ |
| `transaction.recipient.notification.sent` | Recipient has been notified via email/SMS |
| `transaction.recipient.authentication.complete` | Recipient passed identity verification |
| `transaction.recipient.payment.tokenization.complete` | Recipient selected a payment method; account tokenized |
| `transaction.recipient.payment.status.approved` | Disbursement approved and submitted for processing |
| `transaction.recipient.payment.status.funded` | Funds delivered to recipient |
See [Webhooks](/docs/notify-classic/webhooks/overview) for the full event reference and payload schemas.
Do not treat the synchronous `status: 100` response as payment confirmation. Always rely on webhook events for authoritative transaction status.
If you need to stop a staged notification before the recipient has claimed their disbursement, send a cancel request with the `notification_id` returned at staging.
```http theme={null}
POST /gateway/v3/notifycancel HTTP/1.1
Host: payapi-sandbox.ingo.money
Authorization: hmac username="test", ...
Content-Type: application/json
{
"participant_id": 12345,
"notification_id": 9876543
}
```
Once a recipient has claimed and selected a payment method, cancellation is no longer available. See [Notify — Cancel](/docs/notify-classic/notify/cancel) for the full field reference.
***
## What's next
Full HMAC-SHA512 construction guide, header reference, and common signing errors.
Complete field reference for the stage endpoint.
All webhook event types, payload schemas, and signature verification.
Add multi-party orchestration and approval gating to your disbursement flow.
# Testing
Source: https://developers.ingopayments.com/docs/notify-classic/testing
Scenario-based testing guide for Notify Classic single-party staged disbursements, recipient authentication, and webhook event verification.
## Sandbox Environment
Your sandbox mirrors production behavior including payment routing logic, OFAC screening, account verification services, and webhook delivery. Sandbox credentials and velocity limits are provisioned during onboarding.
Sandbox velocity limits are client-specific and configured by your Ingo integration manager during onboarding.
***
## Test Categories
| Category | Description | How to initiate |
| ---------------- | ----------------------------------------------------------- | -------------------------------------------- |
| **Self-Service** | Complete independently in the sandbox at your own pace | Your sandbox credentials |
| **Controlled** | Requires an enablement flag set by your integration manager | Contact your integration manager to schedule |
| **Guided** | Live session with your Ingo integration team recommended | Contact your integration manager to schedule |
***
## Understanding Soft Failures
**Soft failure** — A partial match that does not stop the flow. The recipient experiences no interruption and proceeds transparently. Your system is notified of the result in the background via the correlated **success** webhook carrying the soft-fail status code. No failure webhook emits.
**Hard failure** — A mismatch on a field your configuration has designated as requiring a hard failure. How each verification field’s mismatch is treated is defined during your implementation setup via the configuration form. When a hard failure occurs, the recipient is stopped and must retry. If maximum attempts are exhausted, the session or transaction terminates.
***
## Self-Service Scenarios
**Category:** Self-Service
**Scenario:** Stage a transaction via the Notify API. The recipient receives the notification email and it is delivered successfully.
**Success criteria:** Notification sent and received events fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------------- | ---------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
**Category:** Self-Service
**Scenario:** Stage a transaction using an invalid email address. Confirms your system handles undeliverable notification events.
**Success criteria:** Bounce event received
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | --------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Bounced | `transaction.recipient.notification.status.bounced` | 1200 series |
**Category:** Self-Service
**Scenario:** Resubmit an identical Notify API request using the same `participant_unique_id1`. Confirms duplicate protection is working correctly.
**Success criteria:** Response `status: 101` — no new transaction created
**Category:** Self-Service
**Scenario:** Stage a transaction. Submit a Notify Cancel request before the recipient completes the flow. Confirms cancellation before disbursement selection.
**Success criteria:** Disbursement canceled event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------------- | ------------------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Disbursement Canceled | `transaction.recipient.payment.disbursement.request.canceled` | 1110 |
**Category:** Self-Service
**Scenario:** Attempt to cancel a transaction in a state that does not permit cancellation — already completed, already canceled, already expired, or invalid notification ID. Confirms your system handles cancel error responses gracefully.
**Success criteria:** Appropriate error status returned for each invalid state
**Category:** Self-Service
**Scenario:** Stage a transaction. Allow the notification to expire without recipient action.
**Success criteria:** Disbursement expired event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | ------------------------------------------------------------ | --------------- |
| — | Disbursement Expired | `transaction.recipient.payment.disbursement.request.expired` | 1109 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete the authentication flow in a way that causes the transaction to reach a terminal failure state.
**Success criteria:** Payment terminated event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | ------------------------------------------------- | --------------- |
| — | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 or 1132 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Open the notification and complete the authentication challenge with fully matching data. Recipient proceeds to disbursement selection.
**Success criteria:** Authentication success event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1100 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Enter partially matching authentication data. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial match in the background via the authentication success webhook carrying the soft-fail status code.
**Success criteria:** Authentication success fires with soft-fail status code; recipient proceeds uninterrupted
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | ---------------------------- | ----------------------------------------------------- | --------------- |
| 1–2 | Notification Sent / Received | *(as above)* | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1101 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Provide non-matching authentication data. The recipient is stopped and must retry. Confirms hard failure handling.
**Success criteria:** Authentication failure event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | ---------------------------- | ----------------------------------------------------- | --------------- |
| 1–2 | Notification Sent / Received | *(as above)* | 1200 series |
| 3 | Authentication Failure | `transaction.recipient.authentication.status.failure` | 1102 |
**Category:** Self-Service
**Scenario:** Provide non-matching authentication data until maximum attempts are exhausted. Transaction terminates.
**Success criteria:** Authentication failure fires, overall failure fires, transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------- |
| — | Authentication Failure | `transaction.recipient.authentication.status.failure` | 1102 |
| — | Overall Auth Failure | `transaction.party.authentication.overall.failure` | 1161 |
| — | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Self-Service
**Scenario:** Stage a transaction with RVDM enabled. Complete authentication. Provide recipient information that fully matches the session data.
**Success criteria:** RVDM success event fires, flow continues to account selection
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ------------------------------------------------- | --------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1103 |
**Category:** Self-Service
**Scenario:** Provide partially matching recipient data. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial match in the background via the RVDM success webhook carrying the soft-fail status code.
**Success criteria:** RVDM success fires with soft-fail status code; recipient proceeds uninterrupted
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ------------------------------------------------- | --------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1104 |
**Category:** Self-Service
**Scenario:** Provide non-matching recipient data until maximum attempts are exhausted. Transaction terminates.
**Success criteria:** RVDM failure fires, transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ------------------------------------------------- | --------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | RVDM Failure | `transaction.recipient.verification.rvdm.failure` | 1105 |
| 5 | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete authentication and RVDM. Select card disbursement, tokenize a valid test card, and complete the payment.
**Success criteria:** Tokenization and payment success events fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | --------------------------------- | ---------------------------------------------- | --------------- |
| 1–4 | Notification / Auth / RVDM events | *(as above)* | — |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1125 |
**Category:** Self-Service
**Scenario:** Stage a second card transaction for a recipient with a previously tokenized account. Completes using the existing token without re-entering card details.
**Success criteria:** Payment completes using stored token
**Category:** Self-Service
**Scenario:** Enter a card account number not supported for disbursement. The recipient is stopped and must use a different account. Your system is notified via the CNS/CD failure webhook.
**Success criteria:** CNS/CD failure event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------- | ------------------------------------------------------ | --------------- |
| — | CNS/CD Failure | `transaction.account.verification.card.failure.cns_cd` | 700 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete authentication and RVDM. Select ACH disbursement, enter a valid test routing and account number, and complete the payment.
**Success criteria:** Tokenization and payment success events fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | --------------------------------- | ---------------------------------------------- | --------------- |
| 1–4 | Notification / Auth / RVDM events | *(as above)* | — |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1126 |
**Category:** Self-Service
**Scenario:** Stage a second ACH transaction for a recipient with a previously registered account. Completes using the existing token.
**Success criteria:** Payment completes using stored token
**Category:** Self-Service
**Scenario:** Stage an ACH transaction. Provide non-matching session recipient information during account entry. Confirms hard failure stops the flow before tokenization.
**Success criteria:** RVDM failure fires; no tokenization
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------ | ------------------------------------------------- | --------------- |
| — | RVDM Failure | `transaction.recipient.verification.rvdm.failure` | 1105 |
**Category:** Self-Service
**Scenario:** Provide non-matching session recipient information repeatedly until the session terminates.
**Success criteria:** Session terminated event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | ----------------------------------------------- | --------------- |
| — | Session Terminated | `plugin.transaction.session.request.terminated` | 1127 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete authentication and RVDM. Select PayPal disbursement. PayPal Account Verification (AV) runs as the PayPal-specific account check. The AV result notifies your system in the background. The account is tokenized and payment completes.
**Success criteria:** RVDM success, PayPal AV success, tokenization success, and payment success all fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1100 or 1101 |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1103 or 1104 |
| 5 | PayPal AV Success | `transaction.account.verification.paypal.success.av` | 1148 |
| 6 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 7 | Payment Success | `transaction.recipient.payment.status.success` | 1134 |
**Category:** Self-Service
**Scenario:** Stage a PayPal transaction. Provide partially matching session recipient data. The recipient experiences no interruption. Your system is notified of the partial RVDM match in the background via the RVDM success webhook. The flow continues to PayPal AV and tokenization.
**Success criteria:** RVDM success fires with soft-fail code; PayPal flow continues; payment completes
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ---------------------------------------------------- | --------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1104 |
| 5 | PayPal AV Success | `transaction.account.verification.paypal.success.av` | 1148 |
| 6 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 7 | Payment Success | `transaction.recipient.payment.status.success` | 1134 |
**Category:** Self-Service
**Scenario:** Stage a PayPal transaction. Provide non-matching session recipient data. The RVDM hard failure stops the flow before PayPal AV or tokenization.
**Success criteria:** RVDM failure fires; no PayPal AV or tokenization
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------ | ------------------------------------------------- | --------------- |
| — | RVDM Failure | `transaction.recipient.verification.rvdm.failure` | 1105 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete the full flow. Recipient elects check. Client issues the check.
**Success criteria:** Check in process event fires confirming the recipient elected check
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | -------------------------------------------- | --------------- |
| — | Check In Process | `transaction.recipient.payment.status.check` | 1111 or 1112 |
**Category:** Self-Service
**Scenario:** Stage a check transaction. Recipient selects check but does not confirm the address on file.
**Success criteria:** Check in process event fires with address-not-confirmed status code
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | -------------------------------------------- | --------------- |
| — | Check In Process | `transaction.recipient.payment.status.check` | 1112 |
**Category:** Self-Service
**Scenario:** Stage a Client Issuance check transaction. Allow the notification to expire without recipient action. The disbursement request expires and the transaction terminates.
**Success criteria:** Expired event fires; transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | ------------------------------------------------------------ | --------------- |
| 1 | Disbursement Expired | `transaction.recipient.payment.disbursement.request.expired` | 1109 |
| 2 | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Self-Service
**Scenario:** Stage an Ingo Issuance check transaction. Allow the notification to expire without recipient action. Ingo defaults to issuing the check — the payment succeeds and the check is issued and subsequently paid.
**Success criteria:** Payment success fires, followed by check issued and check paid events
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | --------------------------------------------------- | --------------- |
| 1 | Payment Success | `transaction.recipient.payment.status.success` | 1133 |
| 2 | Check Issued | `transaction.recipient.payment.status.check.issued` | 100 |
| 3 | Check Paid | `transaction.recipient.payment.status.check.paid` | 100 |
**Category:** Self-Service
**Scenario:** Stage a transaction configured for Ingo check issuance. Complete the full flow. Ingo issues the check and it is subsequently paid.
**Success criteria:** Payment success, check issued, and check paid events all fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | --------------------------------------------------- | --------------- |
| 1 | Payment Success | `transaction.recipient.payment.status.success` | 1133 |
| 2 | Check Issued | `transaction.recipient.payment.status.check.issued` | 100 |
| 3 | Check Paid | `transaction.recipient.payment.status.check.paid` | 100 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete authentication and have the recipient elect to cancel the disbursement from within the iFrame.
**Success criteria:** Recipient cancel event fires, transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | -------------------------------------------------------------- | --------------- |
| — | Recipient Cancel | `transaction.recipient.payment.notice.status.recipient.cancel` | 1139 |
| — | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
***
## Controlled Scenarios
The following scenarios require your Ingo integration manager to enable a specific configuration before testing can begin. Contact your integration team to schedule these.
OTAC is a configurable authentication method where a one-time code is delivered to the recipient's mobile number during the authentication flow. The following scenarios require OTAC to be enabled in your sandbox configuration.
**Category:** Controlled
**Scenario:** Stage a transaction with OTAC enabled. Complete the RA challenge. Receive the OTAC code on the registered mobile number and enter it correctly. Authentication completes successfully.
**Success criteria:** OTAC generate, validation success, and overall auth success events all fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | ---------------------------- | ---------------------------------------------------------- | --------------- |
| 1–2 | Notification Sent / Received | *(as above)* | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1100 or 1101 |
| 4 | OTAC Generated | `transaction.party.authentication.otac.delivery.generate` | 1153 or 1154 |
| 5 | OTAC Validation Success | `transaction.party.authentication.otac.validation.success` | 1150 |
| 6 | Overall Auth Success | `transaction.party.authentication.overall.success` | 1160 |
**Category:** Controlled
**Scenario:** Enter an incorrect OTAC code. The recipient is stopped and may retry. Confirms validation failure handling.
**Success criteria:** OTAC validation failure event fires; retry permitted
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ----------------------- | ---------------------------------------------------------- | --------------- |
| — | OTAC Generated | `transaction.party.authentication.otac.delivery.generate` | 1153 or 1154 |
| — | OTAC Validation Failure | `transaction.party.authentication.otac.validation.failure` | 1152 |
**Category:** Controlled
**Scenario:** Enter incorrect OTAC codes until maximum attempts are exhausted. Transaction terminates.
**Success criteria:** OTAC validation failure fires repeatedly; overall auth failure fires; transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ----------------------- | ---------------------------------------------------------- | --------------- |
| — | OTAC Validation Failure | `transaction.party.authentication.otac.validation.failure` | 1152 |
| — | Overall Auth Failure | `transaction.party.authentication.overall.failure` | 1161 |
| — | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Controlled
**Scenario:** Request OTAC code delivery repeatedly until the send limit is reached. Confirms your system handles the send limit event.
**Success criteria:** OTAC delivery limit event fires; overall auth failure fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | ------------------------------------------------------ | --------------- |
| — | OTAC Send Limit | `transaction.party.authentication.otac.delivery.limit` | 1151 |
| — | Overall Auth Failure | `transaction.party.authentication.overall.failure` | 1162 |
**Category:** Controlled
**Scenario:** OTAC cannot be delivered or accessed (e.g., no mobile number available). Transaction terminates.
**Success criteria:** Overall auth failure fires with inaccessible status; transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | -------------------------------------------------- | --------------- |
| — | Overall Auth Failure | `transaction.party.authentication.overall.failure` | 1163 |
| — | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Controlled
**Scenario:** A card account tokenization where the AVS check returns a soft failure. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial address match in the background via the tokenization success webhook carrying the soft-fail status code.
**Success criteria:** Tokenization success fires with AVS soft-fail status code; payment completes
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | --------------------------------- | ---------------------------------------------- | --------------- |
| 1–4 | Notification / Auth / RVDM events | *(as above)* | — |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | 111–119 range |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1125 |
**Category:** Controlled
**Scenario:** A card account tokenization where the AVS check returns a hard decline. The recipient is stopped and must use a different account. Your system is notified via the AVS/CVV failure webhook.
**Success criteria:** AVS/CVV failure event fires; account rejected
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | ------------------------------------------------------- | --------------- |
| — | AVS/CVV Failure | `transaction.account.verification.card.failure.avs_cvv` | 753–759 range |
**Category:** Controlled
**Scenario:** A card account tokenization where the CVV check returns a hard decline. Your system is notified via the AVS/CVV failure webhook.
**Success criteria:** AVS/CVV failure event fires; account rejected
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | ------------------------------------------------------- | --------------- |
| — | AVS/CVV Failure | `transaction.account.verification.card.failure.avs_cvv` | — |
**Category:** Controlled
**Scenario:** An ACH account verification returns a soft failure on account number validation (ANV) or name/address validation (NAV). The recipient experiences no interruption. Your system is notified of the partial match in the background via the tokenization success webhook carrying the soft-fail status code.
**Success criteria:** Tokenization success fires with soft-fail status code; payment completes
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1100 or 1101 |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1103 or 1104 |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | Soft-fail status code |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1126 |
**Category:** Controlled
**Scenario:** ACH account verification returns a hard decline on routing number, account number, or name/address validation. The recipient is stopped and must use a different account. Your system is notified via the appropriate failure webhook.
**Success criteria:** Applicable failure event fires; account rejected
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | -------------------------------------------------- | --------------- |
| — | RNV Failure | `transaction.account.verification.ach.failure.rnv` | 743 |
| — | *or* ANV Failure | `transaction.account.verification.ach.failure.anv` | 767–769 |
| — | *or* NAV Failure | `transaction.account.verification.ach.failure.nav` | 776–778 |
**Category:** Controlled
**Scenario:** PayPal account verification returns a partial match. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial match in the background via the PayPal AV success webhook carrying the soft-fail status code. The account is tokenized and payment completes.
**Success criteria:** PayPal AV success fires with soft-fail status code; tokenization and payment success follow
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | --------------------------------- | ---------------------------------------------------- | --------------------- |
| 1–4 | Notification / Auth / RVDM events | *(as above)* | — |
| 5 | PayPal AV Success | `transaction.account.verification.paypal.success.av` | Soft-fail status code |
| 6 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 7 | Payment Success | `transaction.recipient.payment.status.success` | 1134 |
**Category:** Controlled
**Scenario:** PayPal account verification returns a hard failure. The recipient is stopped and must retry. If maximum attempts are reached, the transaction terminates.
**Success criteria:** PayPal AV failure fires; termination event fires after max attempts
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| ----- | ------------------ | ---------------------------------------------------- | --------------- |
| — | PayPal AV Failure | `transaction.account.verification.paypal.failure.av` | 1150 |
| Final | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Controlled
**Scenario:** A staged transaction triggers an OFAC hit during the disbursement flow. The payment is suspended. After OFAC review, the transaction is cleared and payment completes.
**Success criteria:** Suspended and cleared events both fire; payment ultimately succeeds
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | ---------------------------------------------------------- | --------------- |
| 1 | OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Cleared | `transaction.recipient.verification.ofac.status.cleared` | 1107 |
| 3 | Payment Success | `transaction.recipient.payment.status.success` | 1125–1134 |
**Category:** Controlled
**Scenario:** An OFAC suspension is reviewed and cleared, but payment is subsequently declined by the network.
**Success criteria:** Suspended and cleared events fire; payment failure fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | ---------------------------------------------------------- | --------------- |
| 1 | OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Cleared | `transaction.recipient.verification.ofac.status.cleared` | 1107 |
| 3 | Payment Failure | `transaction.recipient.payment.status.failure` | — |
**Category:** Controlled
**Scenario:** An OFAC suspension is reviewed and confirmed. The transaction is terminated.
**Success criteria:** Suspended and failure events fire; transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | ---------------------------------------------------------- | --------------- |
| 1 | OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Failure | `transaction.recipient.verification.ofac.status.failure` | 1108 |
| 3 | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
***
## Guided Scenarios
The following scenarios involve coordination with your Ingo integration team. Contact your integration manager to schedule a guided session.
**Category:** Guided
**Scenario:** A previously completed payment is returned by the account issuer. Confirms your system correctly handles the returned status.
**Success criteria:** Returned event received and processed correctly
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | ----------------------------------------------- | --------------- |
| — | Payment Returned | `transaction.recipient.payment.status.returned` | 1114 |
***
## Webhook Events Reference
| Event | Topic | Expected Status |
| --------------------- | ---------------------------------------------------- | --------------- |
| Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| Notification Bounced | `transaction.recipient.notification.status.bounced` | 1200 series |
| Event | Topic | Expected Status |
| ----------------------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
| Auth Success | `transaction.recipient.authentication.status.success` | 1100 (full), 1101 (soft fail) |
| Auth Failure | `transaction.recipient.authentication.status.failure` | 1102 |
| OTAC Generated | `transaction.party.authentication.otac.delivery.generate` | 1153 (SMS), 1154 (email) |
| OTAC Send Limit | `transaction.party.authentication.otac.delivery.limit` | 1151 |
| OTAC Validation Success | `transaction.party.authentication.otac.validation.success` | 1150 |
| OTAC Validation Failure | `transaction.party.authentication.otac.validation.failure` | 1152 |
| Overall Auth Success | `transaction.party.authentication.overall.success` | 1160 |
| Overall Auth Failure | `transaction.party.authentication.overall.failure` | 1161 (max attempts), 1162 (send limit), 1163 (inaccessible) |
| Event | Topic | Expected Status |
| -------------- | ---------------------------------------------------------- | ----------------------------- |
| RVDM Success | `transaction.recipient.verification.rvdm.success` | 1103 (full), 1104 (soft fail) |
| RVDM Failure | `transaction.recipient.verification.rvdm.failure` | 1105 |
| OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| OFAC Cleared | `transaction.recipient.verification.ofac.status.cleared` | 1107 |
| OFAC Failure | `transaction.recipient.verification.ofac.status.failure` | 1108 |
| Event | Topic | Expected Status |
| -------------------- | ------------------------------------------------------- | ----------------------------------- |
| Card CNS/CD Failure | `transaction.account.verification.card.failure.cns_cd` | 700 |
| Card AVS/CVV Failure | `transaction.account.verification.card.failure.avs_cvv` | 753–759 |
| ACH RNV Failure | `transaction.account.verification.ach.failure.rnv` | 743 |
| ACH ANV Failure | `transaction.account.verification.ach.failure.anv` | 767–769 |
| ACH NAV Failure | `transaction.account.verification.ach.failure.nav` | 776–778 |
| PayPal AV Failure | `transaction.account.verification.paypal.failure.av` | 1150 |
| PayPal AV Success | `transaction.account.verification.paypal.success.av` | 1148 |
| Tokenization Success | `transaction.account.tokenization.success` | 100 (full), 111–119 (AVS soft fail) |
| Event | Topic | Expected Status |
| ------------------------ | -------------------------------------------------------------- | --------------- |
| Payment Success — Card | `transaction.recipient.payment.status.success` | 1125 |
| Payment Success — ACH | `transaction.recipient.payment.status.success` | 1126 |
| Payment Success — Check | `transaction.recipient.payment.status.success` | 1133 |
| Payment Success — PayPal | `transaction.recipient.payment.status.success` | 1134 |
| Payment Failure | `transaction.recipient.payment.status.failure` | varies |
| Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113, 1132 |
| Payment Returned | `transaction.recipient.payment.status.returned` | 1114 |
| Disbursement Expired | `transaction.recipient.payment.disbursement.request.expired` | 1109 |
| Disbursement Canceled | `transaction.recipient.payment.disbursement.request.canceled` | 1110 |
| Recipient Cancel | `transaction.recipient.payment.notice.status.recipient.cancel` | 1139 |
| Check In Process | `transaction.recipient.payment.status.check` | 1111, 1112 |
| Check Issued | `transaction.recipient.payment.status.check.issued` | 100 |
| Check Paid | `transaction.recipient.payment.status.check.paid` | 100 |
| Check Returned | `transaction.recipient.payment.status.check.returned` | 1114 |
# Webhooks
Source: https://developers.ingopayments.com/docs/notify-classic/webhooks/overview
Event notifications for Notify — Classic disbursements — notification delivery, authentication, verification, tokenization, and payment status.
Notify — Classic is an async-first product. The synchronous stage response confirms the notification was accepted; every subsequent lifecycle event — from the moment Ingo contacts the recipient through to funded — is delivered via webhook. Your integration should be built around these events rather than polling.
Webhooks are delivered as JSON via HTTP POST to your registered endpoint. Return any `2xx` status to acknowledge receipt. See [Webhooks](/docs/hub/webhooks) for endpoint requirements, IP allowlist, and retry behavior.
***
## Event categories
| Category | What it covers |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Recipient Notification** | Notification sent, received by the recipient, and bounced (undeliverable) |
| **Party Authentication** | Identity challenge success and failure |
| **Recipient Verification** | RVDM identity matching outcomes and OFAC screening results |
| **Account Verification** | Card (CNS/CD, AVS/CVV), ACH (RNV, ANV, NAV), and PayPal verification outcomes |
| **Account Tokenization** | Successful account tokenization — includes the `customer_account_token` |
| **Payment Status** | Check issued, paid, canceled, stopped, and returned; payment success, failure, and return; disbursement expiry and cancellation |
***
## Lifecycle order
A typical single-recipient disbursement produces events in this sequence:
1. `transaction.recipient.notification.status.sent`
2. `transaction.recipient.notification.status.received`
3. `transaction.recipient.authentication.status.success`
4. `transaction.recipient.verification.rvdm.success` *(if RVDM is configured)*
5. `transaction.account.tokenization.success`
6. `transaction.recipient.payment.status.success` *(or payment-type-specific variant)*
Verification and account verification events appear between steps 3 and 5 depending on your configured risk controls. Not all events are guaranteed to fire for every transaction — your integration should handle any subset gracefully.
***
## Event reference
Full event catalog — payload schemas, field definitions, and examples for every Notify — Classic webhook event.
# Notification Types
Source: https://developers.ingopayments.com/docs/notify-managed/notification-types
The four notify_type values and when to use each — from standard one-time disbursements to recurring enrollment and payment flows.
The `notify_type` field in the v4 stage request controls the lifecycle mode of the notification. It determines whether the staged event triggers a disbursement, an enrollment experience, or both — and whether the recipient is new to the platform or already enrolled from a prior interaction.
Selecting the right notification type is the primary architectural decision for programs that intend to support recurring payments or standalone account capture.
***
## Type 0 — Standard Disbursement
**Available now.** This is the only notification type currently available for integration.
The standard one-time disbursement. Ingo notifies the recipient, runs identity and OFAC screening, presents the payment options your program has configured, tokenizes the chosen account, and processes the payment — all from a single staged notification. Multi-party orchestration (approvers and interested parties) is fully supported within this notification type.
**Use when:** You have a disbursement amount ready to send and want the recipient to select their preferred payment method. This covers the vast majority of disbursement use cases.
```json theme={null}
"notify_type": 0
```
***
## Type 1 — Enrollment Only
In Development — Not yet available for integration
Collect a recipient's payment preferences without staging a disbursement. The fully hosted experience presents your configured payment options through the Embedded Account Capture interface. On completion, Ingo returns a `customer_account_token` tied to the recipient's chosen account — no disbursement is triggered. The token can then be used with `notify_type: 2` for any number of future disbursements without repeating the enrollment experience.
**Use when:** You want to onboard recipients proactively — collecting payment preferences before a disbursement event occurs — so payments can be issued immediately when the time comes without putting the recipient through account capture at the point of payment.
**Common programs:** Earned wage access pre-enrollment, insurance claim pre-authorization, payroll onboarding, recurring benefits programs.
```json theme={null}
"notify_type": 1
```
***
## Type 2 — Disbursement Only (Enrolled Party)
In Development — Not yet available for integration
Stage a disbursement against a recipient who is already enrolled. Rather than presenting the full payment selection experience again, Ingo uses the `party_id` from the prior enrollment to route the payment to the recipient's established account. The recipient is notified that a payment is on the way without being asked to re-select a payment method.
**Use when:** You have previously enrolled a recipient via `notify_type: 1` or `notify_type: 3` and are now issuing a recurring or subsequent payment to the same account.
**Requires:** A valid `party_id` from a prior enrollment. Pass this in the `settings.party_id` field rather than `settings.client_provided_id`.
```json theme={null}
"notify_type": 2
```
***
## Type 3 — Enrollment + Disbursement
In Development — Not yet available for integration
Combines enrollment and disbursement in a single notification. The recipient selects a payment method through the hosted experience and, upon completion, the disbursement is immediately processed to their chosen account. Ingo returns both a `customer_account_token` and a completed payment — the account is enrolled for future use automatically.
**Use when:** You want to issue a first-time payment and establish the recipient's account preferences in a single interaction, so future payments can use `notify_type: 2` without a separate enrollment step.
**Common programs:** First-payment-plus-enrollment flows, benefits onboarding with immediate disbursement, insurance first-claim settlement.
```json theme={null}
"notify_type": 3
```
***
## Let us know what you need
Notification types 1, 2, and 3 are in development with no current release timeline. Client demand is a direct input into prioritization. If enrollment-only or recurring disbursement flows are important to your program, reach out to your integration manager — your input helps shape the roadmap.
# Cancel Disbursement
Source: https://developers.ingopayments.com/docs/notify-managed/notify/cancel
specs/ingopay-notify-v3.yaml POST /gateway/v3/notifycancel
Cancel a staged Notify — Managed Parties disbursement that has not yet been claimed by the recipient.
# Stage Disbursement
Source: https://developers.ingopayments.com/docs/notify-managed/notify/stage
specs/ingopay-notify-v4.yaml POST /gateway/v4/notify
Stage a disbursement with one or more parties via Notify v4.
# Notify — Managed Parties
Source: https://developers.ingopayments.com/docs/notify-managed/overview
Single and multi-party disbursement orchestration. One API call manages the full lifecycle — notification, approval gating, identity verification, compliance screening, and delivery.
Ingo Payments · Notify — Managed Parties
One call. Every step managed.
Single and multi-party. Fully orchestrated from notification through approval and delivery.
Notify — Managed Parties is the preferred integration for all new programs. It delivers the complete managed disbursement lifecycle from a single API call — recipient notification, identity verification, OFAC screening, client-configured payment selection with amount-based thresholds, and real-time webhook updates at every stage. Standard single-recipient disbursements are fully supported, and multi-party orchestration is available today for programs that require approval gating or interested party visibility within the standard disbursement flow. Additional notification types — including standalone enrollment and recurring disbursement flows — are on the roadmap and will be prioritized based on client demand.
**SMS delivery options** — Notify can send recipient notifications via SMS through Ingo-managed delivery or through your own SMS infrastructure. With Ingo-managed SMS, Ingo sends directly to recipients and manages consent collection — though notifications identify Ingo as the sender rather than your brand. Many clients integrate their own SMS platform for full brand control, directing recipients to the Ingo-hosted disbursement URL. Both approaches are supported. See [Custom Domain & DNS Setup](/docs/hub/domain-setup#sms-delivery-options) for details, or ask your Integration Manager which approach fits your program.
***
## Capabilities
Define up to three party roles per transaction. **Recipients** receive and claim
funds. **Approvers** actively gate the disbursement — funds do not release until
all designated approvers have acted. **Interested Parties** receive visibility
into the transaction without taking any action.
Every capability available in a single-recipient flow is fully supported.
Notification, identity and OFAC screening, client-configured payment options
with amount-based thresholds, account tokenization, and real-time webhook
updates at every status change — all managed by Ingo from a single staged
notification.
In Development
Collect payment preferences independently of any disbursement. The fully hosted
enrollment experience will present your configured payment options through the
Embedded Account Capture interface — no portal or payment UI to build or host.
On completion, Ingo returns a customer\_account\_token ready for use
in any future disbursement. [Tell us this matters to your program →](/docs/notify-managed/notification-types)
In Development
Decouple enrollment from payment for programs that disburse on a recurring
cadence. Enroll a recipient once; stage subsequent disbursements against their
token without re-collecting account details or re-running the hosted experience.
Ideal for payroll, earned wage access, insurance premiums, and recurring financial
programs. [Tell us this matters to your program →](/docs/notify-managed/notification-types)
***
## API Reference
Notify — Managed Parties exposes one staging endpoint. Cancellation of a staged
notification before the recipient has claimed uses the shared Notify Cancel endpoint.
Submit a notification with recipient details, party roles, disbursement intent,
and notification type. Ingo immediately begins the managed lifecycle on your behalf.
Cancel a staged notification before the recipient has claimed their disbursement.
Managed Parties shares the Cancel endpoint with Notify — Classic.
# Quick Start
Source: https://developers.ingopayments.com/docs/notify-managed/quick-start
Stage your first Notify — Managed Parties disbursement, add an approver, and handle the party engagement webhooks.
This guide covers the two most common starting points for Notify — Managed Parties: a standard single-recipient disbursement, and a multi-party disbursement with an approval gate. Both use the same `POST /gateway/v4/notify` endpoint with a structured three-envelope request body. Like all Notify products, the flow is primarily async — you stage a notification and then listen for webhooks to track what's happening.
You'll need your **username**, **secret**, and **participant\_id** to follow this guide. These are issued by your Ingo integration manager during onboarding.
***
## Environments
| Environment | Base URL |
| ----------- | ----------------------------------- |
| Sandbox | `https://payapi-sandbox.ingo.money` |
| Production | `https://payapi.ingo.money` |
***
## Request structure
Every v4 notify request uses a three-envelope body:
| Envelope | Contents |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `request{}` | Authentication context — `participant_id` and `timestamp` |
| `transaction{}` | Disbursement details — amount, currency, IDs, workflow, notify type, sender |
| `transaction_parties[]` | One object per party — role, contact details, identity challenge, notification context |
***
All Notify — Managed Parties requests use **HMAC-SHA512** signing. Build the `X-Date`, `Content-sha512`, `Content-Length`, and `Content-Type` headers, then assemble the `Authorization` header before sending.
See [Authentication](/docs/notify-managed/authentication) for the full construction guide.
Use **RAW** (binary) output from your HMAC library before Base64 encoding — not hex. Base64-encoding hex output produces an incorrect signature and a `401 Unauthorized` response.
Set `notify_type: 0` and define one party with `role: 0` (Recipient). This is the standard one-time disbursement flow — identical in outcome to Notify — Classic but using the v4 envelope structure.
```http theme={null}
POST /gateway/v4/notify HTTP/1.1
Host: payapi-sandbox.ingo.money
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="hAMqhSX6eogO1QpES9Dg9..."
X-Date: Fri, 17 Jan 2020 19:59:29 GMT
Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08=
Content-Length: 680
Content-Type: application/json
{
"request": {
"participant_id": 12345,
"timestamp": 1745356800
},
"transaction": {
"transaction_amount": {
"amount": 250.00,
"currency_code": "USD"
},
"participant_unique_ids": {
"participant_unique_id1": "a4f1b2c3-d456-789e-f012-34567890abcd"
},
"workflow_id": 1,
"notify_type": 0
},
"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": "alex.rivera@example.com",
"phone_mobile": "5555550100"
},
"contact_address": {
"address1": "100 Innovation Way",
"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"
}
]
}
]
}
```
A successful response returns a `notification_id` and the Ingo-assigned `party_id` for each party:
```json theme={null}
{
"request": { "participant_id": 12345, "timestamp": 1745356800 },
"response": {
"status": "100",
"message": "Success"
},
"transaction": {
"participant_unique_ids": {
"participant_unique_id1": "a4f1b2c3-d456-789e-f012-34567890abcd"
},
"notification_id": "9876543",
"parties": [
{ "client_provided_id": "party-001", "party_id": "1" }
]
}
}
```
The `status: 100` response confirms the notification was **staged** — not that the recipient has been paid. The disbursement lifecycle continues asynchronously via webhooks.
To require approval before funds are released, add a second party to `transaction_parties[]` with `role: 1`. The disbursement will not process until the approver has acted — Ingo manages the approver notification and engagement on your behalf.
Add this object to the `transaction_parties` array alongside your recipient:
```json theme={null}
{
"settings": {
"client_provided_id": "approver-001",
"role": 1,
"classification": 1,
"recipient_enabled": 0
},
"name_personal": {
"first_name": "Jordan",
"last_name": "Patel"
},
"contact_telcom": {
"email": "jordan.patel@example.com",
"phone_mobile": "5555550200"
}
}
```
`multiparty_enabled` must be active on your program configuration for `role: 1` and `role: 2` to be accepted. Contact your integration manager if you receive a validation error on party roles.
When the approver acts, Ingo posts a `transaction.recipient.payment.status.approvals.complete` webhook event.
After staging, Ingo posts webhook events to your configured endpoint as each party moves through their engagement. In a multi-party flow, you'll see events for each party independently.
Key events to handle:
| Event | Meaning |
| --------------------------------------------------------- | ------------------------------------------------------ |
| `transaction.recipient.notification.sent` | A party has been notified |
| `transaction.recipient.authentication.complete` | Recipient passed identity verification |
| `transaction.recipient.payment.status.approvals.complete` | All approvers have acted; disbursement released |
| `transaction.recipient.payment.tokenization.complete` | Recipient selected a payment method; account tokenized |
| `transaction.recipient.payment.status.approved` | Disbursement approved and submitted for processing |
| `transaction.recipient.payment.status.funded` | Funds delivered to recipient |
See [Webhooks](/docs/notify-managed/webhooks/overview) for the full event reference and payload schemas.
To stop a staged notification before any party has claimed, use the shared Cancel endpoint with the `notification_id` returned at staging.
```http theme={null}
POST /gateway/v3/notifycancel HTTP/1.1
Host: payapi-sandbox.ingo.money
Authorization: hmac username="test", ...
Content-Type: application/json
{
"participant_id": 12345,
"notification_id": 9876543
}
```
See [Notify — Cancel](/docs/notify-classic/notify/cancel) for the full field reference.
***
## What's next
Learn about all four notify types — including enrollment and recurring flows currently in development.
Complete field reference for the v4 stage endpoint.
All webhook event types, payload schemas, and signature verification.
Full HMAC-SHA512 construction guide and common signing errors.
# Testing
Source: https://developers.ingopayments.com/docs/notify-managed/testing
Scenario-based testing guide for Notify Managed Parties staged disbursements, multi-party approval flows, and webhook event verification.
## Sandbox Environment
Your sandbox mirrors production behavior including payment routing logic, OFAC screening, account verification services, and webhook delivery. Sandbox credentials and velocity limits are provisioned during onboarding.
Sandbox velocity limits are client-specific and configured by your Ingo integration manager during onboarding.
***
## Test Categories
| Category | Description | How to initiate |
| ---------------- | ----------------------------------------------------------- | -------------------------------------------- |
| **Self-Service** | Complete independently in the sandbox at your own pace | Your sandbox credentials |
| **Controlled** | Requires an enablement flag set by your integration manager | Contact your integration manager to schedule |
| **Guided** | Live session with your Ingo integration team recommended | Contact your integration manager to schedule |
***
## Understanding Soft Failures
Ingo uses two distinct failure modes across verification and authentication services:
**Soft failure** — A partial match that does not stop the flow. The recipient experiences no interruption and proceeds transparently. Your system is notified of the result in the background via the correlated **success** webhook carrying the soft-fail status code. No failure webhook emits for a soft failure.
**Hard failure** — A mismatch on a field your configuration has designated as requiring a hard failure. How each verification field’s mismatch is treated is defined during your implementation setup via the configuration form. When a hard failure occurs, the recipient is stopped and must retry. If maximum attempts are exhausted, the session or transaction terminates.
***
## A Note on Multi-Party Testing
Notify Managed Parties flows are scenario-driven, not scripted. Party roles, approval decisions, authentication outcomes, and disbursement selections are all made through live recipient and approver interactions. Because the orchestration responds dynamically to those interactions, testing is structured around **intended outcomes** rather than prescriptive step sequences.
The verification mechanism for every scenario is the webhook event sequence — you know a scenario completed correctly when the expected events fire in the correct order.
***
## Self-Service Scenarios
**Category:** Self-Service
**Scenario:** Stage a transaction via the Notify API. The recipient receives the notification email and it is delivered successfully.
**Success criteria:** Notification delivered without bounce
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------------- | ---------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
**Category:** Self-Service
**Scenario:** Stage a transaction. Receive the initial notification. Allow the reminder notification to fire without completing the disbursement.
**Success criteria:** Both sent and reminder events received
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------------- | ------------------------------------------------ | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Sent (Reminder) | `transaction.recipient.notification.status.sent` | 1200 series |
**Category:** Self-Service
**Scenario:** Stage a transaction using an invalid email address. Confirms your system handles undeliverable notification events.
**Success criteria:** Bounce event received
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | --------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Bounced | `transaction.recipient.notification.status.bounced` | 1200 series |
**Category:** Self-Service
**Scenario:** Resubmit an identical Notify API request using the same `participant_unique_id1`. Confirms duplicate protection is working correctly.
**Success criteria:** Response `status: 101` — no new transaction created
**Category:** Self-Service
**Scenario:** Stage a transaction. Submit a Notify Cancel request before the recipient completes the flow. Confirms cancellation before disbursement selection.
**Success criteria:** Cancellation confirmed, disbursement request canceled event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------------- | ------------------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Disbursement Canceled | `transaction.recipient.payment.disbursement.request.canceled` | 1110 |
**Category:** Self-Service
**Scenario:** Attempt to cancel a transaction in a state that does not permit cancellation — already completed, already canceled, already expired, or invalid notification ID. Confirms your system handles cancel error responses gracefully.
**Success criteria:** Appropriate error status returned for each invalid state
**Category:** Self-Service
**Scenario:** Stage a transaction. Open the notification and complete the authentication challenge with fully matching data. Recipient proceeds to disbursement selection.
**Success criteria:** Authentication success event fires, flow continues to account selection
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1100 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Open the notification and enter partially matching authentication data. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial match in the background via the authentication success webhook carrying the soft-fail status code.
**Success criteria:** Authentication success fires with soft-fail status code; recipient proceeds uninterrupted
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1101 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Open the notification and provide non-matching authentication data until maximum attempts are reached. The recipient is stopped at each failure and may retry. After exhausting all attempts, the transaction terminates.
**Success criteria:** Failure event fires, transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Failure | `transaction.recipient.authentication.status.failure` | 1102 |
| 4 | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Self-Service
**Scenario:** Stage a transaction with RVDM enabled. Complete authentication. Provide recipient information that fully matches the session data.
**Success criteria:** RVDM success event fires, flow continues to account selection
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ------------------------------------------------- | --------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1103 |
**Category:** Self-Service
**Scenario:** Stage a transaction with RVDM enabled. Provide partially matching recipient data. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial match in the background via the RVDM success webhook carrying the soft-fail status code.
**Success criteria:** RVDM success fires with soft-fail status code; recipient proceeds to account selection uninterrupted
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ------------------------------------------------- | --------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1104 |
**Category:** Self-Service
**Scenario:** Stage a transaction with RVDM enabled. Provide non-matching recipient data until maximum attempts are exhausted. The recipient is stopped at each failure and may retry. After exhausting all attempts, the transaction terminates.
**Success criteria:** RVDM failure event fires, transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ------------------------------------------------- | --------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | RVDM Failure | `transaction.recipient.verification.rvdm.failure` | 1105 |
| 5 | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete the flow through authentication and RVDM. Select card disbursement and tokenize a valid test card. Payment processes successfully.
**Success criteria:** Tokenization and payment success events fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | --------------------------------- | ---------------------------------------------- | --------------- |
| 1–4 | Notification / Auth / RVDM events | *(as above)* | — |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1125 |
**Category:** Self-Service
**Scenario:** Stage a second transaction for a recipient with a previously tokenized card. Complete the flow using the existing token without re-entering card details.
**Success criteria:** Payment completes using stored token, no re-tokenization required
**Category:** Self-Service
**Scenario:** Stage a transaction. Enter a card account number not supported for disbursement. The recipient is stopped and must use a different account. Your system is notified via the CNS/CD failure webhook.
**Success criteria:** CNS/CD failure event fires
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------- | ------------------------------------------------------ | --------------- |
| — | CNS/CD Failure | `transaction.account.verification.card.failure.cns_cd` | 700 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete authentication and RVDM. Select ACH disbursement and enter a valid test routing and account number. Payment processes successfully.
**Success criteria:** Tokenization and payment success events fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | --------------------------------- | ---------------------------------------------- | --------------- |
| 1–4 | Notification / Auth / RVDM events | *(as above)* | — |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1126 |
**Category:** Self-Service
**Scenario:** Stage a second ACH transaction for a recipient with a previously registered account. Completes using the existing token.
**Success criteria:** Payment completes using stored token
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete authentication and select PayPal as the disbursement method. In the PayPal flow, PayPal Account Verification (AV) runs in place of RVDM. The AV success webhook notifies your system of the verification result in the background. The recipient experiences no interruption — the account is tokenized and payment processes successfully.
**Success criteria:** PayPal AV success, tokenization success, and payment success all fire in sequence
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1100 or 1101 |
| 4 | PayPal AV Success | `transaction.account.verification.paypal.success.av` | 1148 |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1134 |
**Category:** Self-Service
**Scenario:** Stage a second PayPal transaction for a recipient with a previously registered PayPal account. Completes using the existing token.
**Success criteria:** Payment completes using stored token
**Category:** Self-Service
**Scenario:** Stage a transaction. Complete the flow and have the recipient elect check as their disbursement method. Client issues the check.
**Success criteria:** Check in process event fires confirming the recipient elected check
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | -------------------------------------------- | --------------- |
| — | Check In Process | `transaction.recipient.payment.status.check` | 1111 or 1112 |
**Category:** Self-Service
**Scenario:** Stage a check transaction. Recipient selects check but does not confirm the address on file.
**Success criteria:** Check in process event fires with address-not-confirmed status code
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | -------------------------------------------- | --------------- |
| — | Check In Process | `transaction.recipient.payment.status.check` | 1112 |
**Category:** Self-Service
**Scenario:** Stage a Client Issuance check transaction. Allow the notification to expire without recipient action. The disbursement request expires and the transaction terminates.
**Success criteria:** Expired event fires; transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | -------------------- | ------------------------------------------------------------ | --------------- |
| 1 | Disbursement Expired | `transaction.recipient.payment.disbursement.request.expired` | 1109 |
| 2 | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Self-Service
**Scenario:** Stage an Ingo Issuance check transaction. Allow the notification to expire without recipient action. Ingo defaults to issuing the check — the payment succeeds and the check is issued and subsequently paid.
**Success criteria:** Payment success fires, followed by check issued and check paid events
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | --------------------------------------------------- | --------------- |
| 1 | Payment Success | `transaction.recipient.payment.status.success` | 1133 |
| 2 | Check Issued | `transaction.recipient.payment.status.check.issued` | 100 |
| 3 | Check Paid | `transaction.recipient.payment.status.check.paid` | 100 |
**Category:** Self-Service
**Scenario:** Stage a transaction configured for Ingo check issuance. Complete the full flow. Ingo issues the check and it is subsequently paid.
**Success criteria:** Payment success, check issued, and check paid events all fire
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | --------------------------------------------------- | --------------- |
| 1 | Payment Success | `transaction.recipient.payment.status.success` | 1133 |
| 2 | Check Issued | `transaction.recipient.payment.status.check.issued` | 100 |
| 3 | Check Paid | `transaction.recipient.payment.status.check.paid` | 100 |
**Category:** Self-Service
**Scenario:** Stage a transaction. Open the notification, complete authentication, and have the recipient elect to cancel the disbursement from within the iFrame. Confirms your system handles recipient-initiated cancellation correctly.
**Success criteria:** Recipient cancel event fires, transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | -------------------------------------------------------------- | --------------- |
| — | Recipient Cancel | `transaction.recipient.payment.notice.status.recipient.cancel` | 1139 |
| — | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
***
## Controlled Scenarios
The following scenarios require your Ingo integration manager to enable a specific configuration before testing can begin. Contact your integration team to schedule these.
**Category:** Controlled
**Scenario:** A card account tokenization where the AVS check returns a soft failure. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial address match in the background via the tokenization success webhook carrying the soft-fail status code.
**Success criteria:** Tokenization success fires with AVS soft-fail status code; payment completes
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | --------------------------------- | ---------------------------------------------- | --------------- |
| 1–3 | Notification / Auth / RVDM events | *(as above)* | — |
| 4 | Tokenization Success | `transaction.account.tokenization.success` | 111–119 range |
| 5 | Payment Success | `transaction.recipient.payment.status.success` | 1125 |
**Category:** Controlled
**Scenario:** A card account tokenization where the AVS check returns a hard decline. The recipient is stopped and must use a different account. Your system is notified via the AVS/CVV failure webhook.
**Success criteria:** AVS/CVV failure event fires; account rejected
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | ------------------------------------------------------- | --------------- |
| — | AVS/CVV Failure | `transaction.account.verification.card.failure.avs_cvv` | 753–759 range |
**Category:** Controlled
**Scenario:** AVS or CVV hard failures repeat until the maximum attempt threshold is reached. The recipient is stopped at each failure and may retry. After exhausting all attempts, the transaction terminates.
**Success criteria:** Termination event fires after max attempts
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| ----- | ------------------ | ------------------------------------------------- | --------------- |
| Final | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Controlled
**Scenario:** An ACH account verification returns a soft failure on account number validation (ANV) or name/address validation (NAV). The recipient experiences no interruption — the flow continues transparently. Your system is notified of the partial match result in the background via the tokenization success webhook carrying the soft-fail status code.
**Success criteria:** Tokenization success fires with soft-fail status code; payment completes
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------------- | ----------------------------------------------------- | --------------------- |
| 1 | Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| 2 | Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| 3 | Authentication Success | `transaction.recipient.authentication.status.success` | 1100 or 1101 |
| 4 | RVDM Success | `transaction.recipient.verification.rvdm.success` | 1103 or 1104 |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | Soft-fail status code |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1126 |
**Category:** Controlled
**Scenario:** ACH account verification returns a hard decline on routing number (RNV), account number (ANV), or name/address (NAV) validation. The recipient is stopped and must use a different account. Your system is notified via the appropriate failure webhook.
**Success criteria:** Applicable failure event fires; account rejected
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | -------------------------------------------------- | --------------- |
| — | RNV Failure | `transaction.account.verification.ach.failure.rnv` | 743 |
| — | *or* ANV Failure | `transaction.account.verification.ach.failure.anv` | 767–769 |
| — | *or* NAV Failure | `transaction.account.verification.ach.failure.nav` | 776–778 |
**Category:** Controlled
**Scenario:** ACH verification hard failures repeat until maximum attempts are exhausted. The recipient is stopped at each failure and may retry. After exhausting all attempts, the transaction terminates.
**Success criteria:** Termination event fires after max attempts
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| ----- | ------------------ | ------------------------------------------------- | --------------- |
| Final | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Controlled
**Scenario:** PayPal account verification returns a partial match. The recipient experiences no interruption and proceeds transparently. Your system is notified of the partial match in the background via the PayPal AV success webhook carrying the soft-fail status code. The account is tokenized and payment completes.
**Success criteria:** PayPal AV success fires with soft-fail status code; tokenization and payment success follow
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| --- | -------------------------- | ---------------------------------------------------- | --------------------- |
| 1–3 | Notification / Auth events | *(as above)* | — |
| 4 | PayPal AV Success | `transaction.account.verification.paypal.success.av` | Soft-fail status code |
| 5 | Tokenization Success | `transaction.account.tokenization.success` | 100 |
| 6 | Payment Success | `transaction.recipient.payment.status.success` | 1134 |
**Category:** Controlled
**Scenario:** PayPal account verification returns a hard failure. The recipient is stopped and must retry. If maximum attempts are reached, the transaction terminates. Your system is notified via the PayPal AV failure webhook.
**Success criteria:** PayPal AV failure event fires; termination event fires after max attempts
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| ----- | ------------------ | ---------------------------------------------------- | --------------- |
| — | PayPal AV Failure | `transaction.account.verification.paypal.failure.av` | 1150 |
| Final | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
**Category:** Controlled
**Scenario:** A staged transaction triggers an OFAC hit during the disbursement flow. The payment is suspended. After OFAC review, the transaction is cleared and payment completes.
**Success criteria:** Suspended and cleared events both fire; payment ultimately succeeds
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | ---------------------------------------------------------- | --------------- |
| 1 | OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Cleared | `transaction.recipient.verification.ofac.status.cleared` | 1107 |
| 3 | Payment Success | `transaction.recipient.payment.status.success` | 1125–1134 |
**Category:** Controlled
**Scenario:** An OFAC suspension is reviewed and the transaction is cleared, but the payment is subsequently declined by the network.
**Success criteria:** Suspended and cleared events fire; payment terminates after clearance
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | --------------- | ---------------------------------------------------------- | --------------- |
| 1 | OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Cleared | `transaction.recipient.verification.ofac.status.cleared` | 1107 |
| 3 | Payment Failure | `transaction.recipient.payment.status.failure` | — |
**Category:** Controlled
**Scenario:** An OFAC suspension is reviewed and confirmed. The transaction is terminated.
**Success criteria:** Suspended and failure events fire; transaction terminates
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ------------------ | ---------------------------------------------------------- | --------------- |
| 1 | OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| 2 | OFAC Failure | `transaction.recipient.verification.ofac.status.failure` | 1108 |
| 3 | Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113 |
***
## Guided Scenarios
The following scenarios involve multi-party orchestration and dynamic role interactions that benefit from coordination with your Ingo integration team. Contact your integration manager to schedule a guided session.
Multi-party flows are scenario-driven by design. Party roles, approval decisions, and notification configurations interact dynamically based on your implementation setup. The key outcomes to validate during guided sessions:
| Outcome | Key events to verify |
| --------------------------------- | -------------------------------------------------------------------------------------------------- |
| Single approver — approved | `approvals.pmt-suspended` → `approvals.decision.approved` → `approvals.complete` → payment success |
| Single approver — declined | `approvals.pmt-suspended` → `approvals.decision.declined` → payment terminated |
| Multiple approvers — all approve | `approvals.pmt-suspended` → multiple `decision.approved` → `approvals.complete` |
| Multiple approvers — one declines | `approvals.pmt-suspended` → `decision.declined` → payment terminated |
| With notified parties | Party notification events firing alongside approval events |
**Category:** Guided
**Scenario:** A previously completed payment is returned by the account issuer. Confirms your system correctly handles the returned status and updates your records.
**Success criteria:** Returned event received and processed correctly
**Key webhook sequence to verify:**
| # | Event | Topic | Expected Status |
| - | ---------------- | ----------------------------------------------- | --------------- |
| — | Payment Returned | `transaction.recipient.payment.status.returned` | 1114 |
***
## Webhook Events Reference
| Event | Topic | Expected Status |
| --------------------------- | ---------------------------------------------------- | --------------- |
| Notification Sent | `transaction.recipient.notification.status.sent` | 1200 series |
| Notification Received | `transaction.recipient.notification.status.received` | 1200 series |
| Notification Bounced | `transaction.recipient.notification.status.bounced` | 1200 series |
| Party Notification Sent | `transaction.party.notification.status.sent` | 1200 series |
| Party Notification Received | `transaction.party.notification.status.received` | 1200 series |
| Party Notification Bounced | `transaction.party.notification.status.bounced` | 1200 series |
| Event | Topic | Expected Status |
| -------------- | ---------------------------------------------------------- | ----------------------------- |
| Auth Success | `transaction.recipient.authentication.status.success` | 1100 (full), 1101 (soft fail) |
| Auth Failure | `transaction.recipient.authentication.status.failure` | 1102 |
| RVDM Success | `transaction.recipient.verification.rvdm.success` | 1103 (full), 1104 (soft fail) |
| RVDM Failure | `transaction.recipient.verification.rvdm.failure` | 1105 |
| OFAC Suspended | `transaction.recipient.verification.ofac.status.suspended` | 1106 |
| OFAC Cleared | `transaction.recipient.verification.ofac.status.cleared` | 1107 |
| OFAC Failure | `transaction.recipient.verification.ofac.status.failure` | 1108 |
| Event | Topic | Expected Status |
| -------------------- | ------------------------------------------------------- | ----------------------------------- |
| Card CNS/CD Failure | `transaction.account.verification.card.failure.cns_cd` | 700 |
| Card AVS/CVV Failure | `transaction.account.verification.card.failure.avs_cvv` | 753–759 |
| ACH RNV Failure | `transaction.account.verification.ach.failure.rnv` | 743 |
| ACH ANV Failure | `transaction.account.verification.ach.failure.anv` | 767–769 |
| ACH NAV Failure | `transaction.account.verification.ach.failure.nav` | 776–778 |
| PayPal AV Failure | `transaction.account.verification.paypal.failure.av` | 1150 |
| PayPal AV Success | `transaction.account.verification.paypal.success.av` | 1148 |
| Tokenization Success | `transaction.account.tokenization.success` | 100 (full), 111–119 (AVS soft fail) |
| Event | Topic | Expected Status |
| ----------------------------- | ------------------------------------------------------------------ | --------------- |
| Payment Suspended (Approvals) | `transaction.recipient.payment.status.approvals.pmt-suspended` | 1170 |
| Approval — Approved | `transaction.recipient.payment.status.approvals.decision.approved` | 1123 |
| Approval — Declined | `transaction.recipient.payment.status.approvals.decision.declined` | 1124 |
| Approvals Complete | `transaction.recipient.payment.status.approvals.complete` | 1171 |
| Event | Topic | Expected Status |
| ------------------------ | -------------------------------------------------------------- | --------------- |
| Payment Success — Card | `transaction.recipient.payment.status.success` | 1125 |
| Payment Success — ACH | `transaction.recipient.payment.status.success` | 1126 |
| Payment Success — Check | `transaction.recipient.payment.status.success` | 1133 |
| Payment Success — PayPal | `transaction.recipient.payment.status.success` | 1134 |
| Payment Failure | `transaction.recipient.payment.status.failure` | varies |
| Payment Terminated | `transaction.recipient.payment.status.terminated` | 1113, 1132 |
| Payment Returned | `transaction.recipient.payment.status.returned` | 1114 |
| Disbursement Expired | `transaction.recipient.payment.disbursement.request.expired` | 1109 |
| Disbursement Canceled | `transaction.recipient.payment.disbursement.request.canceled` | 1110 |
| Recipient Cancel | `transaction.recipient.payment.notice.status.recipient.cancel` | 1139 |
| Check In Process | `transaction.recipient.payment.status.check` | 1111, 1112 |
| Check Issued | `transaction.recipient.payment.status.check.issued` | 100 |
| Check Paid | `transaction.recipient.payment.status.check.paid` | 100 |
| Check Canceled | `transaction.recipient.payment.status.check.canceled` | 100 |
| Check Stopped | `transaction.recipient.payment.status.check.stopped` | 100 |
| Check Returned | `transaction.recipient.payment.status.check.returned` | 1114 |
# Webhooks
Source: https://developers.ingopayments.com/docs/notify-managed/webhooks/overview
Event notifications for Notify — Managed Parties — staging, party notifications, authentication, verification, tokenization, approvals, and payment status.
Notify — Managed Parties is an async-first product. The synchronous stage response confirms the notification was accepted; every subsequent lifecycle event — across all parties, through approvals and through to funded — is delivered via webhook. In a multi-party flow, events fire independently per party as each one moves through their engagement.
Webhooks are delivered as JSON via HTTP POST to your registered endpoint. Return any `2xx` status to acknowledge receipt. See [Webhooks](/docs/hub/webhooks) for endpoint requirements, IP allowlist, and retry behavior.
***
## Event categories
| Category | What it covers |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Transaction Staging** | Confirmation that a multi-party disbursement was successfully staged |
| **Party Notification** | Notification sent, received, and bounced — fires per party |
| **Party Authentication** | Identity challenge success and failure — fires per party |
| **Recipient Verification** | RVDM identity matching outcomes and OFAC screening results |
| **Account Verification** | Card (CNS/CD, AVS/CVV), ACH (RNV, ANV, NAV), and PayPal verification outcomes |
| **Account Tokenization** | Successful account tokenization — includes the `customer_account_token` |
| **Approvals** | All designated approvers have acted; disbursement released for processing |
| **Payment Status** | Check issued, paid, canceled, stopped, and returned; payment success, failure, and return; disbursement expiry and cancellation |
***
## Multi-party behavior
In a multi-party transaction, webhook events fire independently for each party as they engage. An approver's `notification.status.sent` event may arrive before or after the recipient's `authentication.status.success` event — events are not serialized across parties.
The `transaction.recipient.payment.status.approvals.complete` event signals that all designated approvers have acted and the disbursement has been released. This is the gate event your integration should listen for if you need confirmation that the approval requirement has been satisfied before funds move.
***
## Event reference
Full event catalog — payload schemas, field definitions, and examples for every Notify — Managed Parties webhook event.
# Account Tokenization Success
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/account-tokenization-success
Fired when a recipient account is successfully tokenized via the iFrame plugin. Documents the latest contract version (v3); earlier versions may omit account_id.
# ACH Account Number Verification Failure
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/ach-account-number-verification-failure
Fired when ACH account number verification (ANV) fails.
# ACH Name/Address Verification Failure
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/ach-nameaddress-verification-failure
Fired when ACH name and address verification (NAV) fails.
# ACH Routing Number Verification Failure
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/ach-routing-number-verification-failure
Fired when ACH routing number verification (RNV) fails.
# Card AVS/CVV Verification Failure
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/card-avscvv-verification-failure
Fired when AVS or CVV verification fails for a card account.
# Card CNS/CD Verification Failure
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/card-cnscd-verification-failure
Fired when card number screening or card data verification fails.
# PayPal Account Verification Failure
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/paypal-account-verification-failure
Fired when PayPal account verification fails.
# PayPal Account Verification Success
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/paypal-account-verification-success
Fired when PayPal account verification completes successfully.
# RVDM Verification Failure
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/rvdm-verification-failure
Fired when RVDM verification fails via the iFrame plugin.
# RVDM Verification Success
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/rvdm-verification-success
Fired when Recipient Verification Data Matching (RVDM) completes successfully via the iFrame plugin.
# Session Expired
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/session-expired
Fired when an iFrame plugin session expires without being completed.
# Session Terminated
Source: https://developers.ingopayments.com/iframe-webhooks/webhooks/session-terminated
Fired when the overall maximum account verification attempt limit is exceeded, terminating the session.
# Check Canceled
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/check-canceled
Fired when an issued check is canceled.
# Check Issued
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/check-issued
Fired when Ingo issues a check for the payment.
# Check Paid
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/check-paid
Fired when an issued check is cashed/paid.
# Check Returned
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/check-returned
Fired when a check is returned due to positive pay exception or issuer rejection.
# Check Stopped
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/check-stopped
Fired when a stop payment is placed on an issued check.
# OFAC Cleared
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/ofac-cleared
Fired when an OFAC suspension is resolved and the payment is cleared to proceed.
# OFAC Failure
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/ofac-failure
Fired when an OFAC hit is confirmed and the transaction is terminated.
# OFAC Suspended
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/ofac-suspended
Fired when an initial OFAC hit causes the payment to be suspended pending review.
# Payment Returned
Source: https://developers.ingopayments.com/ingopay-webhooks/webhooks/payment-returned
Fired when a non-check payment is returned by the issuer.
# Account Tokenization Success
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/account-tokenization-success
Fired when a recipient account is successfully tokenized. Documents the latest contract version (v4); earlier versions may omit account_id.
# ACH Account Number Verification Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/ach-account-number-verification-failure
Fired when ACH account number verification (ANV) fails.
# ACH Name/Address Verification Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/ach-nameaddress-verification-failure
Fired when ACH name and address verification (NAV) fails.
# ACH Routing Number Verification Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/ach-routing-number-verification-failure
Fired when ACH routing number verification (RNV) fails.
# Authentication Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/authentication-failure
Fired when the recipient fails the authentication challenge.
# Authentication Success
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/authentication-success
Fired when the recipient successfully completes the authentication challenge.
# Card AVS/CVV Verification Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/card-avscvv-verification-failure
Fired when AVS or CVV verification fails for a card account.
# Card CNS/CD Verification Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/card-cnscd-verification-failure
Fired when card number screening or card data verification fails.
# Check Canceled
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/check-canceled
Fired when an issued check is canceled.
# Check In Process
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/check-in-process
Fired when a check payment enters processing.
# Check Issued
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/check-issued
Fired when Ingo issues a check for the payment.
# Check Paid
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/check-paid
Fired when an issued check is cashed/paid.
# Check Returned
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/check-returned
Fired when an issued check is returned.
# Check Stopped
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/check-stopped
Fired when a stop payment is placed on an issued check.
# Disbursement Request Canceled
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/disbursement-request-canceled
Fired when a staged disbursement request is canceled.
# Disbursement Request Expired
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/disbursement-request-expired
Fired when a staged disbursement request expires before the recipient completes the process.
# Notification Bounced
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/notification-bounced
Fired when the notification delivery fails (email bounced or SMS undeliverable).
# Notification Received
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/notification-received
Fired when the recipient opens the notification.
# Notification Sent
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/notification-sent
Fired when Ingo successfully delivers a disbursement notification to the recipient.
# OFAC Cleared
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/ofac-cleared
Fired when an OFAC suspension is resolved and the payment is cleared to proceed.
# OFAC Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/ofac-failure
Fired when an OFAC hit is confirmed and the transaction is terminated.
# OFAC Suspended
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/ofac-suspended
Fired when an initial OFAC hit causes the payment to be suspended pending review.
# Payment Failed
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/payment-failed
Fired when a payment disbursement fails.
# Payment Returned
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/payment-returned
Fired when a non-check payment is returned by the issuer.
# Payment Successful
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/payment-successful
Fired when a payment disbursement completes successfully. Documents the latest contract version (v3); earlier versions may omit account_id.
# Payment Terminated
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/payment-terminated
Fired when a payment is terminated (terminal event).
# PayPal Account Verification Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/paypal-account-verification-failure
Fired when PayPal account verification fails.
# PayPal Account Verification Success
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/paypal-account-verification-success
Fired when PayPal account verification completes successfully.
# RVDM Verification Failure
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/rvdm-verification-failure
Fired when RVDM verification fails for the recipient.
# RVDM Verification Success
Source: https://developers.ingopayments.com/notify-classic-webhooks/webhooks/rvdm-verification-success
Fired when Recipient Verification Data Matching (RVDM) completes successfully.
# Account Tokenization Success
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/account-tokenization-success
Fired when a recipient account is successfully tokenized. Documents the latest contract version (v4); earlier versions may omit account_id.
# ACH Account Number Verification Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/ach-account-number-verification-failure
Fired when ACH account number verification (ANV) fails.
# ACH Name/Address Verification Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/ach-nameaddress-verification-failure
Fired when ACH name and address verification (NAV) fails.
# ACH Routing Number Verification Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/ach-routing-number-verification-failure
Fired when ACH routing number verification (RNV) fails.
# Approval Decision — Approved
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/approval-decision-—-approved
Fired when a party approves the transaction.
# Approval Decision — Declined
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/approval-decision-—-declined
Fired when a party declines to approve the transaction.
# Approvals Complete
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/approvals-complete
Fired when all required approvals have been received.
# Approvals — Payment Suspended
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/approvals-—-payment-suspended
Fired when payment processing is suspended pending required approval(s).
# Card AVS/CVV Verification Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/card-avscvv-verification-failure
Fired when AVS or CVV card verification fails.
# Card CNS/CD Verification Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/card-cnscd-verification-failure
Fired when card number screening or card data verification fails.
# Check Canceled
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/check-canceled
Fired when an issued check is canceled.
# Check In Process
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/check-in-process
Fired when a check payment enters processing.
# Check Issued
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/check-issued
Fired when Ingo issues a check for the payment.
# Check Paid
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/check-paid
Fired when an issued check is cashed/paid.
# Check Returned
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/check-returned
Fired when an issued check is returned.
# Check Stopped
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/check-stopped
Fired when a stop payment is placed on an issued check.
# Disbursement Request Canceled
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/disbursement-request-canceled
Fired when a staged disbursement request is canceled.
# Disbursement Request Expired
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/disbursement-request-expired
Fired when a staged disbursement request expires.
# Disbursement Staged
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/disbursement-staged
Fired when a multi-party disbursement is successfully staged and the session is ready.
# Dynamic Validation Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/dynamic-validation-failure
Fired when a party fails dynamic authentication validation.
# Dynamic Validation Success
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/dynamic-validation-success
Fired when a party successfully completes dynamic authentication validation.
# OFAC Cleared
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/ofac-cleared
Fired when an OFAC suspension is resolved.
# OFAC Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/ofac-failure
Fired when an OFAC hit is confirmed and the transaction is terminated.
# OFAC Suspended
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/ofac-suspended
Fired when an initial OFAC hit suspends the payment pending review.
# OTAC Delivery Generated
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/otac-delivery-generated
Fired when a one-time authentication code (OTAC) is generated and delivered to a party.
# OTAC Delivery Limit Reached
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/otac-delivery-limit-reached
Fired when the maximum number of OTAC delivery attempts is reached for a party.
# OTAC Validation Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/otac-validation-failure
Fired when a party fails to validate their one-time authentication code.
# OTAC Validation Success
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/otac-validation-success
Fired when a party successfully validates their one-time authentication code.
# Overall Authentication Failed
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/overall-authentication-failed
Fired when a party has exhausted all authentication attempts without success.
# Overall Authentication Passed
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/overall-authentication-passed
Fired when a party has successfully completed all required authentication steps.
# Party Notification Bounced
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/party-notification-bounced
Fired when a notification delivery fails for a party.
# Party Notification Received
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/party-notification-received
Fired when a party opens the notification.
# Party Notification Sent
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/party-notification-sent
Fired when Ingo successfully delivers a notification to a party in the transaction.
# Party Role Change
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/party-role-change
Coming Soon — Role delegation is not yet available. This event will fire when one or more parties in the transaction have their role changed via approver delegation.
# Payment Failed
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/payment-failed
Fired when a payment disbursement fails.
# Payment Returned
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/payment-returned
Fired when a payment is returned by the issuer.
# Payment Successful
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/payment-successful
Fired when a payment disbursement completes successfully. Documents the latest contract version (v3); earlier versions may omit account_id.
# Payment Terminated
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/payment-terminated
Fired when a payment is terminated (terminal event).
# PayPal Account Verification Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/paypal-account-verification-failure
Fired when PayPal account verification fails.
# PayPal Account Verification Success
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/paypal-account-verification-success
Fired when PayPal account verification succeeds.
# Recipient Canceled
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/recipient-canceled
Fired when the recipient elects to cancel their disbursement request.
# RVDM Verification Failure
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/rvdm-verification-failure
Fired when RVDM verification fails.
# RVDM Verification Success
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/rvdm-verification-success
Fired when RVDM verification completes successfully.
# Settlement Adjustment
Source: https://developers.ingopayments.com/notify-managed-webhooks/webhooks/settlement-adjustment
Fired when a settlement adjustment (credit or debit) is applied to a transaction.