Transaction Registration

This guide walks you through the process of registering a transaction using the dpay.pl API step by step. We will use the simplest integration method - Simple Gateway (redirect to the payment gateway).

Prerequisites

Before you begin, make sure you have:

A verified account at panel.dpay.pl (see Registration)
A payment service created with a service name and Hash key (see Configuration)

How it works

Klient

Twój serwer

dpay.pl

Step 1: Prepare the data

Collect the required data for the request:

Required parameters

Field	Type	Description	Example
`service`	string	Service name from the dashboard (alternatively `name`)	`"abc123"`
`transactionType`	string	Transaction type	`"transfers"`
`value`	string	Amount (0-999999.99, with decimal point)	`"29.99"`
`url_success`	string	URL after successful payment	`"https://myshop.com/success"`
`url_fail`	string	URL after failed payment	`"https://myshop.com/error"`
`url_ipn`	string	URL for IPN notifications	`"https://myshop.com/api/ipn"`
`checksum`	string	SHA-256 checksum	(see below)

Optional parameters

Field	Type	Description
`channel`	string	Specific payment channel
`email`	string	Customer email address
`client_name`	string	Customer first name
`client_surname`	string	Customer last name
`blik_code`	string	BLIK code (for BLIK Level 0 payments)
`description`	string	Transaction description
`custom`	string	Custom data (e.g., order ID)
`products`	array	Product list
`currency_code`	string	Currency code (e.g., `PLN`, `EUR`)
`phone_number`	string	Customer phone number

Transaction types

Type	Description
`transfers`	Bank transfers (PBL)
`dcb_gateway`	Direct Carrier Billing
`card_auth`	Payment card authorization
`mb_way_direct`	MB WAY payment

info

The transfers type is the default type for simple redirect to the payment gateway (Simple Gateway), where the customer chooses the payment method themselves.

Step 2: Generate the checksum

The checksum ensures data integrity. It is generated using the SHA-256 algorithm from the concatenation of fields separated by the | character:

sha256({service}|{hash}|{value}|{url_success}|{url_fail}|{url_ipn})

PHP example

$service = 'abc123';
$hash = '9a8b7c6d5e4f3a2b1c0d';
$value = '29.99';
$urlSuccess = 'https://myshop.com/success';
$urlFail = 'https://myshop.com/error';
$urlIpn = 'https://myshop.com/api/ipn';

$checksum = hash('sha256',
    $service . '|' . $hash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

JavaScript (Node.js) example

const crypto = require('crypto');

const service = 'abc123';
const hash = '9a8b7c6d5e4f3a2b1c0d';
const value = '29.99';
const urlSuccess = 'https://myshop.com/success';
const urlFail = 'https://myshop.com/error';
const urlIpn = 'https://myshop.com/api/ipn';

const checksum = crypto
  .createHash('sha256')
  .update(`${service}|${hash}|${value}|${urlSuccess}|${urlFail}|${urlIpn}`)
  .digest('hex');

Python example

import hashlib

service = 'abc123'
hash_key = '9a8b7c6d5e4f3a2b1c0d'
value = '29.99'
url_success = 'https://myshop.com/success'
url_fail = 'https://myshop.com/error'
url_ipn = 'https://myshop.com/api/ipn'

data = f'{service}|{hash_key}|{value}|{url_success}|{url_fail}|{url_ipn}'
checksum = hashlib.sha256(data.encode('utf-8')).hexdigest()

Step 3: Send the API request

Send a POST request to the payment registration endpoint:

POST https://api-payments.dpay.pl/api/v1_0/payments/register
Content-Type: application/json

Full cURL example

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/register \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "transfers",
    "service": "abc123",
    "value": "29.99",
    "url_success": "https://myshop.com/success",
    "url_fail": "https://myshop.com/error",
    "url_ipn": "https://myshop.com/api/ipn",
    "checksum": "e3b0c44298fc1c149afb..."
  }'

PHP example (cURL)

$payload = [
    'transactionType' => 'transfers',
    'service'         => $service,
    'value'           => $value,
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
];

