Quick Start

Environment	Base URL
Sandbox	`https://payapi-sandbox.ingo.money`
Production	`https://payapi.ingo.money`

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

Step 1 — Sign your request

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.

Step 2 — Stage a single-recipient disbursement

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.

Step 3 — Add an approver

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.

Step 4 — Handle webhook events

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 for the full event reference and payload schemas.

Step 5 — Cancel if needed

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.

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.

Overview

Notify

Webhooks

Environments

Request structure

What’s next

Notification Types

Notify — Stage

Webhooks

Authentication

​Environments

​Request structure

​What’s next

Notification Types

Notify — Stage

Webhooks

Authentication

Environments

Request structure

What’s next