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.

​
Sandbox Environment

Your sandbox mirrors production behavior including payment routing logic, risk management services, OFAC screening, and webhook delivery. Sandbox credentials and velocity limits are provisioned during onboarding.
Sandbox velocity limits are client-specific and configured by your Ingo integration manager during onboarding.

​
Test Categories

CategoryDescriptionHow to initiate
Self-ServiceComplete independently in the sandbox at your own paceYour sandbox credentials
ControlledRequires an enablement flag or pre-loaded test accountsContact your integration manager to schedule
GuidedLive session with your Ingo integration team recommendedContact your integration manager to schedule

​
How IngoPay Testing Works

IngoPay is a synchronous REST API. Verification and process results are returned directly in the API response — your integration handles routing logic based on the status code returned. A small number of scenarios (OFAC screening, returned payments) also generate asynchronous gateway.* webhook events after the initial response.

​
Self-Service Scenarios

Successful Account Tokenization

Category: Self-ServiceScenario: Submit a Verify request with a valid test account. The account is tokenized and a customer_account_token is returned for use in subsequent Process requests.API call: POST /gateway/verifySuccess criteria:
  • Response status: 100
  • customer_account_token present in response data
Key response fields to verify:
FieldExpected
status100
client_messageSuccess
data.customer_account_tokenNon-null string

Idempotent Verify Request

Category: Self-ServiceScenario: Submit a second Verify request using the customer_account_token returned from a prior successful verify. Confirms the token can be reused without re-entering account credentials.API call: POST /gateway/verifySuccess criteria: Response status: 101Key response fields to verify:
FieldExpected
status101
client_messageSuccess - Idempotent

Account Not Available for Disbursement

Category: Self-ServiceScenario: Submit a Verify or Process request with an account number not supported for disbursement. Confirms correct handling of unsupported account types.Success criteria: Response status: 700Key response fields to verify:
FieldExpected
status700
client_messageAccount not currently available for processing via Ingo

Check Digit Failure

Category: Self-ServiceScenario: Submit a Verify request with a malformed card account number that fails the check digit algorithm.Success criteria: Response status: 1042Key response fields to verify:
FieldExpected
status1042
client_messageCheck Digit Failure - Please check account number and try again

Successful Payment

Category: Self-ServiceScenario: Submit a Process request using a valid customer_account_token. The payment is processed successfully.API call: POST /gateway/processApplicable account types: CA, AC, PD, BP, CKSuccess criteria: Response status: 100Key response fields to verify:
FieldExpected
status100
client_messageSuccess
data.transaction_idNon-null string

Idempotent Process Request

Category: Self-ServiceScenario: Resubmit the same Process request using the same participant_unique_id1. Confirms duplicate payment protection is working correctly.Success criteria: Response status: 101Key response fields to verify:
FieldExpected
status101
client_messageSuccess - Idempotent

Velocity Limit Errors

Category: Self-ServiceScenario: Submit Process requests that exceed your configured velocity limits. Confirms your system handles each limit condition gracefully.Success criteria: Appropriate status code returned for each limit conditionKey response fields to verify:
ScenarioExpected Status
Amount below issuer minimum603
Exceeds single transaction limit711
Exceeds daily amount limit712
Exceeds weekly amount limit713
Exceeds monthly amount limit714
Exceeds max transactions per month715
Exceeds 15-day amount limit716

​
Controlled Scenarios

The following scenarios require your Ingo integration manager to enable a specific configuration or pre-load test accounts before testing can begin. Contact your integration team to schedule these.

AVS Soft Fail

Category: ControlledScenario: Submit a Verify request with a card account configured to trigger an AVS soft failure. The verification proceeds and the account is tokenized. Your system receives the soft-fail status code in the Verify response.Success criteria: Verify response contains AVS soft-fail status code; customer_account_token presentKey response fields to verify:
FieldExpected
status111–119 range
data.customer_account_tokenNon-null string

AVS Decline

Category: ControlledScenario: Submit a Verify request with a card account configured to trigger an AVS hard decline. The request fails and no token is issued.Success criteria: Verify response returns AVS decline status code; no token issuedKey response fields to verify:
FieldExpected
status750 or 751

CVV Decline

Category: ControlledScenario: Submit a Verify request with a card account configured to trigger a CVV hard decline.Success criteria: Verify response returns CVV decline status code; no token issuedKey response fields to verify:
FieldExpected
status765

ANV / NAV Soft Fail

Category: ControlledScenario: Submit a Verify request with an ACH account configured to trigger a soft failure on account number validation (ANV) or name/address validation (NAV). The verification proceeds and the account is tokenized. Your system receives the soft-fail status code in the Verify response.Success criteria: Verify response contains soft-fail status code; customer_account_token presentKey response fields to verify:
FieldExpected
status122–126 range (ANV/NAV soft fail)
data.customer_account_tokenNon-null string

RNV / ANV / NAV Hard Decline

Category: ControlledScenario: Submit a Verify request with an ACH account configured to trigger a hard decline on routing number (RNV), account number (ANV), or name/address (NAV) validation. The request fails and no token is issued.Success criteria: Verify response returns applicable decline status code; no token issuedKey response fields to verify:
ScenarioExpected Status
RNV Declined743
ANV Declined767, 768, or 769
NAV Declined776, 777, 778, or 779

