Skip to main content

Test environment

dpay.pl provides a test mode that lets you test your integration without charging real accounts. Test transactions are visible in the administration dashboard but do not generate real money flows.

Enabling test mode​

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

Test mode is available immediately after you create a service. You do not need to wait for account verification before starting the integration.

What happens in test mode​

  • No real charges - no money is collected from customer accounts
  • Transactions visible in the dashboard - all test transactions appear in transaction history and are marked as test transactions
  • IPN works normally - IPN notifications are sent to your endpoint in the same way as in production
  • Full API - all endpoints work in the same way as in production

Testing IPN locally​

During development, your server usually runs on localhost, which is not accessible from the internet. Use a tunnelling tool so that dpay.pl can send IPN notifications to your local server.

ngrok​

ngrok creates an HTTPS tunnel to your local server:

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

ngrok generates a public address, such as https://abc123.ngrok-free.app. Use it as url_ipn:

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

Alternatives​

tip

Remember that the tunnel URL changes after every restart in the free ngrok plan. Update url_ipn in your test requests.

Test values for simulating payments​

In test mode, you can use special test values to simulate different payment scenarios without contacting external providers. The system recognises these values automatically and returns the corresponding responses.

Payment cards​

For a white-label integration (S2S cards), the test scenario is selected by the card number (PAN) included in the encrypted card data (encryptedCardData) when making the payment call. The service only needs to have test mode enabled:

Card numberScenarioDescription
4111111111111111SuccessVisa - payment completed successfully
5555555555554444SuccessMastercard - payment completed successfully
4012888888881881Success with 3DSVisa - FORM (3DS challenge) → SUCCESS cascade
4000000000000002DeclineVisa - transaction declined by the issuer
4000000000000069Expired cardVisa - card expired
4000000000000127Insufficient fundsVisa - insufficient funds
4000000000000085TimeoutVisa - processing timeout
5105105105105100DeclineMastercard - transaction declined
5346930000008110DCC offerForeign Mastercard - currency conversion offer (EUR→PLN, exchange rate 4.507968, 6% markup, EEA card, valid for 30 minutes). After the decision → SUCCESS
5346930000008128DCC unavailableMastercard - card not eligible for DCC. Immediate transparent SUCCESS (the frontend does not see an offer)
5346930000008136Short-lived DCCForeign Mastercard - GBP DCC offer (exchange rate 0.85123, 5.5% markup, non-EEA card) with validUntil = +60 seconds. Use it to test DCC_OFFER_EXPIRED
5346930000008144DCC + 3DS after decisionForeign Mastercard - USD DCC offer (exchange rate 1.05432, 5% markup, non-EEA card), with the DCC_OFFER → FORM (3DS) → SUCCESS cascade
Testing 3DS in test mode

In production, the 3D Secure form opens the bank's page (the card issuer's ACS). In test mode, dpay provides its own test ACS page with three buttons: Approve, Decline, and Timeout. It is functionally identical to production. You do not need to change anything in your integration; the gateway returns the standard redirectType: "FORM" with auto-submit HTML.

DCC scenarios

For a complete description of the Dynamic Currency Conversion flow, including the API contract, required UI elements, and business errors, see Dynamic Currency Conversion (DCC).

BLIK​

Use the following special six-digit BLIK codes in the blik_code field:

BLIK codeScenarioDescription
777200SuccessPayment completed successfully
777201Success (delayed)Success after a longer wait for confirmation
777400DeclinedThe user declined the transaction in the application
777401TimeoutThe user did not confirm within the required time
777402Insufficient fundsInsufficient funds in the account
777500System errorSimulated system-side error

MB WAY​

Use the following special Portuguese numbers in the phone_number field:

Phone numberScenarioDescription
+351900000001SuccessPayment completed successfully
+351900000002Success (delayed)Success after a longer wait
+351900000400DeclinedThe user declined the payment in the MB WAY application
+351900000401TimeoutNo confirmation within the required time
+351900000402Number not registeredThe phone number is not linked to MB WAY
+351900000500System errorSimulated system error

Apple Pay and Google Pay​

Apple Pay and Google Pay use wallet tokens instead of card numbers. In test mode, submit a special test value in the xPayToken field instead of a real token:

TokenScenarioDescription
TEST_SUCCESSSuccessPayment completed successfully
TEST_SUCCESS_DELAYEDSuccess (delayed)Success after a longer wait
TEST_DECLINEDeclineTransaction declined
TEST_INSUFFICIENTInsufficient fundsInsufficient funds
TEST_TIMEOUTTimeoutConfirmation timed out
TEST_ERRORSystem errorSimulated system error
tip

In test mode, you do not need to open a real Apple Pay or Google Pay sheet. Send a request with a test token directly to the /pay/apple-pay or /pay/google-pay endpoint.

How do the test values work?
  • For success scenarios, the transaction immediately receives the processing status and automatically changes to paid after a few seconds. An IPN is sent to your endpoint.
  • For error scenarios, the API returns an error response and the transaction is cancelled.
  • If you use a value that is not in the test list, the system simulates a successful payment by default.
tip

Test values work only when the service has Test mode enabled. In production, they are treated as ordinary payment data.

Testing scenarios​

Successful payment​

  1. Register a transaction through the API with valid data, or use a test value for the success scenario.
  2. The customer is redirected to the payment gateway, or for a white-label integration the API response confirms registration.
  3. After payment approval, an IPN reaches your endpoint with the paid status.
  4. The customer is redirected to url_success.

Cancelled payment​

  1. Register a transaction through the API, or use a test value for a decline or timeout.
  2. The customer selects the cancellation option in the gateway.
  3. The customer is redirected to url_fail.

IPN unavailable (retry)​

  1. Temporarily disable your IPN endpoint, for example by stopping the server.
  2. Register and pay a test transaction.
  3. dpay.pl retries IPN delivery, up to 10 attempts with exponential backoff.
  4. Start the server again. The IPN is delivered during the next attempt.
  5. Check the IPN delivery history for the transaction in the dashboard.

Testing refunds​

  1. Complete a successful test transaction, for example BLIK with code 777200.
  2. Call the refund endpoint with the paid transaction's transaction_id.
  3. Check the API response and the transaction status in the dashboard.

Verifying API responses​

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

ScenarioWhat to check
Successful registrationerror: false, a transactionId, and a URL in msg
Checksum errorFor registration, a 400 response with Invalid checksum
IPNsignature verification, idempotency, and a 200 OK response
Refundsuccess status in the response and an updated refunded_amount
Checksum error for a refund

When the refund checksum is invalid, the refund endpoint returns 401 with the Unauthorized request message, not 400. Account for this in your error handling.

Checklist before going live​

Before disabling test mode, make sure that:

  • Checksum - generated correctly for every request type (registration and refund)
  • IPN - the endpoint works, verifies the signature, and responds with 200 OK
  • Idempotency - each transaction's IPN is processed only once
  • Amount verification - the IPN amount is compared with the order amount in your database
  • Error handling - the application handles API errors correctly (400, 401, 500)
  • HTTPS - every URL (url_success, url_fail, and url_ipn) uses HTTPS
  • Secret Hash - stored securely in environment variables, not in source code
  • Refunds - if you use refunds, both full and partial refunds have been tested
  • Logging - incoming IPN notifications and API responses are logged for diagnostics

After completing the checklist, disable test mode in the dashboard. Your service is ready for production.

Last updated on