Authentication

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:

{
  "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)

Credential scope

Your HMAC credential is authorized for a specific set of participant_id values. A signed request is accepted only if the credential presented is authorized for the participant_id in that request — a valid signature for a participant you are not authorized for is rejected with HTTP 401. If your integration transacts for more than one participant, confirm with your Ingo integration manager that every credential-to-participant pair you use is provisioned before you go live.

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

Assemble required headers

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

Build the header string

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.

Build the signature string

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

Hash and encode the signature string

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==

Assemble the Authorization header

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

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

HTTP 401 and Ingo status code 401 are not the same failure. Everything in the table above is HTTP-level: the request was rejected before it reached transaction processing, and the response carries no Ingo status code. A 401 in the response.status field of an HTTP 200 reply means the opposite — your request authenticated successfully and was then rejected for its contents. See Status Codes.

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

Explore

Guides

Documentation

Trust & Compliance

Product-specific requirements

Banking Platform — API key

Credentials

Credential scope

Authorization header format

Building the signature — step by step

Full request example

Environments

Common errors

Implementation notes

​Product-specific requirements

​Banking Platform — API key

​Credentials

​Credential scope

​Authorization header format

​Building the signature — step by step

​Full request example

​Environments

​Common errors

​Implementation notes

Product-specific requirements

Banking Platform — API key

Credentials

Credential scope

Authorization header format

Building the signature — step by step

Full request example

Environments

Common errors

Implementation notes