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:
- 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). - 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
- Sandbox Endpoint:
https://sandbox-api.iyzipay.com - Documentation: iyzico Test Cards
Test Cards
| Card Number | Brand | Expected Result | Expiry Date | CVC |
|---|---|---|---|---|
5528790000000008 | Mastercard | Successful payment | Any future date | 123 |
4111111111111129 | Visa | Insufficient funds (INSUFFICIENT_FUNDS) | Any future date | 123 |
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: 1is sent automatically in sandbox mode) - Documentation: PayTR Developer Portal
Test Cards
| Card Number | Expected Result | Expiry Date | CVC |
|---|---|---|---|
4355084355084358 | PayTR test card (used by our sandbox tests for BIN queries) | Any future date | 000 |
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
- Sandbox Endpoint:
https://test-dmz.param.com.tr/turkpos.ws/service_turkpos_test.asmx - Documentation: Param Developer Documentation
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
- Sandbox Endpoint:
https://provisioning.sipay.com.tr - Documentation: Sipay API Documentation
Sipay's documentation lists a shared test merchant (app id, app secret and merchant key) and these test cards:
| Card | Number | Expiry | CVV | 3D Secure code |
|---|---|---|---|---|
| Visa | 4508034508034509 | 12/30 | 000 | 000000 |
| Mastercard | 5406675406675403 | 12/30 | 000 | 000000 |
| Troy | 6501700139082826 | 12/30 | 000 | 000000 |
Other CVV values simulate bank errors: 510 insufficient funds, 050 do not honour, 330 expired card, 820 invalid CVV.