Test environment

dpay.pl provides a test mode that allows you to test your integration without charging real accounts. Test transactions are visible in the admin panel but do not generate actual money flows.

Enabling test mode

1. Log in to panel.dpay.pl.
2. Go to Payment Points > Services.
3. Select the service you want to test.
4. Enable the Test mode toggle.

info

Test mode is available immediately after creating a service - you do not need to wait for account verification to start integrating.

What happens in test mode?

• No real charges - no money is debited from customer accounts
• Transactions visible in the panel - all test transactions appear in the transaction history with a test label
• IPN works normally - IPN notifications are sent to your endpoint just as in production mode
• Full API - all endpoints work identically to production

Testing IPN locally

During development, your server typically runs on localhost, which is not accessible from the internet. To allow dpay.pl to send IPN notifications to your local server, use a tunneling tool.

ngrok

ngrok creates an HTTPS tunnel to your local server:

# Start a tunnel (assuming your server runs on port 3000)
ngrok http 3000

ngrok will generate a public address, e.g. https://abc123.ngrok-free.app. Use it as the url_ipn:

{
  "url_ipn": "https://abc123.ngrok-free.app/api/ipn"
}

Alternatives

• Cloudflare Tunnel - a free tunnel from Cloudflare
• localtunnel - a simple open-source tool (npx localtunnel --port 3000)

tip

Keep in mind that the tunnel address changes after each restart (in the free version of ngrok). Update the url_ipn in your test requests accordingly.

Test card numbers

In the S2S whitelabel integration use the test_card_number field in the registration request:

Card number	Scenario	Description
4111111111111111	Success	Visa - payment completed successfully
5555555555554444	Success	Mastercard - payment completed successfully
4012888888881881	Success with 3DS	Visa - cascade FORM (3DS challenge) → SUCCESS
4000000000000002	Decline	Visa - transaction declined by the issuer
4000000000000069	Expired card	Visa - card expired
4000000000000127	Insufficient funds	Visa - insufficient funds
4000000000000085	Timeout	Visa - processing timeout
5105105105105100	Decline	Mastercard - transaction declined
5346930000008110	DCC offer	Foreign Mastercard - conversion offer (EUR→PLN, 4.5079 rate, 6% markup, 30-minute validity). After decision → SUCCESS
5346930000008128	DCC not allowed	Mastercard - card does not qualify for DCC. Transparent SUCCESS right away (frontend never sees the offer)
5346930000008136	DCC short validity	Foreign Mastercard - DCC offer with validUntil = +60 seconds. Lets you test the DCC_OFFER_EXPIRED error
5346930000008144	DCC + 3DS after decision	Foreign Mastercard - cascade DCC_OFFER → FORM (3DS) → SUCCESS

Testing 3DS in test mode

In production, the 3D Secure form leads to the issuer's bank page (issuer ACS). In test mode dpay provides its own test ACS page with three buttons (Approve / Decline / Timeout), functionally identical to production. From the integration's point of view nothing changes - the gateway returns the standard redirectType: "FORM" with auto-submit HTML.

DCC scenarios

A full description of the Dynamic Currency Conversion flow (API contract, required UI elements, business errors) is available on the Dynamic Currency Conversion (DCC) page.

Testing scenarios

Successful payment

1. Register a transaction via the API with valid data.
2. The customer is redirected to the payment gateway.
3. After approving the payment - the IPN is sent to your endpoint with the paid status.
4. The customer is redirected to url_success.

Canceled payment

1. Register a transaction via the API.
2. On the gateway, the customer selects the cancel option.
3. The customer is redirected to url_fail.

IPN unavailable (retry)

1. Temporarily disable your IPN endpoint (e.g. stop the server).
2. Register and complete a test transaction.
3. dpay.pl will retry IPN delivery (up to 10 attempts with exponential backoff).
4. Restart the server - the IPN will be delivered on the next attempt.
5. Check the IPN delivery history for the transaction in the panel.

Testing refunds

1. Complete a successful test transaction.
2. Call the refund endpoint with the transaction_id of the paid transaction.
3. Check the API response and the transaction status in the panel.

Verifying API responses

In test mode, API responses have the same format as in production. Make sure your application correctly handles:

Scenario	What to verify
Successful registration	error: false field, presence of transactionId and URL in msg
Checksum error	400 response with Invalid checksum message
IPN	signature verification, idempotency, 200 OK response
Refund	success status in the response, refunded_amount update

Checklist before going to production

Before disabling test mode, make sure that:

• Checksum - generated correctly for all request types (registration, refund)
• IPN - endpoint works, verifies the signature (signature), responds with 200 OK
• Idempotency - IPN processed only once per transaction
• Amount verification - the amount from the IPN is compared with the order amount in the database
• Error handling - the application correctly handles API errors (400, 401, 500)
• HTTPS - all URLs (url_success, url_fail, url_ipn) use HTTPS
• Secret Hash - stored securely in environment variables, not in code
• Refunds - if you use refunds, both full and partial refunds have been tested
• Logging - incoming IPNs and API responses are logged for diagnostic purposes

Once all points are met, disable test mode in the panel - your service is ready for production.