dpay.pl - API Documentation (1.3.0)

Download OpenAPI specification:

About

Payments Lab provide payment gateway under dpay brand. API can be used both for Technical Service Provider and Payment Service Provider services.

How To Integrate

Plugin

Simplest way to integrate with dpay, is using dpay provided plugin for most popular e-commerce platforms. Here you can find ready plugins: Plugins

Donation page

If you want to accept donations, or just tips for your business, you can do that using dpay's payment page system.

Donation page system allows you to add your own logo and text and that's it! You don't need to worry about page hosting - we take care of that.

Check out our (Example Donation Page)[https://pay.dpay.pl/payment-page/01HXMVYFVRG38SHE0F9S4XK01E]

REST API Integration

If you have IT development capability, you can integrate with our REST API. Our API is designed with KISS pricinpal in mind. There are three ways that you can currently use our API to integrate payments:

Simplest: create payment & redirect payer to dpay gateway

White-label options:

  • Integrate BLIK level 0 payments
  • Integrate white-label selection of other payment channels into your website

All of those ways, requires you to:

  • Register payment
  • Accept Instant Payment Notification (IPN)

Some of our customers prefer to use Get Payment Status instead of IPN but we advise to use IPNs.

Below you can find simplified descriptions of payments flow used in REST API Integration.

Payment flow

Classic payments

After placing the order, the customer clicks the 'pay' button. The Seller's system sends the transaction registration request to the dpay gateway and receives back a unique transaction identifier and a payment link. The seller's system then redirects the customer to the transaction based on received link. In the event of cancellation of the payment, the customer is redirected to the 'url_fail' address. After the successfull transaction, the customer is redirected to the address given in the 'url_success' parameter.

The dpay gateway sends the transaction confirmation to the address given in the 'url_ipn' parameter. The notification with confirmation of the transaction is sent asynchronously. In order to confirm the credibility of the received confirmation, in response to the payment confirmation, the seller's system verifies the request on the basis of the checksum.

Payment flow

Semi-Direct Payments

When you define channel, email, client_name, client_surname, accept_tos params and send it with transaction register request, you can easily redirect customer to the defined channel (eg. bank).Channels list can be obtained from Get banks list method or from dpay management system.All other processes will be done as in classic payment flow. Semi-Direct

Env

Servers

All requests to dpay servers should come from Europe. If you need to send requests to dpay servers from servers outside the Europe, you should contact dpay staff.

Requirements

  • TLS: 1.2
  • OpenSSL: 1.0.1
  • cURL: 7.34.0
  • Capability of JSON creation and parsing, sha256 hashing algorithm

Customization

Custom gateway style

Payments Lab allows to change default gateway style/color (green) to different. Currently supported: default (green), dark, and orange. Default: Default style Dark: Dark style Orange: Orange style

Payment Services

Documentation of Payment Services API.

Register Payment

This request allows to register new payment. Payments methods:

  • Paybylink
  • BLIK
  • Standard bank transfer
  • Paysafecard
  • Creditcard
  • BLIK BNPL

Checksum:

  • Checksums are created using sha256 method.
  • Checksums are created using format: {{name}}|{{SecretHash}}|{{value}}|{{url_success}}|{{url_fail}}|{{url_ipn}} in sha256.
  • {{SecretHash}} you can get from panel.dpay.pl (Payment Points-> Select & Open -> Hash)
  • Example: 4763c9b2af53f287a113fe54dd368aa4a276aada052602sd51980ec4a616038d

Directpayments:

  • You cannot use Directpayments for 'tester', 'paypal', 'blik', 'installment' and 'paysafecard' channel.
  • Client cannot change payment method in directpayment or try again to pay.

Quickpayment:

If the client_name, client_surname and email will be sent in the request, the client will be able to pay without entering the data again. Quickpayment flow currently works for Paybylink, BLIK and standard bank transfer.

Request Body schema: application/json
required
transactionType
required
string
Default: "transfers"

Type of transaction, currently required is transfers

service
required
string
Default: "TestTest"

Payment Point name from panel.dpay.pl

value
required
string
Default: "1.00"

Transaction value in PLN eg. 10.23, 451.00.

url_success
required
string
Default: "https://yourwebsite.tld/success"

URL that payer is redirected after successful payment

url_fail
required
string
Default: "https://yourwebsite.tld/fail"

URL that payer is redirected after failed/expired payment

url_ipn
required
string
Default: "https://yourwebsite.tld/ipn"

URL for IPN communication

checksum
required
string
Default: "sha256 string"

Checksum of transaction

installment
boolean
Default: true

Sending true will allow client to pay in installment form.

creditcard
boolean
Default: true

Sending true will allow client to pay by creditcard.

paysafecard
boolean
Default: true

Sending true will allow client to pay by paysafecard.

paypal
boolean
Default: true

Sending true will allow client to pay by paypal account.

nobanks
boolean
Default: false

Sending true will disable Paybylink and Bank transfer method.

channel
string
Default: ""

Allows to redirect client directly to bank (without dpay gateway view), also known as direct payment

email
string
Default: ""

Client email (required for direct payments)

client_name
string
Default: ""

Client name (required for direct payments)

client_surname
string
Default: ""

Client surname (required for direct payments)

accept_tos
integer
Default: 1

Required for direct payments (Shop with DirectPayments should show dpay TOS before payment with checkbox to accept, field only accepts value: 1)

description
string
Default: "Example description 123"

Transaction description visible for payer on gateway

custom
string
Default: "your custom data"

Custom data passed to url_ipn in Instant Payment Notification

style
string
Default: "default"

Allows to select gateway theme, see chapter Customization.

user_agent
string
Default: ""

User agent of client browser, used to detect mobile devices.

user_ip
string
Default: ""

User IP address, used to detect mobile devices.

blik_code
string
Default: ""

Blik code for mobile payments. Allows to accept BLIK level 0 payments. You need to include user_agent and user_ip to use this feature.

Responses

Request samples

Content type
application/json
{
  • "transactionType": "transfers",
  • "service": "TestTest",
  • "value": "1.00",
  • "checksum": "sha256 string",
  • "installment": true,
  • "creditcard": true,
  • "paysafecard": true,
  • "paypal": true,
  • "nobanks": false,
  • "channel": "",
  • "email": "",
  • "client_name": "",
  • "client_surname": "",
  • "accept_tos": 1,
  • "description": "Example description 123",
  • "custom": "your custom data",
  • "style": "default",
  • "user_agent": "",
  • "user_ip": "",
  • "blik_code": ""
}

Response samples

Content type
application/json
{}

Transaction details

Returns transaction details

Request Body schema: application/json
required
service
required
string
Default: "TestTest"

Service name

transaction_id
required
string
Default: "AAAAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"

Transaction/payment ID

checksum
required
string
Default: "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"

Checksum sha256 (service name|transaction_id|secret hash)

Responses

Request samples

Content type
application/json
{
  • "service": "TestTest",
  • "transaction_id": "AAAAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
  • "checksum": "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"
}

Response samples

Content type
application/json
{
  • "service": "success",
  • "transaction": {}
}

Refund transaction

Refunds transaction currently supports only full refund. Available for BLIK, BLIK BNPL, Bank Transfers, Cards.

Request Body schema: application/json
required
service
required
string
Default: "TestTest"

Service name

transaction_id
required
string
Default: "AAAAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"

Transaction/payment ID

checksum
required
string
Default: "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"

Checksum sha256 (service name|transaction_id|secret hash)

Responses

Request samples

Content type
application/json
{
  • "service": "TestTest",
  • "transaction_id": "AAAAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
  • "checksum": "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"
}

Withdraw details

Allow's to retrive information about specific withdraw.

Request Body schema: application/json
required
service
required
string
Default: "TestTest"

Service name

timestamp
required
any
Default: 1652000000

UNIX timestamp, used to checksum verification. Timestamp must be less than 60 seconds ago.

withdraw_id
required
integer
Default: 12345

Withdraw id

checksum
required
string
Default: "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"

Checksum sha256 (service name|timestamp|withdraw_id|secret hash)

Responses

Request samples

Content type
application/json
{
  • "service": "TestTest",
  • "timestamp": 1652000000,
  • "withdraw_id": 12345,
  • "checksum": "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "state": 0,
  • "net": 1.23,
  • "fee": 0.1,
  • "gross": 1.33,
  • "creation_date": "2022-01-10 01:01:01",
  • "direct_settlement": 0,
  • "paysafecard": 0,
  • "nrb": "AABBBBCCCCDDDDDDDDDDDDDDDD",
  • "receiver": {
    }
}

Get banks list

Returns all banks operated by dpay.

Responses

Response samples

Content type
application/json
{
  • "bank": [
    ]
}

Get banks list for specific service

Returns banks operated by dpay for specific service.

Request Body schema: application/json
required
service
required
string
Default: "TestTest"

Service name

timestamp
required
any
Default: 1652000000

UNIX timestamp, used to checksum verification. Timestamp must be less than 60 seconds ago.

checksum
required
string
Default: "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"

Checksum sha256 (service name|timestamp|secret hash)

Responses

Request samples

Content type
application/json
{
  • "service": "TestTest",
  • "timestamp": 1652000000,
  • "checksum": "ca10f9defba8fd68011d332ff32c4bdaa6d561baac005feaab218de2cade1542"
}

Response samples

Content type
application/json
{
  • "bank": [
    ]
}

Get regulations (DirectPayments)

Returns rules that payer should accept before direct payment.

Responses

Response samples

Content type
text/plain
Zapoznałem się i akceptuję 
<a target="_blank" href="https://dpay.pl/files.view#rules">Regulamin świadczenia usług płatniczych</a> oraz
<a href="https://secure.dpay.pl/privacy" target="_blank">Politykę prywatności</a>.
<br>Chcę aby usługa została zrealizowana niezwłocznie, a w przypadku odstąpienia od umowy, wiem, że nie otrzymam zwrotu poniesionych kosztów za usługi zrealizowane na moje żądanie do chwili odstąpienia od umowy.

Instant Payment Notification

After successful payment, you will receive an Instant Payment Notification (IPN) containing the transaction details. IPN will be sent to the URL defined in the TransactionRegister request.

The IPN schema is defined below.

id
string
Default: "AAAAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"

Transaction ID

amount
float
Default: 1.23

Transaction value eg. 1.23 PLN

email
string
Default: "[email protected]"

Client email

type
string
Default: "transfer"

Transaction type eg. transfer

attempt
integer
Default: 1

IPN delivery attempt

version
integer
Default: 1

IPN version

custom
string
Default: "your custom data eg. shop transaction id"

Custom data pass-through

{
  • "id": "AAAAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
  • "amount": 1.23,
  • "email": "[email protected]",
  • "type": "transfer",
  • "attempt": 1,
  • "version": 1,
  • "custom": "your custom data eg. shop transaction id"
}

SMS Premium Rate

Get all tariffs

Return all registered public sms premium tariffs.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Verify code

SMS Premium code verification.

path Parameters
client
required
string
Example: 1

Client ID

service
required
string
Example: 1

Service ID

code
required
string
Example: A1B2C3D4

Code eg. A1B2C3D4

Responses

Response samples

Content type
application/json
{
  • "code": "A1B2C3D4",
  • "msisdn": 123456789,
  • "net": 6,
  • "net_gross": 4,
  • "number": 71480,
  • "revenue": 50,
  • "status": true,
  • "tariff": 7,
  • "vat": "7.38"
}

Direct Carrier Billing

Register Payment

This request allows to register new DCB payment.

Checksum:

  • Checksums are created using sha256 method.
  • Checksums are created using format: {{GUID}}|{{SecretHash}}|{{value}}|{{url_success}}|{{url_fail}}|{{url_ipn}} in sha256.
  • {{SecretHash}} you can get from panel.dpay.pl (Direct Carrier Billing -> Select & Open -> Hash)
  • Example: 4763c9b2af53f287a113fe54dd368aa4a276aada052602sd51980ec4a616038d
Request Body schema: application/json
required
guid
string
Default: "EC29490E-F3AC-421C-91BF-16840E7BFF93"

Service GUID

value
required
integer
Default: 1023

Transaction value in PLN eg. 10.23, 451.00 times 100 => 1023, 45100.

url_success
required
string
Default: "https://yourwebsite.tld/success"

URL that payer is redirected after successful payment

url_fail
required
string
Default: "https://yourwebsite.tld/fail"

URL that payer is redirected after failed/expired payment

checksum
required
string
Default: "sha256 string"

Checksum of transaction

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

SMS Sending

User API

Get balance

Returns user's balance.

query Parameters
key
string

User (service) API Key

checksum
string

Checksum created from hashed sha256 concatenation of key from dpay staff, secret user(service) api key, function name (getBalance), timestamp (same as in query param)

timestamp
integer

UNIX timestamp, used to checksum verification

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": 1.23
}

