Error codes and response statuses

A complete list of HTTP codes, transaction statuses, validation errors, and dpay.pl API response codes.

HTTP response codes

Code	Meaning	Description
200	Success	The request was processed successfully
400	Bad request	Business validation error (for example, an invalid registration checksum, disabled channel, or invalid amount)
401	Unauthorised	Missing or invalid credentials; also an invalid checksum for refunds, transaction details, and payout details (Unauthorized request)
403	Forbidden	No permission to access the resource (errorcode: err01)
404	Not found	The resource does not exist
422	Field validation error	The request failed formal field validation (see the format below)
500	Server error	Internal server error

Response formats

Success response (payment registration)

{
  "error": false,
  "msg": "https://secure.dpay.pl/transfer@pay@A75AEBB4-4B89-4834-AD43-EF442C133769",
  "status": true,
  "transactionId": "A75AEBB4-4B89-4834-AD43-EF442C133769"
}

The msg field in a successful registration response has different values depending on the scenario:

Scenario	msg value	Additional fields
Redirect to the payment gateway	Payment gateway URL	none
Test mode	Internal payment simulation page URL	none
Internal processing without a redirect, for example a payment initiated with a code	Internal processing	none
Transaction paid immediately	Transaction paid	additionalInfo.transaction with transaction details

Success response - paid transaction

{
  "error": false,
  "msg": "Transaction paid",
  "status": true,
  "transactionId": "A75AEBB4-4B89-4834-AD43-EF442C133769",
  "additionalInfo": {
    "transaction": {
      "payment_id": "A75AEBB4-4B89-4834-AD43-EF442C133769",
      "pid": null,
      "mtid": null,
      "email": "customer@example.com",
      "description": "Order #1234",
      "name": null,
      "surname": null,
      "value": "29.99",
      "status": "paid",
      "creation_date": "2026-05-03 17:40:07",
      "payment_date": "2026-05-03 17:40:12"
    }
  }
}

The Transaction statuses section describes the values in additionalInfo.transaction.status.

Transaction error response (for example, cancelled)

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "42191111-A7AE-392E-8C09-7965C1DC6B0B"
}

Business validation error (HTTP 400)

Returned for merchant-side errors such as an invalid checksum, disabled channel, or invalid amount. The message field contains the specific error message, while errors is an object mapping a field name to a message, not an array:

{
  "status": "failed",
  "message": "Invalid checksum",
  "errors": {
    "checksum": "Invalid checksum"
  }
}

{
  "status": "failed",
  "message": "Amount is less than 0.01 PLN",
  "errors": {
    "value": "Invalid value"
  }
}

Field validation error (HTTP 422)

When a request fails formal field validation, for example because a required field is missing or a value has the wrong type, the API returns the standard validation response. In this format, errors maps a field name to an array of messages:

{
  "message": "The value field is required.",
  "errors": {
    "value": [
      "The value field is required."
    ]
  }
}

Error response with a code (403)

{
  "error": true,
  "errorcode": "err01",
  "message": "Access denied",
  "status": false
}

Card response - success

{
  "success": true,
  "status": "success",
  "message": {
    "redirectText": "",
    "redirectType": "SUCCESS",
    "dccOffer": null
  }
}

The message field

On success (success: true), message is an object in which dccOffer is always present. It is null when no currency conversion offer was made. On failure (success: false), message is a string containing the error message.

Card response - 3D Secure required

{
  "success": true,
  "status": "success",
  "message": {
    "redirectText": "PGZvcm0gbWV0aG9kPSJQT1NUIi4uLg==",
    "redirectType": "FORM",
    "dccOffer": null
  }
}

Card response - error

{
  "success": false,
  "status": "error",
  "message": "DCC_OFFER_EXPIRED"
}

Card response - DCC offer (foreign card)

{
  "success": true,
  "status": "success",
  "message": {
    "redirectText": null,
    "redirectType": "DCC_OFFER",
    "dccOffer": {
      "currencyConversionId": "00509166251006151007",
      "originalAmount": 3.00,
      "originalCurrency": "EUR",
      "convertedAmount": 13.52,
      "convertedCurrency": "PLN",
      "exchangeRate": 4.507968,
      "validUntil": "2026-05-03T17:40:07+00:00",
      "declarationText": "Make sure you understand the costs of currency conversions...",
      "markup": [{ "rate": 6.0, "additionalInfo": "Mastercard" }],
      "europeanEconomicArea": true
    }
  }
}

For the complete flow, see Dynamic Currency Conversion (DCC).

BLIK response - error

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "42191111-A7AE-392E-8C09-7965C1DC6B0B",
  "additionalInfo": {
    "error": "USER_DECLINED",
    "error_description": null
  }
}

Transaction statuses

The status field in a transaction details response (pbl/details) and in refund statuses:

Status	Description
created	Transaction created and awaiting payment
processing	Payment being processed
paid	Payment completed successfully
captured	Funds captured after an earlier pre-authorisation
expired	Transaction cancelled or expired

A second status map - registration response

The additionalInfo.transaction.status field in a registration response (the Transaction paid variant) uses a different mapping: pending, paid, captured, and canceled. The pending and canceled statuses occur only there, while created, processing, and expired occur only in the transaction details response.

Payout statuses

The state field in the payout details response (pbl/withdraws/details):

Value	Status	Description
0	Pending	The payout is awaiting processing
1	Completed	The payout was processed
-1	Error	The payout failed

