Skip to content

Payment methods · SIMULATORs

Test card payments without a real acquirer

Route a terminal to the Simplified Simulator (simplified-card-simulator) or the Simulator (card-simulator) and Finrelay answers card requests itself. Approve, decline, redirect or form-submit, chosen by the test card or by metadata.

Simplified Simulator or Simulator Control the outcome
Outcome metadata
  • response_code result Approved or declined (default approved)
  • simulate_redirect redirect Browser goes to your URL
  • simulate_form_submit form_submit Auto-submitting form

Metadata values are strings. Unknown response_code values fall back to approved.

The card simulators stand in for a card acquirer in UAT. They never contact a card network: the result comes from the request itself, so the same request always gives the same outcome.

This page calls them the Simplified Simulator and the Simulator.

Simplified Simulator or Simulator

Simplified Simulator Simulator
Provider service simplified-card-simulator card-simulator
Use it for Everyday integration testing. Pair it with the 3DS Authentication Simulator and pick the outcome with a test card. Advanced cases: 3DS action-required, declined 3DS authentication, and the Google Pay and Apple Pay redirect page.
Payment methods card, saved_card, google-pay, apple-pay card, saved_card, google-pay, apple-pay

Both are card providers, so both take the same authorize and manage requests. They differ only in what authorize can return.

Authorize behaviour Simplified Simulator Simulator
Result (approved or declined) Yes Yes
simulate_redirect Yes Yes
simulate_form_submit Yes Yes
3DS action required (simulate_authentication_required) No Yes
Declined 3DS authentication No Yes
Google Pay and Apple Pay redirect page No Yes
Reconciliation test extension No Yes

In short: the Simplified Simulator has three outcomes (result, redirect, form-submit) and never goes through 3DS itself. The Simulator has the same three plus the 3DS and wallet-redirect branches.

Wallets on the Simplified Simulator

google-pay and apple-pay are still offered by the Simplified Simulator. They get no special redirect page: the request is handled like any other, from its metadata.

Default routing

Test configurations are routed to the Simplified Simulator by default. If you need to test extended behaviours (3DS action-required, a declined 3DS authentication, or the Google Pay and Apple Pay redirect page), please let us know and we will route you to the Simulator.

Control the outcome

Send these keys in the request's metadata. All values are strings.

Key Effect
response_code A gateway processing code, for example TRX_STATUS_DECLINED. Default TRX_STATUS_APPROVED.
response_message Message returned with the result. Default approved.
approval_code, reference_number Returned as sent. Random six letters if omitted.
payment_provider_status, payment_provider_response_code, payment_provider_response_message Returned as sent. Default approved.
simulate_redirect Returns a redirect to this URL instead of a result.
simulate_form_submit JSON string {"url": "...", "data": {...}}. Returns a form_submit.

If both simulate_redirect and simulate_form_submit are set, simulate_redirect wins.

Common response_code values:

Value Status Code
TRX_STATUS_APPROVED APPROVED 0000
TRX_STATUS_DECLINED DECLINED 1000
TRX_STATUS_FAILED DECLINED 1001
TRX_STATUS_PENDING PENDING 1002
TRX_STATUS_CANCELED CANCELED 1003
TRX_STATUS_DECLINED_INSUFFICIENT_FUNDS DECLINED 1004

Capture, void and refund

Management requests (capture, void, refund) are answered from the transaction's metadata with the same keys as above. With no metadata they are approved.

Test cards

With the Simplified Simulator, a test card number picks the outcome, so no metadata is needed. For example, 4000000000000002 (Visa) or 5200000000000007 (Mastercard) gives a frictionless, approved payment. The full list of scenarios and card numbers is on the 3DS Authentication Simulator page.

These cards need the simplified authentication simulator

The card number is read by the simplified-authentication-simulator authentication service on the terminal, paired with the simplified-card-simulator card provider. The card provider itself answers from metadata.

Test card for the Simulator

The Simulator does not map card numbers to outcomes: any valid-format card works, and the result comes from the request metadata. For 3DS, the authentication outcome comes from the simulated_flow metadata of the full 3DS simulator (default VERSIONING_FINGERPRINT_Y_CHALLENGE, a challenge).

A card you can use:

Card number CVV Expiry
4111111111111111 123 10/2030

With no simulated_flow, this card gets the default challenge flow. See Advanced: metadata-driven simulator for the other simulated_flow values.