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

# Testing

> Scenario-based testing guide for IngoPay API direct payment integrations — Verify, Process, risk management, and payment error handling.

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

<Info>
  Sandbox velocity limits are client-specific and configured by your Ingo integration manager during onboarding.
</Info>

***

## Test Categories

| Category         | Description                                              | How to initiate                              |
| ---------------- | -------------------------------------------------------- | -------------------------------------------- |
| **Self-Service** | Complete independently in the sandbox at your own pace   | Your sandbox credentials                     |
| **Controlled**   | Requires an enablement flag or pre-loaded test accounts  | Contact your integration manager to schedule |
| **Guided**       | Live session with your Ingo integration team recommended | Contact 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

<AccordionGroup>
  <Accordion title="Verify API">
    <Card title="Successful Account Tokenization" icon="credit-card">
      **Category:** Self-Service

      **Scenario:** 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/verify`

      **Success criteria:**

      * Response `status: 100`
      * `customer_account_token` present in response data

      **Key response fields to verify:**

      | Field                         | Expected        |
      | ----------------------------- | --------------- |
      | `status`                      | `100`           |
      | `client_message`              | `Success`       |
      | `data.customer_account_token` | Non-null string |
    </Card>

    <Card title="Idempotent Verify Request" icon="rotate">
      **Category:** Self-Service

      **Scenario:** 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/verify`

      **Success criteria:** Response `status: 101`

      **Key response fields to verify:**

      | Field            | Expected               |
      | ---------------- | ---------------------- |
      | `status`         | `101`                  |
      | `client_message` | `Success - Idempotent` |
    </Card>

    <Card title="Account Not Available for Disbursement" icon="ban">
      **Category:** Self-Service

      **Scenario:** 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: 700`

      **Key response fields to verify:**

      | Field            | Expected                                                  |
      | ---------------- | --------------------------------------------------------- |
      | `status`         | `700`                                                     |
      | `client_message` | `Account not currently available for processing via Ingo` |
    </Card>

    <Card title="Check Digit Failure" icon="circle-xmark">
      **Category:** Self-Service

      **Scenario:** Submit a Verify request with a malformed card account number that fails the check digit algorithm.

      **Success criteria:** Response `status: 1042`

      **Key response fields to verify:**

      | Field            | Expected                                                          |
      | ---------------- | ----------------------------------------------------------------- |
      | `status`         | `1042`                                                            |
      | `client_message` | `Check Digit Failure - Please check account number and try again` |
    </Card>
  </Accordion>

  <Accordion title="Process API">
    <Card title="Successful Payment" icon="bolt">
      **Category:** Self-Service

      **Scenario:** Submit a Process request using a valid `customer_account_token`. The payment is processed successfully.

      **API call:** `POST /gateway/process`

      **Applicable account types:** CA, AC, PD, BP, CK

      **Success criteria:** Response `status: 100`

      **Key response fields to verify:**

      | Field                 | Expected        |
      | --------------------- | --------------- |
      | `status`              | `100`           |
      | `client_message`      | `Success`       |
      | `data.transaction_id` | Non-null string |
    </Card>

    <Card title="Idempotent Process Request" icon="rotate">
      **Category:** Self-Service

      **Scenario:** Resubmit the same Process request using the same `participant_unique_id1`. Confirms duplicate payment protection is working correctly.

      **Success criteria:** Response `status: 101`

      **Key response fields to verify:**

      | Field            | Expected               |
      | ---------------- | ---------------------- |
      | `status`         | `101`                  |
      | `client_message` | `Success - Idempotent` |
    </Card>

    <Card title="Velocity Limit Errors" icon="gauge">
      **Category:** Self-Service

      **Scenario:** 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 condition

      **Key response fields to verify:**

      | Scenario                           | Expected Status |
      | ---------------------------------- | --------------- |
      | Amount below issuer minimum        | `603`           |
      | Exceeds single transaction limit   | `711`           |
      | Exceeds daily amount limit         | `712`           |
      | Exceeds weekly amount limit        | `713`           |
      | Exceeds monthly amount limit       | `714`           |
      | Exceeds max transactions per month | `715`           |
      | Exceeds 15-day amount limit        | `716`           |
    </Card>
  </Accordion>
</AccordionGroup>

***

## Controlled Scenarios

<Warning>
  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.
</Warning>

<AccordionGroup>
  <Accordion title="Card — AVS & CVV Risk Management">
    <Card title="AVS Soft Fail" icon="location-crosshairs">
      **Category:** Controlled

      **Scenario:** 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` present

      **Key response fields to verify:**

      | Field                         | Expected        |
      | ----------------------------- | --------------- |
      | `status`                      | `111–119` range |
      | `data.customer_account_token` | Non-null string |
    </Card>

    <Card title="AVS Decline" icon="location-dot-slash">
      **Category:** Controlled

      **Scenario:** 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 issued

      **Key response fields to verify:**

      | Field    | Expected       |
      | -------- | -------------- |
      | `status` | `750` or `751` |
    </Card>

    <Card title="CVV Decline" icon="shield-slash">
      **Category:** Controlled

      **Scenario:** 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 issued

      **Key response fields to verify:**

      | Field    | Expected |
      | -------- | -------- |
      | `status` | `765`    |
    </Card>
  </Accordion>

  <Accordion title="ACH — Account Verification">
    <Card title="ANV / NAV Soft Fail" icon="building-columns">
      **Category:** Controlled

      **Scenario:** 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` present

      **Key response fields to verify:**

      | Field                         | Expected                            |
      | ----------------------------- | ----------------------------------- |
      | `status`                      | `122–126` range (ANV/NAV soft fail) |
      | `data.customer_account_token` | Non-null string                     |
    </Card>

    <Card title="RNV / ANV / NAV Hard Decline" icon="ban">
      **Category:** Controlled

      **Scenario:** 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 issued

      **Key response fields to verify:**

      | Scenario     | Expected Status               |
      | ------------ | ----------------------------- |
      | RNV Declined | `743`                         |
      | ANV Declined | `767`, `768`, or `769`        |
      | NAV Declined | `776`, `777`, `778`, or `779` |
    </Card>
  </Accordion>

  <Accordion title="OFAC Screening">
    <Card title="OFAC Suspended — Cleared (Payment Success)" icon="flag">
      **Category:** Controlled

      **Scenario:** 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 succeeds

      **Key response fields to verify:**

      | Field            | Expected                   |
      | ---------------- | -------------------------- |
      | `status`         | `130`                      |
      | `client_message` | `Success - OFAC Suspended` |

      **Key webhook sequence to verify:**

      | # | Event          | Topic                                                              | Expected Status |
      | - | -------------- | ------------------------------------------------------------------ | --------------- |
      | 1 | OFAC Suspended | `gateway.transaction.recipient.verification.ofac.status.suspended` | 1106            |
      | 2 | OFAC Cleared   | `gateway.transaction.recipient.verification.ofac.status.cleared`   | 1107            |
    </Card>

    <Card title="OFAC Failure — Transaction Terminated" icon="triangle-exclamation">
      **Category:** Controlled

      **Scenario:** An OFAC suspension is reviewed and confirmed. The transaction is terminated.

      **Success criteria:** Process response `status: 130`; suspended and failure webhooks fire

      **Key webhook sequence to verify:**

      | # | Event          | Topic                                                              | Expected Status |
      | - | -------------- | ------------------------------------------------------------------ | --------------- |
      | 1 | OFAC Suspended | `gateway.transaction.recipient.verification.ofac.status.suspended` | 1106            |
      | 2 | OFAC Failure   | `gateway.transaction.recipient.verification.ofac.status.failure`   | 1108            |
    </Card>
  </Accordion>

  <Accordion title="Process — Mocked Responses">
    <Note>
      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.
    </Note>

    <Card title="Issuer Decline Scenarios" icon="credit-card">
      **Category:** Controlled

      **Scenario:** 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)
    </Card>

    <Card title="Application Error Scenarios" icon="triangle-exclamation">
      **Category:** Controlled

      **Scenario:** 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)
    </Card>

    <Card title="Pending and In-Progress Responses" icon="clock">
      **Category:** Controlled

      **Scenario:** 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:**

      | Scenario                            | Expected Status |
      | ----------------------------------- | --------------- |
      | Pending issuer response             | `102`           |
      | Idempotent — processing in progress | `104`           |
    </Card>
  </Accordion>

  <Accordion title="Retail Card-Present">
    <Note>
      Retail card-present scenarios apply only to clients configured for retail processing. Contact your integration manager to confirm your configuration before running these tests.
    </Note>

    <Card title="Retail Velocity Limits" icon="store">
      **Category:** Controlled

      **Scenario:** 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
    </Card>

    <Card title="Store Not Authorized" icon="ban">
      **Category:** Controlled

      **Scenario:** Submit a request for a transaction type not authorized for the store configuration.

      **Success criteria:** Appropriate error response indicating unauthorized transaction type
    </Card>

    <Card title="Card Swipe / Track Data Errors" icon="credit-card">
      **Category:** Controlled

      **Scenario:** 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
    </Card>
  </Accordion>
</AccordionGroup>

***

## Guided Scenarios

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

<AccordionGroup>
  <Accordion title="Process Errors">
    <Card title="Unauthorized Account Type" icon="ban">
      **Category:** Guided

      **Scenario:** Submit a Process request for an account type your participant configuration does not permit.

      **Success criteria:** Appropriate error response returned
    </Card>

    <Card title="Insufficient Funds" icon="money-bill-slash">
      **Category:** Guided

      **Scenario:** Submit a Process request that fails due to insufficient funds in the issuer network.

      **Success criteria:** Appropriate decline response returned
    </Card>

    <Card title="Destination Disabled" icon="circle-stop">
      **Category:** Guided

      **Scenario:** Submit a Process request for a destination that has been disabled.

      **Success criteria:** Appropriate error response returned
    </Card>

    <Card title="Account Not Available — Expired Token" icon="credit-card">
      **Category:** Guided

      **Scenario:** Submit a Process request for an account that is no longer supported or whose token has expired.

      **Success criteria:** Appropriate error response returned
    </Card>
  </Accordion>

  <Accordion title="Returned Payments">
    <Card title="Issuer Return Transaction" icon="arrow-rotate-left">
      **Category:** Guided

      **Scenario:** 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 correctly

      **Key webhook sequence to verify:**

      | # | Event            | Topic                                                   | Expected Status |
      | - | ---------------- | ------------------------------------------------------- | --------------- |
      | — | Payment Returned | `gateway.transaction.recipient.payment.status.returned` | 1114            |
    </Card>
  </Accordion>
</AccordionGroup>

***

## Webhook Events Reference

<Info>
  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.
</Info>

<AccordionGroup>
  <Accordion title="OFAC Events">
    | Event          | Topic                                                              | Expected Status |
    | -------------- | ------------------------------------------------------------------ | --------------- |
    | OFAC Suspended | `gateway.transaction.recipient.verification.ofac.status.suspended` | 1106            |
    | OFAC Cleared   | `gateway.transaction.recipient.verification.ofac.status.cleared`   | 1107            |
    | OFAC Failure   | `gateway.transaction.recipient.verification.ofac.status.failure`   | 1108            |
  </Accordion>

  <Accordion title="Payment Events">
    | Event            | Topic                                                         | Expected Status |
    | ---------------- | ------------------------------------------------------------- | --------------- |
    | Payment Returned | `gateway.transaction.recipient.payment.status.returned`       | 1114            |
    | Check Issued     | `gateway.transaction.recipient.payment.status.check.issued`   | 100             |
    | Check Paid       | `gateway.transaction.recipient.payment.status.check.paid`     | 100             |
    | Check Canceled   | `gateway.transaction.recipient.payment.status.check.canceled` | 100             |
    | Check Stopped    | `gateway.transaction.recipient.payment.status.check.stopped`  | 100             |
    | Check Returned   | `gateway.transaction.recipient.status.payment.check.returned` | 1114            |
  </Accordion>
</AccordionGroup>