Skip to main content
POST
/
gateway
/
process--retail
curl --request POST \
  --url https://payapi-sandbox.ingo.money/gateway/process--retail \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "participant_id": 12345,
  "account_type": "CA",
  "amount": 101,
  "customer_account_token": "ca875cce-58c0-46a0-8f14-676190cc7df6",
  "source_of_funds": 4,
  "recipient_phone": "1231231234",
  "participant_unique_id1": "fb746578-c4c3-498f-b398-1ff07b4fe2ff",
  "participant_unique_id2": "77d6b010-eab4-44dc-9a27-6ffa4838c9f2",
  "track1": "%B4111111111111111^ROCKETS/JOHNNY^2612101000000000000000000000000?",
  "track2": ";4111111111111111=26121010000000000000?",
  "store_id": "STORE-001",
  "clerk_id": "CLK-007",
  "terminal_id": "TERM-042",
  "retail_location": {
    "location_name": "ABC Retail",
    "location_id": "LOC-1234",
    "location_address": "100 Innovation Way",
    "location_city": "Anytown",
    "location_state": "GA",
    "location_zip": "00000"
  },
  "ledger": {
    "api_key": "lk_live_abc123xyz",
    "user_id": "usr_00456",
    "entity_type": "program",
    "entity_id": "ent_00789"
  },
  "timestamp": 1579832224,
  "version": 11
}
'
{
  "status": 100,
  "client_message": "Success",
  "data": {
    "estimated_posting_time": "Payment will post within 5 minutes.",
    "estimated_posting_date": "04/21/2026",
    "transaction_id": 2361541,
    "request_timestamp": 1579832290,
    "customer_account_token": "ca875cce-58c0-46a0-8f14-676190cc7df6",
    "participant_unique_id1": "fb746578-c4c3-498f-b398-1ff07b4fe2ff",
    "participant_unique_id2": "77d6b010-eab4-44dc-9a27-6ffa4838c9f2"
  },
  "time": "1.2044"
}

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.

Authorizations

​
Authorization
string
header
required

All requests must be authenticated using an HMAC-signed Authorization header. Ingo Money requires HMAC-SHA512 for all new integrations. SHA-512 provides a significantly larger internal state and output length than SHA-256, making it substantially more resistant to length-extension attacks and brute-force preimage attempts — properties that matter for financial API traffic where each request authorizes a real money movement.

Legacy integrations using HMAC-SHA256 remain supported but are encouraged to upgrade. SHA-256 continues to meet the current minimum security bar; however, upgrading to SHA-512 eliminates an entire class of potential vulnerabilities before they become exploitable, and aligns with NIST guidance recommending SHA-2 family algorithms with 256-bit security strength or greater for long-term use. Contact your Ingo integration manager to coordinate an algorithm upgrade.

MD5 and SHA-1 are not accepted under any circumstances. Requests signed with either algorithm will be rejected.

Authorization header format:

Authorization: hmac username="YOUR_HMAC_USERNAME", algorithm="hmac-sha512", headers="request-line x-date content-type content-length content-sha512", signature="BASE64_SIGNATURE"

Credentials provisioned by your Ingo integration manager:

  • HMAC username — identifies your integration in the Authorization header username field. Distinct from your participant identifier.

  • HMAC secret — provisioned by your Ingo integration manager. The private key used to compute the signature. Never transmit this value — store it in a secrets manager or environment variable, never in source code.

  • Participant identifier — a separate value used to identify your account within the API request payload. The name and placement differs by product family. Both the HMAC username and participant identifier are provisioned at onboarding — do not substitute one for the other.

  • API key — required for select product families as an additional per-request credential. See product-specific documentation for applicability.

See the Ingo API Authentication Guide for the complete string-to-sign construction, body hashing requirements, and timestamp validation rules.

Body

application/json

store_id, clerk_id, and terminal_id are required when the client is configured as a retail participant. retail_location{} is additionally required for CA account type when the client is configured with the retail location flag. Both are determined by client-level backend configuration — contact your Ingo integration manager to confirm your setup.

​
participant_id
integer
required

Unique participant identifier assigned by Ingo.

Example:

12345

​
account_type
enum<string>
required

CA = card-present (debit or credit), BP = bill payment card-present.

Available options:
CA,
BP
Minimum string length: 1
Example:

"CA"

​
amount
number<float>
required

Amount of the transaction.

Required range: x >= 0.01
Example:

101

​
customer_account_token
string
required

Token representing the account number and customer data as provided in the response from a previous Verify API call.

Required string length: 1 - 255
Example:

"ca875cce-58c0-46a0-8f14-676190cc7df6"

​
source_of_funds
enum<integer>
required

Funding source indicator: 1 = Cash, 2 = Check, 3 = Combo of Cash & Check, 4 = Corp Disbursement.

Available options:
1,
2,
3,
4
Example:

4

​
participant_unique_id1
string
required

Participant assigned transaction ID for the process request. Value must be unique and may not contain NPI data. Used for idempotency — a duplicate value returns an idempotent response without initiating a new push request. Appears on daily reconciliation reports.

Required string length: 1 - 255
Example:

"fb746578-c4c3-498f-b398-1ff07b4fe2ff"

​
timestamp
integer<int64>
required

Unix timestamp of the request.

Example:

1579832224

​
version
integer
required

API version of the request. Current version is 11.

Example:

11

​
recipient_phone
string | null

10-digit recipient phone number.

Maximum string length: 10
Example:

"1231231234"

​
participant_unique_id2
string | null

Optional second participant assigned transaction ID. Does not appear on daily reconciliation reports.

Maximum string length: 255
Example:

"77d6b010-eab4-44dc-9a27-6ffa4838c9f2"

​
track1
string | null

URL-encoded Track 1 data from and including the beginning sentinel to and including the ending sentinel. Captured at point of sale.

Maximum string length: 255
Pattern: ^(%B)([0-9]{12,22})([/^])([\s\S]*)([/^])([0-9]{2})([0-9]{2})([0-9]*)([?])$
Example:

"%B4111111111111111^ROCKETS/JOHNNY^2612101000000000000000000000000?"

​
track2
string | null

Track 2 data from and including the beginning sentinel to and including the ending sentinel. Captured at point of sale.

Maximum string length: 255
Pattern: ^(;)([0-9]{12,22})(=)([0-9]{2})([0-9]{2})([0-9])*([?])$
Example:

";4111111111111111=26121010000000000000?"

​
store_id
string

Client assigned store ID. Required when the client is configured as a retail participant (retail flag enabled in client configuration).

Required string length: 1 - 255
Example:

"STORE-001"

​
clerk_id
string

Client assigned clerk ID. Required when the client is configured as a retail participant (retail flag enabled in client configuration).

Required string length: 1 - 255
Example:

"CLK-007"

​
terminal_id
string

Client assigned terminal ID. Required when the client is configured as a retail participant (retail flag enabled in client configuration).

Required string length: 1 - 255
Example:

"TERM-042"

​
retail_location
object

Client assigned retail location information. Required for CA account type when the client is configured with the retail location flag (retail_object flag enabled in client configuration). This flag is independent of the retail flag and must be confirmed with your Ingo integration manager. Not applicable for BP account type.

​
ledger
object

Required for clients configured for ledger service. Exclude entirely if not applicable to your integration.

Response

Payment accepted successfully

​
status
integer

Numeric code describing the status of the API request. 100 = Success.

Example:

100

​
client_message
string

Text description associated with the status code.

Example:

"Success"

​
data
object
​
time
string

Time in seconds to complete the request.

Example:

"1.2044"