Single Sign-On

Single Sign-On (SSO) lets you authenticate your own customer in your own portal and hand them directly into the Digital Payment Center (DPC). The customer arrives already authenticated, so the DPC does not present the Recipient Authentication challenge. SSO is an authentication method in its own right, configured per participant as an alternative to Recipient Authentication questions or a One-Time Authorization Code. Every party to a payment must satisfy the configured authentication method individually.

This is a signed-URL redirect, not a federated identity integration. There is no SAML metadata exchange, no identity-provider configuration, no directory integration and no certificate rotation. You sign a URL with a shared secret and issue a redirect.

The signing scheme on this page is not the same as the HMAC request signing used for Ingo APIs. API requests are signed over a header signature string — see Authentication. SSO is signed over the request URL itself, as described below. Confirm with your Integration Manager whether your SSO credentials are the same pair as your API credentials.

When to use it

Good fit

Your recipients already sign in to a portal you operate, and that portal is close enough to the system issuing disbursements to carry a signed link.

Use authentication questions instead

Recipients have no portal relationship with you, or a disbursement may reach someone who has stopped logging in — for example a closed or cancelled account.

You can offer both. A notification can invite the recipient to sign in or to continue through the standard challenge.

How it works

Stage the disbursement

Call Notify server-to-server. The response returns a notification_id. For Notify — Managed Parties it also returns a parties array, each entry carrying a party_id.

Your customer signs in to your portal

Authentication happens entirely on your side, using whatever method you already use.

Build and sign the redirect URL

Assemble the URL, compute the signature, and append it. See Hash generation.

Redirect the customer

Issue the redirect from your application server. The customer lands in the DPC already authenticated and selects how to be paid. No authentication challenge is presented.

Handle the callback

On completion, cancellation or error, Ingo redirects the customer to your return URL with a status and sub-status, which you may verify against the same signature scheme.

Multi-party disbursements

Notify — Managed Parties addresses entry per party, so the SSO URL carries a party identifier in addition to the notification identifier.

partyId is required on Notify — Managed Parties, including when the disbursement has a single recipient. The party is resolved by exact match — a request without partyId will not resolve to a party.

Both Recipient and Approver parties may enter by SSO. Interested parties do not enter the DPC and are not issued an entry URL. Because every party authenticates in their own right, the handoff is performed once per party, not once per payment. A disbursement with a recipient and an approver requires two separate signed redirects, each carrying that party’s own partyId.

Request

https://{domain}/session/sso/{notification_id}
  ?t={timestamp}
  &return_url={return_url}
  &nonce={nonce}
  &username={username}
  &h={hash}

https://{domain}/session/sso/{notification_id}
  ?t={timestamp}
  &return_url={return_url}
  &nonce={nonce}
  &username={username}
  &h={hash}
  &partyId={party_id}

URL values

Value	Description
`domain`	The default or custom domain of your hosted DPC. See Domain Setup
`notification_id`	The notification identifier returned by the Notify staging call

Parameters

Parameter	Description
`t`	Timestamp of signature generation. Epoch Unix timestamp in seconds
`return_url`	The authorized return URL the customer is sent back to. URL-encode this value
`nonce`	An arbitrary or random value returned to you unchanged in the callback. Used for additional validation of incoming messages
`username`	Your provisioned client username
`h`	The digital signature of the request
`partyId`	Notify — Managed Parties only, required. The `party_id` of the party signing in, from the `parties` array of the Notify response. This is `party_id`, not `client_provided_id`

The signed request is short-lived. The timestamp is validated on receipt and a request older than a short window, measured in seconds, is rejected. Generate the timestamp and issue the redirect in the same request cycle. Do not pre-generate SSO URLs, cache them, or deliver them by email or SMS. Confirm the exact window with your Integration Manager.

Hash generation

Generate a timestamp and encode your return URL

var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
var return_url = HttpUtility.UrlEncode("https://pay.example.com/callback");

Create the request URL

var nonce = Guid.NewGuid();
var requestUrl = $"{domain}/session/sso/{notification_id}"
    + $"?t={timestamp}&return_url={return_url}"
    + $"&nonce={nonce}&username={username}";

Do not include partyId in the string you sign. It is appended after the hash — see URL redirect.

Convert the request URL to lowercase

requestUrl = requestUrl.ToLower();

Compute the SHA-512 hash

static byte[] ComputeSha512Hash(string value)
{
    using (var sha512Managed = new SHA512Managed())
    {
        var content = Encoding.UTF8.GetBytes(value);
        return sha512Managed.ComputeHash(content);
    }
}

var sha512HashedContent = ComputeSha512Hash(requestUrl);

Compute the HMAC-SHA512 signature and Base64-encode it