OFAC Suspended — Cleared (Payment Success)

Category: ControlledScenario: Submit a Process request using a test account configured to trigger an OFAC hit. The initial Process response returns status: 130 confirming OFAC suspension. After OFAC review, the transaction is cleared and payment completes.Success criteria: Process response status: 130; suspended and cleared webhooks fire; payment ultimately succeedsKey response fields to verify:
FieldExpected
status130
client_messageSuccess - OFAC Suspended
Key webhook sequence to verify:
#EventTopicExpected Status
1OFAC Suspendedgateway.transaction.recipient.verification.ofac.status.suspended1106
2OFAC Clearedgateway.transaction.recipient.verification.ofac.status.cleared1107

OFAC Failure — Transaction Terminated

Category: ControlledScenario: An OFAC suspension is reviewed and confirmed. The transaction is terminated.Success criteria: Process response status: 130; suspended and failure webhooks fireKey webhook sequence to verify:
#EventTopicExpected Status
1OFAC Suspendedgateway.transaction.recipient.verification.ofac.status.suspended1106
2OFAC Failuregateway.transaction.recipient.verification.ofac.status.failure1108
Mocked response testing requires pre-loaded test accounts provisioned by your Ingo integration manager. These scenarios simulate issuer declines, application errors, and edge cases not reachable through standard sandbox requests.

Issuer Decline Scenarios

Category: ControlledScenario: Submit Process requests using pre-loaded test accounts that simulate issuer decline conditions — insufficient funds, do not honor, invalid account, stolen card, restricted card, transaction limits, and other issuer-specific declines.Success criteria: Appropriate decline status code returned for each scenario (851–865 range)

Application Error Scenarios

Category: ControlledScenario: Submit Process requests using pre-loaded test accounts that simulate Ingo application error conditions — transaction failures, routing network errors, validation errors, and timeout scenarios.Success criteria: Appropriate error status code returned for each scenario (400–999 range)

Pending and In-Progress Responses

Category: ControlledScenario: Submit Process requests that simulate a pending issuer response (102) or an idempotent in-progress state (104). Confirms your system handles non-terminal success states correctly.Success criteria:
ScenarioExpected Status
Pending issuer response102
Idempotent — processing in progress104
Retail card-present scenarios apply only to clients configured for retail processing. Contact your integration manager to confirm your configuration before running these tests.

Retail Velocity Limits

Category: ControlledScenario: Submit Process requests that exceed retail store-level velocity limits — max daily transaction amount and max daily transaction count per store.Success criteria: Appropriate error response returned for each limit condition

Store Not Authorized

Category: ControlledScenario: Submit a request for a transaction type not authorized for the store configuration.Success criteria: Appropriate error response indicating unauthorized transaction type

Card Swipe / Track Data Errors

Category: ControlledScenario: Submit a Process request that requires track data without providing it, or with invalid track1/track2 data. Confirms your system handles track data validation errors.Success criteria: Appropriate error response for each track data condition

​
Guided Scenarios

The following scenarios require coordination with your Ingo integration team. Contact your integration manager to schedule a guided session.

Unauthorized Account Type

Category: GuidedScenario: Submit a Process request for an account type your participant configuration does not permit.Success criteria: Appropriate error response returned

Insufficient Funds

Category: GuidedScenario: Submit a Process request that fails due to insufficient funds in the issuer network.Success criteria: Appropriate decline response returned

Destination Disabled

Category: GuidedScenario: Submit a Process request for a destination that has been disabled.Success criteria: Appropriate error response returned

Account Not Available — Expired Token

Category: GuidedScenario: Submit a Process request for an account that is no longer supported or whose token has expired.Success criteria: Appropriate error response returned

Issuer Return Transaction

Category: GuidedScenario: A previously completed payment is returned by the issuer. Confirms your system correctly handles the returned payment webhook and updates your records.Success criteria: Returned payment webhook received and processed correctlyKey webhook sequence to verify:
#EventTopicExpected Status
—Payment Returnedgateway.transaction.recipient.payment.status.returned1114

​
Webhook Events Reference

IngoPay API responses are synchronous — most results are returned directly in the API response. The following webhook events fire asynchronously for a small number of scenarios.
EventTopicExpected Status
OFAC Suspendedgateway.transaction.recipient.verification.ofac.status.suspended1106
OFAC Clearedgateway.transaction.recipient.verification.ofac.status.cleared1107
OFAC Failuregateway.transaction.recipient.verification.ofac.status.failure1108
EventTopicExpected Status
Payment Returnedgateway.transaction.recipient.payment.status.returned1114
Check Issuedgateway.transaction.recipient.payment.status.check.issued100
Check Paidgateway.transaction.recipient.payment.status.check.paid100
Check Canceledgateway.transaction.recipient.payment.status.check.canceled100
Check Stoppedgateway.transaction.recipient.payment.status.check.stopped100
Check Returnedgateway.transaction.recipient.status.payment.check.returned1114