Sandbox & Testing

Use the sandbox environment to test your integration without real money. The sandbox is identical to production in API structure — only payment processing is simulated.

---

Sandbox vs Production

	Sandbox	Production
Base URL	https://4pay.online/api/v1	https://4pay.online/api/v1
API Key	Sandbox key (from Partner Area)	Live key (from Partner Area)
Real charges	❌ Never	✅ Real money
Webhooks	✅ Sent to your notify_url	✅ Sent to your notify_url

Same URL, different key

The API base URL is the same for sandbox and production. The environment is determined by which API key you use — sandbox keys are prefixed sk_test_ or similar.

---

Getting a sandbox API key

1. Log in to Partner Area
2. Go to Settings → API Keys
3. Select Sandbox environment and click Create Key

---

Making a test transaction

curl -X POST https://4pay.online/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SANDBOX_KEY" \
  -d '{
    "params": {
      "type": "payment",
      "amount": 1000,
      "currency": "USD",
      "txid": "sandbox-test-001",
      "returnUrl": "https://yoursite.com/success",
      "failUrl": "https://yoursite.com/fail"
    }
  }'

You will receive a payment_url. Open it in a browser to see the hosted payment form. Use the test cards below to simulate different outcomes.

---

Test Cards

Visa

Card Number	CVV	Expiry	Result
4111 1111 1111 1111	Any 3 digits	Any future date	✅ Successful payment
4000 0000 0000 0002	Any 3 digits	Any future date	❌ Declined (insufficient funds)
4000 0000 0000 0069	Any 3 digits	Any future date	❌ Declined (expired card)
4000 0000 0000 3220	Any 3 digits	Any future date	🔐 3DS authentication required

Mastercard

Card Number	CVV	Expiry	Result
5500 0000 0000 0004	Any 3 digits	Any future date	✅ Successful payment
5105 1051 0510 5100	Any 3 digits	Any future date	✅ Successful payment

3DS Test Flow

Cards ending in 3220 trigger the 3DS flow. On the test 3DS page:

• Enter any 6-digit code to succeed
• Click "Fail" to simulate 3DS failure

---

Test Webhooks

When a test transaction completes, a webhook is sent to your notifyUrl exactly as in production. Use a public tunnel to receive webhooks during local development:

# Using ngrok
ngrok http 3000
# Forwarding: https://abc123.ngrok.io → localhost:3000

Then set notifyUrl: "https://abc123.ngrok.io/webhooks/payment" in your test transactions.

---

Simulating specific scenarios

Simulate a successful payment

Use card 4111 1111 1111 1111. The transaction will move to charged status.

Simulate a declined payment

Use card 4000 0000 0000 0002. The transaction will move to failed status with error_description: "insufficient_funds".

Simulate a refund

After a successful test payment, issue a refund:

curl -X PUT https://4pay.online/api/v1/transactions/TRANSACTION_ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SANDBOX_KEY" \
  -d '{ "params": { "type": "refund" } }'

The transaction status will move to refunded.

---

Smoke Test Script

If you want to automate the full end-to-end flow (register → create partner → create terminal → create transaction), contact your platform operator — they can share the smoke test script used for platform validation.

---

Moving to production

When you are ready to go live:

1. Replace your sandbox API key with a live API key from Partner Area
2. Ensure your notifyUrl points to your production server
3. Replace test returnUrl / failUrl with production URLs
4. Remove any hardcoded test data (card numbers, test txids)

No code changes required — the API is identical.