In addition to state, the amount fields (net, fee, and gross), and the creation date (creation_date), the response contains:

Field	Description
id	Payout identifier
paysafecard	Paysafecard portion of the payout (present when direct_settlement = 0)
declined	1 if the payout was declined; otherwise 0
decline_reason	Reason for declining the payout (present only when declined = 1)
decline_status	Status of the decline process (present only when declined = 1)
direct_settlement	1 when the payout is processed as a settlement directed to specified accounts
nrb	Payout account number (present when direct_settlement = 0)
receiver	Object containing the recipients of a directed settlement (present instead of nrb when direct_settlement = 1)

Payment registration errors

Messages returned in the message field of an HTTP 400 response (see Business validation error):

Message	Cause	Solution
Invalid checksum	Invalid checksum	Check the field order and Hash key. Format: sha256(service|hash|value|url_success|url_fail|url_ipn), with value normalised to two decimal places
Service not found	Unknown service name	Check the service field in the dpay.pl dashboard
Amount is less than 0.01 PLN	Amount below the minimum	Provide at least 0.01, using a decimal point (for example, "29.99"); errors.value then contains Invalid value

BLIK error codes

When a BLIK payment is rejected, additionalInfo.error contains the raw rejection code from the BLIK system, forwarded 1:1 without mapping by dpay. The list of codes is open-ended and depends on the customer's bank and the BLIK system. Treat this field as diagnostic information and do not base business logic on it.

In test mode, payments are simulated and additionalInfo.error has one of the following values:

Code	Description
DECLINE	Transaction declined by the issuer
EXPIRED_CARD	Payment instrument expired
INSUFFICIENT_FUNDS	Insufficient funds
USER_DECLINED	User declined the transaction
TIMEOUT	Confirmation timed out
ALIAS_NOT_FOUND	Alias not found
SYSTEM_ERROR	Simulated system error

MB WAY error codes

The additionalInfo.error field in an MB WAY payment response when error: true, status: false:

Code	Description	Solution
E0506	The phone number is not registered in the MB WAY application	Ask the customer to register it in MB WAY or provide another number
E0508	The phone number is temporarily unavailable in MB WAY	Try again shortly or use another payment method
E0099	The operation is not permitted for this number	The customer should contact MB WAY support
E0103	Invalid request data	Check the phone number format (PT: 9 digits, prefix 351) and the other fields
E0309	Transaction not found	Check transactionId or initiate a new payment
E0399	Transaction declined	The customer declined the transaction in the application or confirmation timed out
E0000	Fallback code - the system returned no error code	Treat it as a generic error; inspect error_description and escalate to support if it repeats
other E*	Generic MB WAY processor error	error_description contains details; escalate to support if it repeats

Complete MB WAY error response format:

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "42191111-A7AE-392E-8C09-7965C1DC6B0B",
  "additionalInfo": {
    "error": "E0506",
    "error_description": "The provided alias does not exists"
  }
}

Card response codes

The message.redirectType field in a card payment response. The following list of values is complete:

Value	Meaning	Action
SUCCESS	Payment completed	Redirect the customer to the success page
FORM	3D Secure required	Display the 3DS form from redirectText (Base64 encoded)
URL	Redirect to an external URL	Redirect the customer to the URL in redirectText
DCC_OFFER	Currency conversion offer (DCC)	Show the customer both amounts from dccOffer, then call the endpoint again with dccDecision after the customer decides (see DCC)

DCC error codes

DCC errors are returned with HTTP 200 in the {"success": false, "status": "error", "message": "..."} format. The message field is then a string containing the error code:

{
  "success": false,
  "status": "error",
  "message": "DCC_OFFER_EXPIRED"
}

Message	HTTP	Cause	Solution
DCC_OFFER_EXPIRED	200	The decision was submitted after the DCC offer's validUntil	Show "Offer expired", return to the payment method screen, and start a new flow
INVALID_FLOW_STATE	200	dccDecision was submitted without an earlier offer, for example for a finalised transaction	Technical error - log it and redirect to an error screen

caution

Do not identify these errors by HTTP code because the response uses HTTP 200. Check the success field in the response body.

DCB error codes

DCB registration errors (secure.dpay.pl/dcb/register endpoint)

Messages returned in msg when error: true:

Message	HTTP	Cause	Solution
missing guid or value or url success/fail or chcksum	400	One of the required fields is missing: guid, value, url_success, url_fail, or checksum	Supply all required request fields
Could not find service by GUID	400	Unknown GUID	Check the GUID in the dpay.pl dashboard
Service not verified.	401	The Payment Point has not been verified	Complete Payment Point verification
Invalid checksum	400	Invalid checksum	Use the amount in Polish zloty with two decimal places in the checksum and omit url_ipn; see Generating checksums

note

The missing guid or value or url success/fail or chcksum message contains a typo (chcksum) in the API and is returned literally in this form.

DCB payment statuses

Value	Status	Description
1	PAID	Payment completed
0	PENDING	Payment awaiting confirmation
-1	REJECTED	Payment rejected
2	REFUNDED	Payment refunded

DCB verification statuses

Value	Status	Description
1	VERIFIED	Number verified
0	NOT_VERIFIED	Number not verified
-1	BLOCKED	Number blocked
-2	REQUIRES_CONTACT	Support contact required

SMS code statuses

Value	Status	Description
1	USED	Code used
0	PENDING	Code awaiting use
-1	REJECTED	Code rejected