> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.