Direct settlement (payout)

Allow's to send money directly to your Partner. Service requires special dpay staff verification and acceptance. Every payout costs 1 PLN (there is no dpay's commision, it's bank commision).

query Parameters
key
string

User (service) API Key

checksum
string

Checksum created from hashed sha256 concatenation of key from dpay staff, secret user(service) api key, function name (getBalance), timestamp (same as in query param)

timestamp
integer

UNIX timestamp, used to checksum verification

Request Body schema: application/json
required
nrb
string
Default: "AABBBBCCCCDDDDDDDDDDDDDDDD"

Receiver NRB

title
string
Default: "TEST"

Payout title (displayed in elixir transaction), passing TEST, Receiver will se DPAY.PL PAYOUT TEST

receiverName
string
Default: "Company sp. z o.o."

Receiver name (eg. Company sp. z o.o.)

receiverAddress
string
Default: "ul. Testowa 12/13a"

Receiver address (eg. ul. Testowa 12/13a)

amount
float
Default: 12.53

Transfer amount

Responses

Request samples

Content type
application/json
{
  • "nrb": "AABBBBCCCCDDDDDDDDDDDDDDDD",
  • "title": "TEST",
  • "receiverName": "Company sp. z o.o.",
  • "receiverAddress": "ul. Testowa 12/13a",
  • "amount": 12.53
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "id": 123,
  • "message": "Direct settlement/Payout sent successfully, id: 123."
}

Utilities

Utilities chapter contains methods about getting information about dpay eg. PI license number.

License Number

Returns license number of entity operating dpay.

Responses

Privacy Policy

Redirects to dpay privacy policy page.

Responses

Rules

Redirects to dpay rules page.

Responses