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)

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

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

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

​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

Authorization header format

Building the signature — step by step

Full request example

Environments

Common errors

Implementation notes