$ch = curl_init('https://api-payments.dpay.pl/api/v1_0/payments/register');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

Step 4: Handle the response

The dpay.pl API returns a response in JSON format:

Success response

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

Field	Type	Description
`error`	boolean	`false` if the request was processed successfully
`msg`	string	Payment gateway URL - redirect the customer to this address
`status`	boolean	`true` on success, `false` on error
`transactionId`	string	Unique transaction identifier

Transaction error response (HTTP 200)

Returned, for example, with an invalid BLIK code or a canceled transaction:

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

Field	Type	Description
`error`	boolean	`true` - an error occurred
`msg`	string	Error description
`status`	boolean	`false` - the transaction failed
`transactionId`	string	Transaction identifier
`additionalInfo`	object	Optional error details (e.g., BLIK error code)

Validation error (HTTP 400)

Returned for merchant-side errors (invalid checksum, disabled channel, invalid amount):

{
  "status": "failed",
  "message": "Payment registration failed",
  "errors": ["Invalid checksum"]
}

Field	Type	Description
`status`	string	`"failed"`
`message`	string	General error message
`errors`	array	List of detailed error messages

Step 5: Redirect the customer

After receiving a response with error: false, redirect the customer to the URL contained in the msg field:

PHP

if (!$result['error']) {
    // Save the transactionId in your database
    saveTransaction($orderId, $result['transactionId']);

    // Redirect the customer to the payment gateway
    header('Location: ' . $result['msg']);
    exit;
} else {
    // Handle the error
    echo 'Payment registration error: ' . $result['msg'];
}

JavaScript (Express.js)

if (!result.error) {
  // Save the transactionId in your database
  await saveTransaction(orderId, result.transactionId);

  // Redirect the customer
  res.redirect(result.msg);
} else {
  res.status(400).json({ error: result.msg });
}

Step 6: Receive the IPN

After the payment is completed, dpay.pl will send an IPN notification to the url_ipn address. For a detailed description of IPN handling, see the Handling IPN guide.

Full example - PHP

<?php
// Configuration
$service = getenv('DPAY_SERVICE');
$hash = getenv('DPAY_HASH');

// Order data
$value = '29.99';
$urlSuccess = 'https://myshop.com/success';
$urlFail = 'https://myshop.com/error';
$urlIpn = 'https://myshop.com/api/ipn';

// Generate the checksum
$checksum = hash('sha256',
    $service . '|' . $hash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

// Register the payment
$payload = json_encode([
    'transactionType' => 'transfers',
    'service'         => $service,
    'value'           => $value,
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
]);

$ch = curl_init('https://api-payments.dpay.pl/api/v1_0/payments/register');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && !$result['error']) {
    // Redirect the customer to the gateway
    header('Location: ' . $result['msg']);
    exit;
} else {
    http_response_code(500);
    echo 'Error: ' . ($result['msg'] ?? 'Unknown error');
}

Common errors

Error	Cause	Solution
`Invalid checksum`	Invalid checksum	Verify the field order and Hash key
`Service not found`	Unknown service name	Check the `service` field in the dashboard
`Invalid value`	Invalid amount	Use the decimal point format (e.g., `"29.99"`)
`Invalid URL`	Invalid URL address	Make sure the URLs start with `https://`

What's next?

Handling IPN - learn how to receive and verify payment notifications
BLIK Level 0 - integrate direct BLIK payments
Cards S2S - add Server-to-Server card payments

Prerequisites​

How it works​

Step 1: Prepare the data​

Required parameters​

Optional parameters​

Transaction types​

Step 2: Generate the checksum​

PHP example​

JavaScript (Node.js) example​

Python example​

Step 3: Send the API request​

Full cURL example​

PHP example (cURL)​

Step 4: Handle the response​

Success response​

Transaction error response (HTTP 200)​

Validation error (HTTP 400)​

Step 5: Redirect the customer​

PHP​

JavaScript (Express.js)​

Step 6: Receive the IPN​

Full example - PHP​

Common errors​

What's next?​