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 Finavexo answers card requests itself. Approve, decline, redirect or form-submit, chosen by the test card or by metadata.

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, network-token card, saved_card, google-pay, apple-pay, network-token

Network Token

A network-token payment is handled like a card payment, with no 3DS step, whether or not you send an ECI or a cryptogram. The outcome comes from the request metadata; the test cards do not apply.

POST /api/transactions/authorize
{
  "terminal_id": "your-terminal-id",
  "payment_method": {
    "type": "network-token",
    "data": {
      "encrypted_token_number": "...",
      "encrypted_expiration_month": "...",
      "encrypted_expiration_year": "...",
      "encrypted_cryptogram": "...",
      "eci": "05",
      "source": "apple-pay"
    }
  },
  "metadata": {}
}

Encrypt the token fields with your merchant public key, as for a card. Any number that passes the Luhn check works as the token number, for example 4111111111111111, if its card brand is enabled on your terminal. Send the expiry month as 1โ€“12 and the year with four digits. With empty metadata the payment is approved; add the metadata keys to get another outcome. See Network Token for every field.

source (for example apple-pay) is only a label. A network-token payment never gets the Google Pay and Apple Pay redirect page: that page appears only for the google-pay and apple-pay payment method types, and only on the Simulator.

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.