Sandbox

Use a plk_test_… key (or Developers → Sandbox in the app, which runs real requests with your account).

Sandbox payments:

• never call the payment provider and never move funds,
• return sandbox: true and simulation: true,
• are listed in your dashboard under Transactions → Sandbox,
• fire real webhooks to your endpoint when you simulate a result.

Test phone numbers

The scenario is chosen by the last digit of a number ending in 00000000N and works with every active operator of the country. Any country code works.

Other numbers return 202 pending.

OTP simulation

1{
2  "error": "otp_required",
3  "sandbox": true,
4  "simulation": true,
5  "reference": "PLK-SBX-…",
6  "ussd_code": "#SANDBOX#",
7  "message": "Demo OTP required. Use 000000 with the same request."
8}

Re-send with "reference": "<returned reference>" and "otp": "000000". Any other OTP returns invalid_otp.

Finishing pending payments

1curl -X POST https://paylinky.vercel.app/api/v1/sandbox/simulate \
2  -H "Authorization: Bearer $PAYLINKY_TEST_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{ "transaction_id": "0b9c…", "status": "success" }'

This updates the transaction and sends payment.completed (or payment.failed) to your webhook.

Crypto in the sandbox

/crypto/collect returns a clearly fake address and stays pending until you call /sandbox/simulate.

Test checklist

• 200 on /countries and /crypto/assets
• one pending, one success, one failed, one cancelled
• the OTP round-trip
• webhook received, signature verified, duplicate delivery ignored
• timeout → status check instead of a second payment
• errors 400, 401, 403, 429