Skip to content
Better Payment

Test Cards and Sandbox Setup

Test your integration with the in-memory MockProvider or real provider sandbox environments.

Testing payments without moving real money can be done in two ways with better-payment:

  1. In-Memory Mock Provider (better-payment/testing): Best for unit tests, CI pipelines, and local development. It runs entirely in memory without network requests or external credentials. See Testing for the complete list of magic card numbers and test controls (failNext, networkErrorNext).
  2. Provider Sandbox (mode: 'sandbox'): Best for end-to-end verification against real provider test environments before going live.

In-Memory Mock Provider

For application tests, better-payment/testing provides MockProvider. It requires no API credentials and gives you deterministic outcomes using magic card numbers.

See Testing for full setup instructions, request examples, and the complete reference table of MOCK_CARDS (SUCCESS, INSUFFICIENT_FUNDS, CARD_DECLINED, THREEDS_REQUIRED, etc.).


Provider Sandbox Setup

When initializing betterPayment, set mode: 'sandbox'. In sandbox mode, each provider automatically connects to its sandbox endpoint:

import { betterPayment, iyzico, paytr, akbank, parampos } from 'better-payment';

const payment = betterPayment({
  mode: 'sandbox',
  providers: {
    iyzico: iyzico({
      apiKey: process.env.IYZICO_SANDBOX_API_KEY!,
      secretKey: process.env.IYZICO_SANDBOX_SECRET_KEY!,
    }),
    paytr: paytr({
      merchantId: process.env.PAYTR_SANDBOX_MERCHANT_ID!,
      merchantKey: process.env.PAYTR_SANDBOX_MERCHANT_KEY!,
      merchantSalt: process.env.PAYTR_SANDBOX_MERCHANT_SALT!,
    }),
    akbank: akbank({
      merchantSafeId: process.env.AKBANK_SANDBOX_MERCHANT_SAFE_ID!,
      terminalSafeId: process.env.AKBANK_SANDBOX_TERMINAL_SAFE_ID!,
      secretKey: process.env.AKBANK_SANDBOX_SECRET_KEY!,
    }),
    parampos: parampos({
      clientCode: process.env.PARAMPOS_SANDBOX_CLIENT_CODE!,
      clientUsername: process.env.PARAMPOS_SANDBOX_CLIENT_USERNAME!,
      clientPassword: process.env.PARAMPOS_SANDBOX_CLIENT_PASSWORD!,
      guid: process.env.PARAMPOS_SANDBOX_GUID!,
    }),
  },
});

See Installation for details on setting up environment variables.


iyzico Sandbox

Test Cards

Card NumberBrandExpected ResultExpiry DateCVC
5528790000000008MastercardSuccessful paymentAny future date123
4111111111111129VisaInsufficient funds (INSUFFICIENT_FUNDS)Any future date123

Both cards are the ones our nightly sandbox tests use. For the 3D Secure step (the verification code the sandbox asks for) and the full list of scenario cards, see the official iyzico Test Cards page.


PayTR Sandbox

  • Sandbox Endpoint: https://www.paytr.com (PayTR uses a unified endpoint; test_mode: 1 is sent automatically in sandbox mode)
  • Documentation: PayTR Developer Portal

Test Cards

Card NumberExpected ResultExpiry DateCVC
4355084355084358PayTR test card (used by our sandbox tests for BIN queries)Any future date000

With mode: 'sandbox', Better Payment sends test_mode=1 with every request. Set testMode in the provider config to override it. For more test cards and the 3D Secure test step, see the PayTR developer documentation.


Akbank Sandbox

  • Sandbox Endpoint: https://apipre.akbank.com/api/v1/payment/virtualpos
  • Documentation: Akbank API Portal

Akbank provides test cards and credentials with your test merchant account; ask your Akbank contact.


Parampos Sandbox

Parampos provides test cards, test credentials (Client Code, Username, Password, and GUID) and SOAP endpoints with your test merchant account; ask your Param contact.


Sipay Sandbox

Sipay's documentation lists a shared test merchant (app id, app secret and merchant key) and these test cards:

CardNumberExpiryCVV3D Secure code
Visa450803450803450912/30000000000
Mastercard540667540667540312/30000000000
Troy650170013908282612/30000000000

Other CVV values simulate bank errors: 510 insufficient funds, 050 do not honour, 330 expired card, 820 invalid CVV.