Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

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.
ProductAuth mechanismAdditional requirement
IngoPay APIHMAC-SHA512—
Notify — ClassicHMAC-SHA512—
Notify — Managed PartiesHMAC-SHA512—
Embedded Account CaptureHMAC-SHA512 (server-side only)The iFrame SDK handles browser-side session auth automatically — no additional signing required from the client
Banking PlatformHMAC-SHA512 + API keyAn 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

CredentialDescription
usernameIdentifies your integration in the Authorization header
secretUsed locally to sign each request. Never transmitted.
participant_idNumeric 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=="
ParameterValue
usernameYour Ingo-issued username
algorithmAlways hmac-sha512
headersSpace-separated list of signed header names (see below)
signatureBase64-encoded HMAC-SHA512 signature (see below)

​
Building the signature — step by step

1

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
2

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.
3

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
4

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

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

ProductSandboxProduction
IngoPay APIhttps://payapi-sandbox.ingo.moneyhttps://payapi.ingo.money
Notify — Classic & Managed Partieshttps://payapi-sandbox.ingo.moneyhttps://payapi.ingo.money
Embedded Account Capturehttps://iip-session-management-uat.ingo.moneyhttps://iip-session-management.ingo.money
Banking Platformhttps://api.sdev.banking.ingopayments.tech/api/v4https://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

ErrorCauseFix
401 UnauthorizedInvalid signatureVerify secret, signature string construction, and RAW (not hex) HMAC output
401 Clock skewX-Date outside ±300s windowSync your server clock with NTP
400 Body hash mismatchContent-sha512 doesn’t match bodyRecompute hash from the exact body bytes being sent
400 Missing headerRequired header absentEnsure 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