Skip to main content
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

EnvironmentBase URL
Sandboxhttps://payapi-sandbox.ingo.money
Productionhttps://payapi.ingo.money

​
Request structure

Every v4 notify request uses a three-envelope body:
EnvelopeContents
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 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.
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:
{
  "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:
{
  "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:
EventMeaning
transaction.recipient.notification.sentA party has been notified
transaction.recipient.authentication.completeRecipient passed identity verification
transaction.recipient.payment.status.approvals.completeAll approvers have acted; disbursement released
transaction.recipient.payment.tokenization.completeRecipient selected a payment method; account tokenized
transaction.recipient.payment.status.approvedDisbursement approved and submitted for processing
transaction.recipient.payment.status.fundedFunds delivered to recipient
See Webhooks 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.
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 for the full field reference.

​
What’s next

Notification Types

Learn about all four notify types — including enrollment and recurring flows currently in development.

Notify — Stage

Complete field reference for the v4 stage endpoint.

Webhooks

All webhook event types, payload schemas, and signature verification.

Authentication

Full HMAC-SHA512 construction guide and common signing errors.