Payment mocking

Testing is a key step for development, CI/CD pipelines and preventing issues and bugs.

We treat testing as a first class citizen and aim to provide functionality for all the different levels of testing in the simplest possible manner.

Where Mocking Runs

Mocks are only available in the Nopan Sandbox environment.

Sandbox only → Mocking never touches live rails or moves funds.
Safe for CI/CD → You can run automated tests and manual flows without risk.
Real vs simulated → You decide whether to test end-to-end with the scheme or only against Nopan logic.

Mocking is designed to help you test integration with Nopan itself, as well as interactions with schemes via their sandbox environments. In production, mocks are disabled - all requests are routed to real payment providers.

Mocking Modes

When testing integrations with new payment schemes, it's important to test different outcomes (like success, failure, timeout, etc.). That is where mocking comes into the picture. Mocking is the process of imitating production resources in order to get predictable results.

Our platform supports two modes of mocking to help you simulate real-world scenarios during development and testing: Mock and Pass-through

Standard Mock mode

In this mode, no real payment provider is involved. We simulate the behavior of the provider based on your input.

You fully control the response (success, failure, timeout, etc.)

There is no external redirection or provider logic Great for local or isolated testing Fast and deterministic

tip

Use this when you want full control over the outcome and don't need to test the actual provider flow.

Pass-through mocking mode

Some payment schemes offer sandbox environments, but triggering specific outcomes in those sandboxes can be tricky — they often require obscure test values, codes, or timing-based tricks.

With Pass-Through Mocking, we simplify this:

You define the outcome you want (e.g. success, user cancel, failure) We handle the sandbox-specific setup behind the scenes (e.g. setting the correct redirect URLs, query parameters, or codes) The request is actually routed through the real provider's sandbox, giving you the full real-world flow Redirects, UI, and provider-specific behaviors are preserved

tip

Use this when you want to experience the real flow (including redirects, third-party UIs) without dealing with provider sandbox quirks.

Pass-through vs Mock

Feature

Pass-through

Mock

Used for

E2E, UI/Manual testing

Backend testing

Reach

Real scheme involved

Nopan only

Features

Full flow support, SCA redirects...

Overridable values, easy customization of responses

Override response values

Yes

Configurable flow

Yes

Default Sandbox behaviour

If no mock is set, the platform will go to the real scheme directly without any changes in the payloads following the default sandbox flow.

Mock time to live (TTL)

Mocks inside our platform last for 24 hours by default. Default green flows and values will be provided for requests that are not explicitly mocked. The mocks can also be configured to be available for a single request by setting the oneTime field in the mock request. In this case, the mock will be used for a single call for each of the payment steps.

How to use the mocking system

Select between PASSTHROUGH and MOCK type
Set the key type between PAYER_ID and CLIENT_TRANSACTION_ID
Set the status and the data expected in each of the steps for Payment flow to be tested

tip

Only steps that require mocking should be included in the request. Default values will be provided if a step is not explicitly mocked. See Mock Requests for a detailed description on the available fields for mocking.

tip

Ensures the requests to the Payment flow match the key value and type sent while setting the mock. See Payments Requests for more information on the API.

Example

The following configuration sets up a mock for the initiate step of the payment, to get status ACCEPTED and a specific code within statusInfo.

This mock would last 24 hours since oneTime is set to false, and only be used if the processingAccountId and clientTransactionId sent during the payment flow matches with the one in this mock request.

cURL -  POST /mock/set
curl -X POST https://api.nopan.com/mock/set \
  -H "Authorization: Bearer <access-token>" \
  -H "Idempotency-Key: 63c2e3f0-12aa-41bb-ae62-f3d91fdbb762" \
  -H "Signature: nopan_sig=<signature>" \
  -H "Signature-Input: nopan_sig=("@status");keyid="your-key-id";created=1766678793 \
  -H "Content-Type: application/json" \
  -d '{
  "processingAccountId": "merchant",
  "key": {
    "type": "CLIENT_TRANSACTION_ID",
    "value": "order123"
  },
  "type": "MOCK",
  "oneTime": false,
  "steps": {
    "initiate": {
      "status": "ACCEPTED",
      "providerDetails": {
        "providerTransactionId": "9c82132e-eb2a-491c-970d-47260d4122b0",
        "redirectUrl": "https://merchant.callback.com",
        "registeredAt": 1748505211886,
        "expiresAt": 1748505271887
      },
      "statusInfo": {
        "reasonCode": "-1",
        "message": "Awaiting user consent"
      }
    }
  }
}'

How to Trigger Mocking

To enable mocking, you must explicitly create a mock configuration using the Mock Requests API.

To summarize:

Choose between MOCK (simulate Nopan only) or PASSTHROUGH (real scheme sandbox with controlled outcomes)
Define the key (e.g. CLIENT_TRANSACTION_ID or PAYER_ID)
Specify the desired status and optional fields for each step (initiate, finalize, capture, etc.)
Call POST /mock/set in the sandbox environment

Once configured, any payment request in sandbox that matches your key will use the mock instead of the default flow. If no matching mock is found, the request follows the default sandbox behavior — routed to the scheme’s sandbox with no overrides.

Where Mocking Runs​

Mocking Modes​

Standard Mock mode​

Pass-through mocking mode​

Pass-through vs Mock​

Mock time to live (TTL)​

How to use the mocking system​

Example​

How to Trigger Mocking​