static byte[] ComputeHmacHash(byte[] hashedContent, string secret)
{
    byte[] secretBytes = Encoding.UTF8.GetBytes(secret);
    using (HMACSHA512 hmacsha512 = new HMACSHA512(secretBytes))
    {
        return hmacsha512.ComputeHash(hashedContent);
    }
}

var hashBytes = ComputeHmacHash(sha512HashedContent, secret);
var hash = Convert.ToBase64String(hashBytes);

Use RAW output from your hashing and HMAC libraries — not hex. Base64-encoding hex output produces an incorrect signature.

URL redirect

Append the signature

requestUrl = $"{requestUrl}&h={hash}";

Append the party identifier — Managed Parties only

requestUrl = $"{requestUrl}&partyId={party_id}";

Issue the redirect

return Redirect(requestUrl);

Example — Notify — Managed Parties:

https://digitalpay.example.com/session/sso/1000001?t=1561045723&return_url=https%3A%2F%2Fpay.example.com%2Fcallback&nonce=PARTNER-REF-001&username=00000000-0000-0000-0000-000000000001&h=ootG56o3IrO8jMhigVb-uO11P9tpPvTzAGKtZTjPQELMXtEB7SOXiNs4x8zifYtsBUNEaW3lDJcn8of1DUoW8Q&partyId=00000000-0000-0000-0000-000000000002

Response callback

{return_url}?notification_id={notification_id}
  &status={status}
  &substatus={substatus}
  &t={timestamp}
  &nonce={nonce}
  &username={username}
  &h={hash}

Parameter	Description
`notification_id`	The notification identifier provided in the SSO request
`status`	Status code indicating the type of event that occurred
`substatus`	Contextual status code providing additional detail
`t`	Timestamp of signature generation. Epoch Unix timestamp in seconds
`nonce`	The nonce provided in the SSO request, returned unchanged
`username`	Your provisioned client username
`h`	The digital signature of the request

The callback does not echo partyId. Where you need to correlate a callback to a specific party, carry that correlation in the nonce.

Validating the callback signature

As an additional layer of security, you may validate the hash on the response. Perform hash generation steps 1–5 above, using the response URL to build the request URL in step 2 without the h parameter, then confirm the two hashes are identical.

var requestUrl = $"{return_url}?notification_id={notification_id}"
    + $"&status={status}&substatus={substatus}"
    + $"&t={timestamp}&nonce={nonce}&username={username}";

Status codes

Code	Meaning	Sub codes
`2200`	Session completed and funded successfully	`201` Card · `202` ACH · `203` Check · `204` PayPal
`2400`	Session was unsuccessful	`401` Configuration error · `402` Transaction canceled, terminated or expired · `403` Transaction already completed · `404` Web session expired · `405` Terminated — max account verification attempts exceeded · `406` Terminated — max processing attempts exceeded · `407` Suspended due to OFAC
`2401`	An authorization error has occurred	—
`2404`	The customer experienced a 404 Page Not Found error	—
`2500`	The customer experienced a system error	—

405 and 406 mean the disbursement has been terminated and cannot be resumed. Treat it as closed. If the payee still needs to be paid, stage a new disbursement or fall back to another payment method.

These are SSO callback codes and are distinct from the API status codes returned in a transaction response. See Status Codes.

Prerequisites

A portal of your own that authenticates the customer before the handoff.
A provisioned client username and secret for SSO signing.
A return URL registered with Ingo in advance. Requests carrying an unregistered return URL are rejected.
A server-side endpoint that builds and signs the redirect — the secret must never reach the browser.
You are already live or in-flight on Notify — Classic or Notify — Managed Parties. SSO is a feature add, not a standalone integration.

Testing

During UAT, validate the full round trip: that a signed redirect lands the customer in the DPC with no authentication challenge presented, that the callback returns to your return URL with the expected status and substatus, and that your hash validation accepts a genuine callback. Confirm your redirect is issued inside the timestamp window, and test the failure paths — an expired timestamp and a tampered signature should both be rejected. For Notify — Managed Parties, test each party role separately. Confirm a recipient and an approver can each enter with their own partyId, and that the approval completes end to end. Your Integration Manager provides a test plan and validation support.

Explore

Guides

Documentation

Trust & Compliance

When to use it

Good fit

Use authentication questions instead

How it works

Multi-party disbursements

Request

URL values

Parameters

Hash generation

URL redirect

Response callback

Validating the callback signature

Status codes

Prerequisites

Testing

​When to use it

Good fit

Use authentication questions instead

​How it works

​Multi-party disbursements

​Request

​URL values

​Parameters

​Hash generation

​URL redirect

​Response callback

​Validating the callback signature

​Status codes

​Prerequisites

​Testing

When to use it

How it works

Multi-party disbursements

Request

URL values

Parameters

Hash generation

URL redirect

Response callback

Validating the callback signature

Status codes

Prerequisites

Testing