Introduction

Interface characteristics and address

Seller administration panel API has been made using REST architecture.

Interface addresses are available at:

Production environment:

https://ssl.dotpay.pl/s2/login/api/v1/

Test environment:

https://ssl.dotpay.pl/test_seller/api/v1/

Authentication and authorization

Authentication and authorization

For example for:
GETaccounts/

request headers

GET /test_seller/api/v1/accounts/ HTTP/1.1
Host: ssl.dotpay.pl
Authorization: Basic YXBpLnBhd2VsdzE6WXRyZURmcjgx

after sending a request with incorrect login / password:

response headers:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
WWW-Authenticate: Basic realm="api"
Vary: Accept
Allow: GET, OPTIONS

response:

{
  "detail": "Invalid username/password"
}

<?xml version='1.0' encoding='utf-8'?>
<root>
    <detail>Invalid username/password</detail>
</root>

API authentication is done by entering (with HTTP Basic authentication method) user login and password adequate to seller GUI administration panel data. After sending a request API is going to return response with proper HTTP status code.

If there is such a need, like in the example above, a parameter detail with error description will be returned.

HTTP status code meaning:

HTTP status code	DESCRIPTION
201 OK	ok
401 Unauthorized	not able to authorize
403 Forbidden	no permission

Requests limit number

Requests limit number

For example for:
GETaccounts/

request headers:

GET /test_seller/api/v1/accounts/ HTTP/1.1
Host: ssl.dotpay.pl
Authorization: Basic YXBpLnBhd2VsdzE6WXRyZURmcjgx

After too many made requests per unit of time, will be returned answer:

response headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 28
Content-Type: application/json
Allow: GET, OPTIONS

response:

{
  "detail": "Request was throttled. Expected available in 28.0 seconds."
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <detail>Request was throttled. Expected available in 28.0 seconds.</detail>
</root>

In order to eliminate abuse API has a limit on the number of requests in a given unit of time. If customer exceeds the limit, it will be returned error code 429 Too Many Requests. Next request should be repeated after time specified in header Retry-After. Details of error will be returned in response to requests in parameter detail.

HTTP status code meaning:

HTTP status code	DESCRIPTION
429 Too Many Requests	exceeded limit of requests

Input / output data format

Input / output data format

When parameter format is sent (like in examples below), API is going to return a response according to those above.

For example for:
GETaccounts/

request headers
Format JSON

using parameter in header application/json:

GET /test_seller/api/v1/accounts/ HTTP/1.1
Host: ssl.dotpay.pl
Authorization: Basic YXBpLnBcf4VsdzpZdHJlRGZyODE=
Accept: application/json
Content-Type: application/json

or using a parameter in resource address /accounts/?format=json:

GET /test_seller/api/v1/accounts/?format=json HTTP/1.1
Host: ssl.dotpay.pl
Authorization: Basic YXBpLnBcf4VsdzpZdHJlRGZyODE=

Format XML

using parameter in header application/xml:

GET /test_seller/api/v1/accounts/ HTTP/1.1
Host: ssl.dotpay.pl
Authorization: Basic YXBpLnBcf4VsdzpZdHJlRGZyODE=
Accept: application/xml
Content-Type: application/xml

or using a parameter in resource address /accounts/?format=xml:

GET /test_seller/api/v1/accounts/?format=xml HTTP/1.1
Host: ssl.dotpay.pl
Authorization: Basic YXBpLnBcf4VsdzpZdHJlRGZyODE=

is going to return:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/",
      "id": "123456",
      "status": "active",
      "name": "Megastore Test Shop",
      "mcc_code": "7273",
      "main_url": "http://www.example.com/",
      "config": {
        "urlc": "http://www.example.com/confirmation/",
        "block_external_urlc": false,
        "pin": "cMhbAulyaQKnUUYbRL2EwK0hHZ5C7rkI"
      },
      "balance": [
        {
          "balance_amount": "7335.03",
          "balance_currency": "PLN"
        }
      ]
    }   
  ]
}

<root>
    <count>1</count>
    <next><next/>
        <previous><previous/>
            <results>
                <list-item>
                    <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/</href>
                    <id>123456</id>
                    <status>active</status>
                    <name>Megastore Test Shop</name>
                    <mcc_code>7273</mcc_code>
                    <main_url>http://www.example.com/</main_url>
                    <config>
                        <urlc>http://www.example.com/confirmation/</urlc>
                        <block_external_urlc>False</block_external_urlc>
                        <pin>cMhbAulyaQKnUUYbRL2EwK0hHZ5C7rkI</pin>
                    </config>
                    <balance>
                        <list-item>
                            <balance_amount>7335.03</balance_amount>
                            <balance_currency>PLN</balance_currency>
                        </list-item>
                    </balance>
                </list-item>
            </results>
</root>

API is able to communicate with json (default) or xml. Format choice is done by sending headers Accept and Content-Type or additional parameter format (sent by GET method) which value is named with one of the formats (json or xml).

Character encoding

Character encoding

For example json_encode function from PHP by default escapes diacritics (to \uXXXX ) and slashes '/' :

<?php
 $description = "Zażółć // Gęślą // Jaźń";
 $encoded = json_encode($description);
    echo "<pre>";
        echo "\nBefore json encode: ".$description;
        echo "\nAfter json encode: ".$encoded;
    echo "</pre>";
?>

is going to return (incorrect encoding for 'After json encode'):

Before json encode: Zażółć // Gęślą // Jaźń

After json encode: "Za\u017c\u00f3\u0142\u0107 \/\/ G\u0119\u015bl\u0105 \/\/ Ja\u017a\u0144"

In this case remember to use predefined constants JSON_UNESCAPED_UNICODE and JSON_UNESCAPED_SLASHES (sum of their values is 320) to avoid this problem:

<?php
 $description = "Zażółć // Gęślą // Jaźń";
 $encoded = json_encode($description, 320);
    echo "<pre>";
        echo "\nBefore json encode: ".$description;
        echo "\nAfter json encode: ".$encoded;
    echo "</pre>";
?>

is going to return (correct encoding for 'After json encode'):

Before json encode: Zażółć // Gęślą // Jaźń

After json encode: "Zażółć // Gęślą // Jaźń"

For some resources, requests sent to Dotpay require specific data, for example for payouts it would be receiver information.

Pagination

Pagination

For example for:
GEToperations/?page={int}&page_size={int}

is going to return response fragment as below:

{
  "count": 1271,
  "next": "https://ssl.dotpay.pl/test_seller/api/v1/operations/?page=3",
  "previous": "https://ssl.dotpay.pl/test_seller/api/v1/operations/",
  "results": [
    {
      "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9909-01234/",
      "number": "M9909-01234",
      "creation_datetime": "2019-05-06T12:12:04.375886",
      "type": "payment",
      "status": "rejected",
      "amount": "10.23",
      "currency": "PLN",
      "original_amount": "10.23",
      "original_currency": "PLN",
      "account_id": "123456",
      "related_operation": null,
      "description": "test payment - store 1",
      "control": "kdhsfsdf5sdfdsf",
      "payer": {
        "first_name": "Foo",
        "last_name": "Bar",
        "email": "foobar@example.com",
        "geoip_country": "POL"
      },
      "real_description": "",
      "status_datetime": "2019-05-06T12:15:05.079806"
    },
    {
      "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9396-21234/",
      "number": "M9396-21234",
      "creation_datetime": "2019-05-06T12:11:49.301974",
      "type": "payment",
      "status": "completed",
      "amount": "109.99",
      "currency": "PLN",
      "original_amount": "109.99",
      "original_currency": "PLN",
      "account_id": "654321",
      "related_operation": null,
      "description": "Zamowienie ze sklepu testowego 2 nr: asdfas3017738s6",
      "control": "asdfas3017738s6",
      "payer": {
        "first_name": "John",
        "last_name": "Pollack",
        "email": "john@example.com"
      },
      "status_datetime": "2019-05-06T12:11:51.738439"
    },

  ...

}

GET`operations/?page={int}&page_size={int}`

For a request which requires returning a larger amount of data API response is paginated (by default one page consists of 100 elements). The response includes next and previous values which contain address of next / previous page of the response while count has a number of returned objects in the whole response.

Meaning of values sent in request in order to filter response:

PROPERTY	TYPE	MEANING / DESCRIPTION
`page`	int	Page number
`page_size`	int	Number of elements displayed on one page (min value: 1 ; max value: 100 (default))

RESOURCES

User shops list (ID)

Resource returns a list of all shops (ID)
resource:

GETaccounts/

request headers

GET /test_seller/api/v1/accounts/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXNlcjU7UNDc6QVFNQWJxOIF2Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X GET "https://ssl.dotpay.pl/test_seller/api/v1/accounts/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers

HTTP/1.1 200 OK
Content-Type: application/[json|xml]; charset=utf-8
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/?format=json",
      "id": "123456",
      "status": "active",
      "name": "My Shop No. 1",
      "mcc_code": "7395",
      "main_url": "http://myshopisthebest.com",
      "config": {
        "urlc": "",
        "block_external_urlc": false,
        "pin": "Iu9ZgztcBWqnyUTgcOtJ4xlVylvIsqbF"
      },
      "balance": [
        {
          "balance_amount": "7335.03",
          "balance_currency": "PLN"
        }
      ]
    },  
    {
      "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/654321/?format=json",
      "id": "654321",
      "status": "active",
      "name": "My Shop No. 2",
      "mcc_code": "1761",
      "main_url": "http://www.example.com/",
      "config": {
        "urlc": "http://www.example.com/notification/",
        "block_external_urlc": true,
        "pin": "POklGh0u7YYzA48FHaBRWJLnmqKcTRji"
      },
      "balance": [
        {
          "balance_amount": "14081.10",
          "balance_currency": "EUR"
        },
        {
          "balance_amount": "531.92",
          "balance_currency": "PLN"
        }
      ]
    }
  ]
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <count>2</count>
  <next></next>
  <previous></previous>
  <results>
    <list-item>
      <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/?format=xml</href>
      <id>123456</id>
      <status>active</status>
      <name>My Shop No. 1</name>
      <mcc_code>7395</mcc_code>
      <main_url>http://dotpay.pl</main_url>
      <config>
        <urlc></urlc>
        <block_external_urlc>False</block_external_urlc>
        <pin>Iu9ZgztcBWqnyUTgcOtJ4xlVylvIsqbF</pin>
      </config>
      <balance>
        <list-item>
          <balance_amount>9362.69</balance_amount>
          <balance_currency>PLN</balance_currency>
        </list-item>
      </balance>
    </list-item>
    <list-item>
      <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/654321/?format=xml</href>
      <id>654321</id>
      <status>active</status>
      <name>My Shop No. 2</name>
      <mcc_code>1761</mcc_code>
      <main_url>http://www.example.com/</main_url>
      <config>
        <urlc>http://www.example.com/notification/</urlc>
        <block_external_urlc>True</block_external_urlc>
        <pin>POklGh0u7YYzA48FHaBRWJLnmqKcTRji</pin>
      </config>
      <balance>
        <list-item>
          <balance_amount>14081.10</balance_amount>
          <balance_currency>EUR</balance_currency>
        </list-item>
        <list-item>
          <balance_amount>726.35</balance_amount>
          <balance_currency>PLN</balance_currency>
        </list-item>
      </balance>
    </list-item>
  </results>
</root>

Below is an exemplary request (and response) using PHP and cURL library

<?php

 $ch = curl_init();
  curl_setopt ($ch, CURLOPT_URL,"https://ssl.dotpay.pl/test_seller/api/v1/accounts/");
  curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, TRUE);
  curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 2);
 // curl_setopt ($ch, CURLOPT_CAINFO, "ca-bundle.crt"); //http://curl.haxx.se/docs/caextract.html
  curl_setopt ($ch, CURLOPT_FOLLOWLOCATION, 1);
  curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt ($ch, CURLOPT_TIMEOUT, 100);
  curl_setopt ($ch, CURLOPT_USERPWD, 'user:password');

  $response = curl_exec($ch); // API response
  $curl_info = curl_getinfo($ch); //curl info
 curl_close($ch);

 echo "<pre>";
     echo "HTTP status code: ".$curl_info['http_code'];
     echo PHP_EOL."-------------------------".PHP_EOL.PHP_EOL;
     print_r(json_decode($response));
 echo "</pre>";
?>

response:

HTTP status code: 200
-------------------------

stdClass Object
(
 [count] => 2
 [next] => 
 [previous] => 
 [results] => Array
  (
   [0] => stdClass Object
    (
     [href] => https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/
     [id] => 123456
     [status] => active
     [name] => My Shop No. 1
     [mcc_code] => 7395
     [main_url] => http://myshopisthebest.com
     [config] => stdClass Object
      (
       [urlc] => 
       [block_external_urlc] => false
       [pin] => Iu9ZgztcBWqnyUTgcOtJ4xlVylvIsqbF
      )
     [balance] => stdClass Object
      (
       [balance_amount] => 7335.03
       [balance_currency] => PLN
      )
    )
   [1] => stdClass Object
    (
     [href] => https://ssl.dotpay.pl/test_seller/api/v1/accounts/654321/
     [id] => 654321
     [status] => active
     [name] => My Shop No. 2
     [mcc_code] => 1761
     [main_url] => http://www.example.com/
     [config] => stdClass Object
      (
       [urlc] => http://www.example.com/notification/
       [block_external_urlc] => true
       [pin] => POklGh0u7YYzA48FHaBRWJLnmqKcTRji
      )
     [balance] => stdClass Object
      (
       [balance_amount] => 14081.10
       [balance_currency] => EUR
      ),
      (
       [balance_amount] => 531.92
       [balance_currency] => PLN
      )
    )
  )
)

GET`accounts/`

List of all the shops to which logged in user has permissions.

PROPERTY	TYPE	MEANING / DESCRIPTION
`count`	string	number of available stores (ID) for logged in user
`next`	int	address of next page of response (pagination)
`previous`	string	address of prevous page of response (pagination)
`result`	string	result details

Shop details (ID)

Display details of store (ID) for which user has access
resource:

GETaccounts/{int: id}/

request headers

GET /test_seller/api/v1/accounts/652321/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X GET "https://ssl.dotpay.pl/test_seller/api/v1/accounts/654321/" \
     -u username: password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]; charset=utf-8
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

response:

    {
      "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/654321/?format=json",
      "id": "654321",
      "status": "active",
      "name": "My Shop",
      "mcc_code": "1761",
      "main_url": "http://www.example.com/",
      "config": {
        "urlc": "http://www.example.com/notification/",
        "block_external_urlc": true,
        "pin": "POklGh0u7YYzA48FHaBRWJLnmqKcTRji"
      },
      "balance": [
        {
          "balance_amount": "14081.10",
          "balance_currency": "EUR"
        },
        {
          "balance_amount": "531.92",
          "balance_currency": "PLN"
        }
      ]
    }

<?xml version="1.0" encoding="utf-8"?>
<root>
   <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/654321/?format=xml</href>
   <id>654321</id>
   <status>active</status>
   <name>My Shop No. 2</name>
   <mcc_code>1761</mcc_code>
   <main_url>http://www.example.com/</main_url>
   <config>
     <urlc>http://www.example.com/notification/</urlc>
     <block_external_urlc>True</block_external_urlc>
     <pin>POklGh0u7YYzA48FHaBRWJLnmqKcTRji</pin>
   </config>
   <balance>
     <list-item>
       <balance_amount>14081.10</balance_amount>
       <balance_currency>EUR</balance_currency>
     </list-item>
     <list-item>
       <balance_amount>726.35</balance_amount>
       <balance_currency>PLN</balance_currency>
     </list-item>
   </balance>
</root>

GET`accounts/{int: id}/`

Resource returns each shop details (ID) for which logged in user has permission.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
404 Not Found	shop not found
403 Forbidden	no permission

Meaning of values returned in table results:

PROPERTY	TYPE	MEANING / DESCRIPTION
`href`	string	API address where response for each shop (ID) is placed
`id`	int	shop number (ID)
`status`	string	shop status (ID)
`name`	string	shop name (ID)
`mcc_code`	string	business type code (MCC)
`main_url`	string	shop address (ID)
`config.urlc`	string	urlc notification address; address defined in administration panel to which are delivered urlc notifications
`config.block_external_urlc`	bool	block external urlc; ability to accept urlc address when initiating payment. Sending address in this way overwrites settings `config.urlc`.
`config.pin`	string	PIN (generated automatically when creating an account, you can change it by logging in by www to administration panel)
`balance.balance_amount`	string	amount of available account balance
`balance.balance_currency`	string	currency of available account balance

Shop payment channels list (ID)

Resource returns list of available payment channels for given shop (ID).

resource:

GETaccounts/{int: id}/channels/

request headers

GET /test_seller/api/v1/accounts/123456/channels/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]; charset=utf-8
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

response fragment:

  [
    {
      "id": 46,
      "name": "Płacę z Citi Handlowy",
      "logo": "https://ssl.dotpay.pl/t2/cloudfs1/magellan_media/payment_channel_logo/55796949dadfce3cbc9efdfd/",
      "group": "fast_transfers",
      "is_blocked_by_seller": false,
      "is_disabled": false,
      "is_offline": false
    },
    {
      "id": 11,
      "name": "Bank transfer / postal",
      "logo": "https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/payment_channel_logo/53b707a8dadfce7a89f5645c/",
      "group": "cash",
      "is_blocked_by_seller": false,
      "is_disabled": false,
      "is_offline": true
    },
    {
      "id": 248,
      "name": "Payment cards",
      "logo": "https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/payment_channel_logo/5874ef1edadfce7e43444a10/",
      "group": "credit_cards",
      "is_blocked_by_seller": false,
      "is_disabled": false,
      "is_offline": false
    },
  ]

<?xml version="1.0" encoding="utf-8"?>
<root>
  <list-item>
    <id>46</id>
    <name>Płacę z Citi Handlowy</name>
    <logo>https://ssl.dotpay.pl/t2/cloudfs1/magellan_media/payment_channel_logo/55796949dadfce3cbc9efdfd/</logo>
    <group>fast_transfers</group>
    <is_blocked_by_seller>False</is_blocked_by_seller>
    <is_disabled>False</is_disabled>
    <is_offline>False</is_offline>
  </list-item>
  <list-item>
    <id>11</id>
    <name>Bank transfer / postal</name>
    <logo>https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/payment_channel_logo/53b707a8dadfce7a89f5645c/</logo>
    <group>cash</group>
    <is_blocked_by_seller>False</is_blocked_by_seller>
    <is_disabled>False</is_disabled>
    <is_offline>True</is_offline>
  </list-item>
  <list-item>
    <id>248</id>
    <name>Payment cards</name>
    <logo>https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/payment_channel_logo/5874ef1edadfce7e43444a10/</logo>
    <group>credit_cards</group>
    <is_blocked_by_seller>False</is_blocked_by_seller>
    <is_disabled>False</is_disabled>
    <is_offline>False</is_offline>
  </list-item>
</root>

Below is exemplary request (and response) using PHP and cURL library.

<?php
 $ch = curl_init();
  curl_setopt ($ch, CURLOPT_URL, "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/channels/");
  curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, TRUE);
  curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 2);
  curl_setopt ($ch, CURLOPT_CAINFO, "ca-bundle.crt"); //http://curl.haxx.se/docs/caextract.html
  curl_setopt ($ch, CURLOPT_FOLLOWLOCATION, 1);
  curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt ($ch, CURLOPT_TIMEOUT, 100);
  curl_setopt ($ch, CURLOPT_USERPWD, 'user:password');

  $response = curl_exec($ch); // API response
  $curl_info = curl_getinfo($ch); //curl info
 curl_close($ch);

 echo "<pre>";
     echo "HTTP status code: ".$curl_info['http_code'];
     echo PHP_EOL."-------------------------".PHP_EOL.PHP_EOL;
     print_r(json_decode($response));
 echo "</pre>";
?>

response fragment:

HTTP status code: 200
-------------------------

Array
(
 [0] => stdClass Object
    (
        [id] => 6
        [name] => Przelew24
        [logo] => https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/payment_channel_logo/569d0b59dadfce09296b6be6/
        [group] => fast_transfers
        [is_blocked_by_seller] => 
        [is_disabled] => 
        [is_offline] => 
    )
 [1] => stdClass Object
    (
        [id] => 11
        [name] => Bank transfer / postal
        [logo] => https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/payment_channel_logo/53b707a8dadfce7a89f5645c/
        [group] => cash
        [is_blocked_by_seller] => 
        [is_disabled] => 
        [is_offline] => 1
    )
 [2] => stdClass Object
    (
        [id] => 248
        [name] => Payment cards
        [logo] => https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/payment_channel_logo/5874ef1edadfce7e43444a10/
        [group] => credit_cards
        [is_blocked_by_seller] => 
        [is_disabled] => 
        [is_offline] => 
    )

GET`accounts/{int: id}/channels/`

Resource returns list of available payment channels for given shop (ID).

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
404 Not Found	shop not found

Meaning of values returned in response:

PROPERTY	TYPE	MEANING / DESCRIPTION
`id`	int	payment channel number
`name`	string	payment channel name
`logo`	string	url address where payment channel logo is
`group`	string	payment channel group
`is_blocked_by_seller`	bool	channel is blocked by seller
`is_disabled`	bool	channel is disabled
`is_offline`	bool	channel is offline which means it cannot account payments in real time

Payment link generation

Resource allows to create payment links for a given shop (ID)
resource:

POSTaccounts/{int: id}/payment_links/

request headers

POST /test_seller/api/v1/accounts/123456/payment_links/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X POST "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \
     -d @data_to_post \

request (file @data_to_post in json or xml format):

{
   "amount": "73.60",
   "currency": "PLN",
   "description": "test payment from link",
   "control": "202cb9dsf52d23434ed",
   "language": "pl",
   "ignore_last_payment_channel": 1,
   "redirection_type": 0,
   "url": "https://example.com/back/",
   "urlc": "https://example.com/notification/",
   "payer": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "phone": "+48123456789",
      "address": {
         "street": "Wielicka",
         "building_number": "28B",
         "postcode": "30-552",
         "city": "Krakow",
         "region": "Malopolska",
         "country": "POL"
      }
   },
   "seller": {
      "p_info": "My Best Shop"
   }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <amount>73.60</amount>
    <control>202cb9dsf52d23434ed</control>
    <currency>PLN</currency>
    <description>test payment from link</description>
    <ignore_last_payment_channel>1</ignore_last_payment_channel>
    <language>pl</language>
    <payer>
        <address>
            <building_number>28B</building_number>
            <city>Krakow</city>
            <country>POL</country>
            <postcode>30-552</postcode>
            <region>Malopolska</region>
            <street>Wielicka</street>
        </address>
        <email>john.smith@example.com</email>
        <first_name>John</first_name>
        <last_name>Smith</last_name>
        <phone>+48123456789</phone>
    </payer>
    <type>0</type>
    <url>https://example.com/back/</url>
    <urlc>https://example.com/notification/</urlc>
    <seller>
        <p_info>My Best Shop</p_info> 
    </seller>
</root>

response headers:

HTTP/1.1 201 Created
Content-Type: application/[json|xml]; charset=utf-8
Vary: Accept
Allow: GET, POST, OPTIONS
Location: https://ssl.dotpay.pl/test_seller/api/v1/accounts/781633/payment_links/27oydgv6dnj38zud68u8wnjf5y60l1pk/

response:

{
   "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/774420/payment_links/u0njalbic3btgkkyjusmqnaa2goedylk/?format=json",
   "payment_url": "https://ssl.dotpay.pl/test_payment/?pid=u0njalbic3btgkkyjusmqnaa2goedylk",
   "token": "u0njalbic3btgkkyjusmqnaa2goedylk",
   "amount": "73.60",
   "currency": "PLN",
   "description": "test payment from link",
   "control": "202cb9dsf52d2343332",
   "language": "pl",
   "channel_id": null,
   "ch_lock": null,
   "onlinetransfer": null,
   "redirection_type": 0,
   "buttontext": null,
   "url": "https://example.com/back/",
   "urlc": "https://example.com/notification/",
   "expiration_datetime": null,
   "auto_reject_date": null,
   "payer": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "phone": "+48123456789",
      "address": {
         "street": "Wielicka",
         "building_number": "72",
         "flat_number": null,
         "postcode": "30-552",
         "city": "Krakow",
         "region": "Malopolska",
         "country": "POL"
      }
   },
   "recipient": {
      "account_number": "",
      "company": null,
      "first_name": null,
      "last_name": null,
      "address": {
         "street": null,
         "building_number": null,
         "flat_number": null,
         "postcode": null,
         "city": null
      }
   },
   "customer": null,
   "seller": {
      "p_info": null,
      "p_email": null,
      "p_www": null
   }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/774420/payment_links/12pswre6ex2z6ezfiyn5kawyzycjpym0/?format=xml</href>
   <payment_url>https://ssl.dotpay.pl/test_payment/?pid=12pswre6ex2z6ezfiyn5kawyzycjpym0</payment_url>
   <token>12pswre6ex2z6ezfiyn5kawyzycjpym0</token>
   <amount>73.60</amount>
   <currency>PLN</currency>
   <description>test payment from link</description>
   <control>202cb9dsf52d2343332</control>
   <language>pl</language>
   <channel_id />
   <ch_lock />
   <onlinetransfer />
   <redirection_type>0</redirection_type>
   <buttontext />
   <url>https://example.com/back/</url>
   <urlc>https://example.com/notification/</urlc>
   <expiration_datetime />
   <auto_reject_date />
   <payer>
      <first_name>John</first_name>
      <last_name>Smith</last_name>
      <email>john.smith@example.com</email>
      <phone>+48123456789</phone>
      <address>
         <street>Wielicka</street>
         <building_number>72</building_number>
         <flat_number />
         <postcode>30-552</postcode>
         <city>Krakow</city>
         <region>Malopolska</region>
         <country>POL</country>
      </address>
   </payer>
   <recipient>
      <account_number />
      <company />
      <first_name />
      <last_name />
      <address>
         <street />
         <building_number />
         <flat_number />
         <postcode />
         <city />
      </address>
   </recipient>
   <customer />
   <seller>
      <p_info />
      <p_email />
      <p_www />
   </seller>
</root>

If for the store you also need to send the chk parameter to Dotpay, you must calculate and add an additional parameter to the link generated by the api. Example of calculating the value of the chk parameter for a pay link in PHP:

<?php

##  Example Structure link payments of having to enter an additional parameter 'chk'



// PIN rewritten from account configuration (ID)
  $DotpayPin = "Oi9xSl8lE4cJhygjKn2L1MW2MBqkv234";

// optional parameter: indicates in what language the payment form should be presented after the payer's redirection
  $lang = "en";

// generated {token} for the payment link
  $pid = "rfhu4jb5ym657g3xluf4bbqfmbyj6t17";


### calculation of the 'chk' parameter value:

  // $chkchain = $DotpayPin . $lang . $pid; // if the 'lang' optional parameter was used
     $chkchain = $DotpayPin . $pid; 
          $chk = hash('sha256', $chkchain);

## ready payment link:

// $payment_link = "https://ssl.dotpay.pl/t2/?chk=" . $chk . "&pid=" . $pid . "&lang=" . $lang; // if the 'lang' optional parameter was used
   $payment_link = "https://ssl.dotpay.pl/t2/?chk=" . $chk . "&pid=" . $pid;

  echo $payment_link;

?>

POST`accounts/{int: id}/payment_links/`

Resource allows to create payment links for a given shop (ID).

Generating a payment link means creating a special token, which calling will allow you to define parameters listed in the request in advance thus making it impossible to modify payment data.

In case payment language was NOT specified or defined (parameter language), allows you to determine language on payment page lang.

Example of payment page with added parameter lang = en to present payment form in English:

https://ssl.dotpay.pl/t2/?pid=rfhu4jb5ym657g3xluf4bbqfmbyj6t17&lang=en

where the link components are: payment_url&lang=en

or: https://ssl.dotpay.pl/t2/?pid=token&lang=en

Additional parameters that can be added to the created payment link:

Name of the parameter	Type	MEANING / DESCRIPTION
`lang`	string	The language of the pages and payment forms presented
`buttontext`	string	Content that will be displayed on the button to return to the seller's website
`ignore_last_payment_channel`	string	ignoring the customer's last payment method
`expiration_date`	string	expiry date of the payment request
`p_info`	string	name of the payment recipient, which will be displayed to the customer on the Dotpay payment page
`p_email`	string	email address that will be displayed to the payer to contact the seller
`api_version`	string	api language version

Such a prepared link with a key can be sent for example by e-mail to a buyer.

Created payment link can be used repeatedly until it is deleted or expiration date expires if it was determined during its generation.

HTTP status code meaning:

HTTP status code	DESCRIPTION
201 Created	link generated
404 Not Found	shop not found

Meaning of values sent in request (except href, payment_url, token) and returned in response:

PROPERTY	TYPE	MEANING / DESCRIPTION
`href`	string	API address where generated link details are
`payment_url`	string	generated payment link
`token`	string	identification token
`amount`	decimal	amount
`currency`	string	currency - format: ISO 4217
`description`	string	description
`control`	string	parameter allowing to store string of 1000 characters (for example shop order number). Parameter is sent unchanged to seller service in URLC notification
`language`	string	language - format: ISO 639-1 (corresponding description to parameter `lang` in payment api)
`channel_id`	string	payment channel number
`ch_lock`	string	parameter allowing to lock selected channel
`onlinetransfer`	string	method of displaying offline channels on a payment page - WARNING: parameter temporary unavailable
`redirection_type`	string	type of redirection to seller shop after completed payment (corresponding description to parameter `type` in payment api)
`buttontext`	string	text of return to shop button
`url`	string	seller shop address where buyer is redirected to after completed payment
`urlc`	string	address where URLC notification is going to be sent
`expiration_datetime`	string	link expiration date - format: YYYY-MM-DDTHH:MM:SS
`payer.first_name`	string	buyer name
`payer.last_name`	string	buyer surname
`payer.email`	string	buyer email address
`payer.phone`	string	buyer phone number
`payer.address.street`	string	buyer street
`payer.address.building_number`	string	buyer building number
`payer.address.flat_number`	string	buyer flat number
`payer.address.postcode`	string	buyer postcode
`payer.address.city`	string	buyer city
`payer.address.region`	string	buyer region
`payer.address.country`	string	buyer country. Format ISO 3166-1 alfa-3
`recipient.account_number`	string	seller bank account number - format: IBAN
`recipient.company`	string	seller company name
`recipient.first_name`	string	seller name
`recipient.last_name`	string	seller surname
`recipient.address.street`	string	seller street
`recipient.address.building_number`	string	seller building number
`recipient.address.flat_number`	string	seller flat number
`recipient.address.postcode`	string	seller postcode
`recipient.address.city`	string	seller city
`seller.p_info`	string	the name of a payment receiver, which will be displayed on the payment Dotpay website
`seller.p_email`	string	This parameter describes an e-mail address, which will be seen by a customer

Caution!
By default for shop is also required sending the chk parameter. In the case of generating payment links from seller administration panel the chk parameter is automatically added to the link.

However for links generated by using this seller administration panel API chk value has to be calculated and added separately.

An example of a payment link structure in the situation when the requirement of sending the chk parameter is enabled for the seller's account (ID):
https://ssl.dotpay.pl/t2/?chk={chk}&pid={token}

Description of the method of calculating the parameter chk is included in the payment integration documentation in the chapter Redirection parameters integrity protection (CHK).

Payment link deletion

Payment link deletion
resource:

DELETEaccounts/{int: id}/payment_links/{token}/

request headers

DELETE /test_seller/api/v1/accounts/123456/payment_links/5e60d3r728trixvagqj7bds19r0irm31/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library.

curl -X DELETE "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/5e60d3r728trixvagqj7bds19r0irm31/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 204 No Content
Content-Type: application/[json|xml]; charset=utf-8
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS

DELETE`accounts/{int: id}/payment_links/{token}/`

Resource allows to delete generated payment link for a given shop (ID).

HTTP status code meaning:

HTTP status code	DESCRIPTION
204 No Content	link deleted
404 Not Found	shop not found

Payment links list

Payment links list
resource:

GETaccounts/{int: id}/payment_links/

request headers

GET /test_seller/api/v1/accounts/123456/payment_links/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXNlcjU4NDc6QVFNQWJxZEF2Qg==
Content-Type: application/[json|xml]

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]; charset=utf-8
Vary: Accept
Allow: GET, POST, OPTIONS

response:


{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/dct37t608pzod13p3zbk01uzdjy1wevq/?format=json",
            "payment_url": "https://ssl.dotpay.pl/test_payment/?pid=dct37t608pzod13p3zbk01uzdjy1wevq",
            "token": "dct37t608pzod13p3zbk01uzdjy1wevq",
            "amount": "73.60",
            "currency": "PLN",
            "description": "test payment from link",
            "control": "202cb9dsf52d2343332",
            "language": "pl",
            "channel_id": null,
            "ch_lock": null,
            "onlinetransfer": null,
            "redirection_type": 0,
            "buttontext": null,
            "url": "https://example.com/back/",
            "urlc": "https://example.com/notification/",
            "expiration_datetime": "2019-12-14T09:44:00.000000",
            "payer": {
                "first_name": "John",
                "last_name": "Smith",
                "email": "john.smith@example.com",
                "phone": "+48123456789",
                "address": {
                    "street": "Wielicka",
                    "building_number": "72",
                    "flat_number": null,
                    "postcode": "30-552",
                    "city": "Krakow",
                    "region": "Malopolska",
                    "country": "POL"
                }
            },
            "recipient": {
                "account_number": "PL52 9410 1010 6580 3100 2202 6989",
                "company": "Nazwa Firmy",
                "first_name": "Adam",
                "last_name": "Kowal",
                "address": {
                    "street": "Ukryta",
                    "building_number": "130",
                    "flat_number": null,
                    "postcode": "00-576",
                    "city": "Warszawa"
                }
            }
        },
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/a25b04svybudjepi62njbn5p5sl3cdir/?format=json",
            "payment_url": "https://ssl.dotpay.pl/test_payment/?pid=a25b04svybudjepi62njbn5p5sl3cdir",
            "token": "a25b04svybudjepi62njbn5p5sl3cdir",
            "amount": "2.00",
            "currency": "PLN",
            "description": "Order number 123465",
            "control": "6576576567fsd",
            "language": null,
            "channel_id": null,
            "ch_lock": null,
            "onlinetransfer": null,
            "redirection_type": 0,
            "buttontext": null,
            "url": "http://mywebsiteshop.com/back/",
            "urlc": null,
            "expiration_datetime": "2020-06-14T14:18:00.000000",
            "payer": {
                "first_name": "John",
                "last_name": "Smith",
                "email": "j.smith@example.com",
                "phone": null,
                "address": {
                    "street": "Niebieska",
                    "building_number": "1",
                    "flat_number": null,
                    "postcode": "11-111",
                    "city": "Krakow",
                    "region": null,
                    "country": "POL"
                }
            },
            "recipient": {
                "account_number": "",
                "company": null,
                "first_name": null,
                "last_name": null,
                "address": {
                    "street": null,
                    "building_number": null,
                    "flat_number": null,
                    "postcode": null,
                    "city": null
                }
            }
        }
    ]
}



<?xml version="1.0" encoding="UTF-8"?>
<root>
    <count>2</count>
    <next />
    <previous />
    <results>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/dct37t608pzod13p3zbk01uzdjy1wevq/?format=xml</href>
            <payment_url>https://ssl.dotpay.pl/test_payment/?pid=dct37t608pzod13p3zbk01uzdjy1wevq</payment_url>
            <token>dct37t608pzod13p3zbk01uzdjy1wevq</token>
            <amount>73.60</amount>
            <currency>PLN</currency>
            <description>test payment from link</description>
            <control>202cb9dsf52d2343332</control>
            <language>pl</language>
            <channel_id />
            <ch_lock />
            <onlinetransfer />
            <redirection_type>0</redirection_type>
            <buttontext />
            <url>https://example.com/back/</url>
            <urlc>https://example.com/notification/</urlc>
            <expiration_datetime>2019-12-14T09:44:00.000000</expiration_datetime>
            <payer>
                <first_name>John</first_name>
                <last_name>Smith</last_name>
                <email>john.smith@example.com</email>
                <phone>+48123456789</phone>
                <address>
                    <street>Wielicka</street>
                    <building_number>72</building_number>
                    <flat_number />
                    <postcode>30-552</postcode>
                    <city>Krakow</city>
                    <region>Malopolska</region>
                    <country>POL</country>
                </address>
            </payer>
            <recipient>
                <account_number>PL52 9410 1010 6580 3100 2202 6989</account_number>
                <company>Nazwa Firmy</company>
                <first_name>Adam</first_name>
                <last_name>Kowal</last_name>
                <address>
                    <street>Ukryta</street>
                    <building_number>130</building_number>
                    <flat_number />
                    <postcode>00-576</postcode>
                    <city>Warszawa</city>
                </address>
            </recipient>
        </list-item>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/a25b04svybudjepi62njbn5p5sl3cdir/?format=xml</href>
            <payment_url>https://ssl.dotpay.pl/test_payment/?pid=a25b04svybudjepi62njbn5p5sl3cdir</payment_url>
            <token>a25b04svybudjepi62njbn5p5sl3cdir</token>
            <amount>2.00</amount>
            <currency>PLN</currency>
            <description>Order number 123465</description>
            <control>6576576567fsd</control>
            <language />
            <channel_id />
            <ch_lock />
            <onlinetransfer />
            <redirection_type>0</redirection_type>
            <buttontext />
            <url>http://mywebsiteshop.com/back/</url>
            <urlc />
            <expiration_datetime>2020-06-14T14:18:00.000000</expiration_datetime>
            <payer>
                <first_name>John</first_name>
                <last_name>Smith</last_name>
                <email>j.smith@example.com</email>
                <phone />
                <address>
                    <street>Niebieska</street>
                    <building_number>1</building_number>
                    <flat_number />
                    <postcode>11-111</postcode>
                    <city>Krakow</city>
                    <region />
                    <country>POL</country>
                </address>
            </payer>
            <recipient>
                <account_number />
                <company />
                <first_name />
                <last_name />
                <address>
                    <street />
                    <building_number />
                    <flat_number />
                    <postcode />
                    <city />
                </address>
            </recipient>
        </list-item>
    </results>
</root>

GET`accounts/{int: id}/payment_links/`

Resource returns list of payment links for given shop (ID).

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
404 Not Found	shop not found

Payment link details

Payment link details
resource:

GETaccounts/{int: id}/payment_links/{token}/

request headers

GET /test_seller/api/v1/accounts/123456/payment_links/x7dked4kngwd5kza1xuhf4821udpfuxt/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXNlcjU4NDc6QVFNQWJxZEF2Qg==
Content-Type: application/[json|xml]

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept
Allow: GET, PUT, DELETE, OPTIONS

response:


{
   "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/781633/payment_links/x7dked4kngwd5kza1xuhf4821udpfuxt/?format=json",
   "payment_url": "https://ssl.dotpay.pl/test_payment/?pid=x7dked4kngwd5kza1xuhf4821udpfuxt",
   "token": "x7dked4kngwd5kza1xuhf4821udpfuxt",
   "amount": "123.90",
   "currency": "PLN",
   "description": "test payment from link",
   "control": "202cb943534gd2343332",
   "language": "pl",
   "channel_id": null,
   "ch_lock": null,
   "onlinetransfer": null,
   "redirection_type": null,
   "buttontext": null,
   "url": "https://example.com/back/",
   "urlc": "https://example.com/notification/",
   "expiration_datetime": "2020-11-14T09:44:00.000000",
   "auto_reject_date": null,
   "payer": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "phone": "+48123456789",
      "address": {
         "street": "Wielicka",
         "building_number": "28B",
         "flat_number": null,
         "postcode": "30-552",
         "city": "Krakow",
         "region": "Malopolska",
         "country": "POL"
      }
   },
   "recipient": {
      "account_number": "PL52 9410 1010 6580 3100 2202 6989",
      "company": "Nazwa Firmy",
      "first_name": "Adam",
      "last_name": "Kowal",
      "address": {
         "street": "Ukryta",
         "building_number": "130",
         "flat_number": null,
         "postcode": "00-576",
         "city": "Warszawa"
      }
   },
   "customer": null,
   "seller": {
      "p_info": null,
      "p_email": null,
      "p_www": null
   }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/781633/payment_links/x7dked4kngwd5kza1xuhf4821udpfuxt/?format=xml</href>
   <payment_url>https://ssl.dotpay.pl/test_payment/?pid=x7dked4kngwd5kza1xuhf4821udpfuxt</payment_url>
   <token>x7dked4kngwd5kza1xuhf4821udpfuxt</token>
   <amount>123.90</amount>
   <currency>PLN</currency>
   <description>test payment from link</description>
   <control>202cb943534gd2343332</control>
   <language>pl</language>
   <channel_id />
   <ch_lock />
   <onlinetransfer />
   <redirection_type />
   <buttontext />
   <url>https://example.com/back/</url>
   <urlc>https://example.com/notification/</urlc>
   <expiration_datetime>2020-11-14T09:44:00.000000</expiration_datetime>
   <auto_reject_date />
   <payer>
      <first_name>John</first_name>
      <last_name>Smith</last_name>
      <email>john.smith@example.com</email>
      <phone>+48123456789</phone>
      <address>
         <street>Wielicka</street>
         <building_number>28B</building_number>
         <flat_number />
         <postcode>30-552</postcode>
         <city>Krakow</city>
         <region>Malopolska</region>
         <country>POL</country>
      </address>
   </payer>
   <recipient>
      <account_number>PL52 9410 1010 6580 3100 2202 6989</account_number>
      <company>Nazwa Firmy</company>
      <first_name>Adam</first_name>
      <last_name>Kowal</last_name>
      <address>
         <street>Ukryta</street>
         <building_number>130</building_number>
         <flat_number />
         <postcode>00-576</postcode>
         <city>Warszawa</city>
      </address>
   </recipient>
   <customer />
   <seller>
      <p_info />
      <p_email />
      <p_www />
   </seller>
</root>

GET`accounts/{int: id}/payment_links/{token}/`

Resource returns details of a payment link for a given shop (ID).

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
404 Not Found	shop not found

Payout from shop account balance (ID) / Multipayout

Payout from shop account balance (ID) / Multipayout
resource:

POSTaccounts/{int: id}/payout/

request headers

POST /test_seller/api/v1/accounts/123456/payout/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXNlcjU4NDc6QVFNQWJxZEF2Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X POST "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payout/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \
     -d @data_to_post \

request (file @data_to_post in json or xml format including 2 payouts):

{
    "currency": "PLN",
    "transfers": [
        {
            "amount": "19.30",
            "control": "019e1921bfb1193965d1e",
            "description": "payout for JS",
            "recipient": {
                "account_number": "PL32249000896640389235035459",
                "name": "John Smith"
            }
        },
        {
            "amount": "56.20",
            "control": "3769978411",
            "description": "payout for PJ",
            "recipient": {
                "account_number": "PL33109032070768017608228474",
                "name": "Patrick Jones"
            }
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <currency>PLN</currency>
    <transfers>
        <list-item>
            <amount>19.30</amount>
            <control>019e1921bfb1193965d1e</control>
            <description>payout for JS</description>
            <recipient>
                <account_number>PL32249000896640389235035459</account_number>
                <name>John Smith</name>
            </recipient>
        </list-item>
        <list-item>
            <amount>56.20</amount>
            <control>3769978411</control>
            <description>payout for PJ</description>
            <recipient>
                <account_number>PL33109032070768017608228474</account_number>
                <name>Patrick Jones</name>
            </recipient>
        </list-item>
    </transfers>
</root>

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept
Allow: POST, OPTIONS

response:

{
  "detail": "ok"
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <detail>ok</detail>
</root>

Below is an exemplary request (and response) using PHP and cURL library.

request:

<?php

$fields = array(
    'currency' => 'PLN',
    'transfers' => array(
        array(
            'amount' => '19.30',
            'control' => '019e1921bfb1193965d1e',
            'description' => 'payout for JS',
            'recipient' => array(
                'account_number' => 'PL32249000896640389235035459',
                'name' => 'John Smith'
            )
        ),
        array(
            'amount' => '56.20',
            'control' => '3769978411',
            'description' => 'payout for PJ',
            'recipient' => array(
                'account_number' => 'PL33109032070768017608228474',
                'name' => 'Patrick Jones'
            )
        )
    )
);

$data = json_encode($fields, 320);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://ssl.dotpay.pl/test_seller/api/accounts/123456/payout/");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, TRUE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
//curl_setopt($ch, CURLOPT_CAINFO, "ca-bundle.crt"); //http://curl.haxx.se/docs/caextract.html
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 100);
curl_setopt($ch, CURLOPT_USERPWD, 'user:password');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data)
));

$response  = curl_exec($ch); // API response
$curl_info = curl_getinfo($ch); //curl info
curl_close($ch);

echo "<pre>";
echo "HTTP status code: " . $curl_info['http_code'];
echo PHP_EOL . "-------------------------" . PHP_EOL . PHP_EOL;
print_r(json_decode($response));
echo "</pre>";

?>

response:

HTTP status code: 200
-------------------------

stdClass Object
(
    [detail] => ok
)

POST`accounts/{int: id}/payout/`

Resource allows to create a payout from a shop account (ID). Executing a request type payout_any_amount operation for every transfers table object is created.

If an account number for payout (account_number)is not sent in the request, default account number set in the shop configuration (administration panel) is going to be used.

Information: if account (ID) is not properly configured, which depends on signed agreement, data sent in account_number will be ignored.

To check if transaction exists and what its status is resource operations/ might be used.

To optimize request we suggest filtering with account_id, type, creation_date_from and control (which is recommended to be unique), for example:

GET`https://ssl.dotpay.pl/test_seller/api/operations/?account_id=123456&type=payout_any_amount&creation_date_from=2019-02-15&control=qwerty123`

Advice:
In order to optimize process we suggest receiving a notifications urlc for payout_any_amount transactions for new status. Ask Dotpay to enable urlc notifications for this type of operation. As a result after registration of payment transaction you will be informed and will not need polling API as described above.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
403 Forbidden	access denied
404 Not Found	shop not found

Meaning of values sent in request:

PROPERTY	TYPE	MEANING / DESCRIPTION
`currency`	string	payout currency, format: ISO 4217
`transfers.amount`	decimal	payout amount given with hundredth part (always two places after the separator). The separator of the hundredth part is dot sign.
`transfers.control`	string	unique identifier of operation assigned by Seller
`transfers.description`	string	payout description
`transfers.recipient.account_number`	string	bank account number for payout (format: IBAN)
`transfers.recipient.name`	string	payout receiver name

OPERATIONS

Operations list

Displaying list of operations available for a given shop (ID)
resource:

GEToperations/

request headers

GET /test_seller/api/v1/operations/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X GET "https://ssl.dotpay.pl/test_seller/api/v1/operations/?type=payment&status=completed" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

response:

{
    "count": 428,
    "next": "https://ssl.dotpay.pl/test_seller/api/v1/operations/?page=2&status=completed&type=payment",
    "previous": null,
    "results": [
        {
            "operation_commission_amount": "-2.94",
            "operation_withdrawal_amount": "102.06",
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9987-19271/",
            "number": "M9987-19271",
            "creation_datetime": "2019-05-14T16:01:24.292901",
            "type": "payment",
            "status": "completed",
            "amount": "105.00",
            "currency": "PLN",
            "original_amount": "105.00",
            "original_currency": "PLN",
            "account_id": "123456",
            "related_operation": null,
            "description": "Nr zamówienia: 000000074/74",
            "control": "74",
            "payer": {
                "first_name": "Kacper",
                "last_name": "Nicpon",
                "email": "kacper.nicpon@example.com",
                "geoip_country": null
            },
            "status_datetime": "2019-05-14T16:01:26.081277"
        },
        {
            "operation_commission_amount": "-6.30",
            "operation_withdrawal_amount": "308.70",
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9916-08045/",
            "number": "M9916-08045",
            "creation_datetime": "2019-05-14T15:48:52.966608",
            "type": "payment",
            "status": "completed",
            "amount": "315.00",
            "currency": "PLN",
            "original_amount": "315.00",
            "original_currency": "PLN",
            "account_id": "654321",
            "related_operation": null,
            "description": "Order nr: 234234234",
            "control": "73423d22d2",
            "payer": {
                "first_name": "John",
                "last_name": "Pollack",
                "email": "johnp@example.com"
            },
            "status_datetime": "2019-05-14T15:48:54.780431"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <count>428</count>
    <next>https://ssl.dotpay.pl/test_seller/api/v1/operations/?page=2&amp;status=completed&amp;type=payment</next>
    <previous />
    <results>
        <list-item>
            <operation_commission_amount>-2.94</operation_commission_amount>
            <operation_withdrawal_amount>102.06</operation_withdrawal_amount>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/operations/M9987-19271/</href>
            <number>M9987-19271</number>
            <creation_datetime>2019-05-14T16:01:24.292901</creation_datetime>
            <type>payment</type>
            <status>completed</status>
            <amount>105.00</amount>
            <currency>PLN</currency>
            <original_amount>105.00</original_amount>
            <original_currency>PLN</original_currency>
            <account_id>123456</account_id>
            <related_operation />
            <description>Nr zamówienia: 000000074/74</description>
            <control>74</control>
            <payer>
                <first_name>Kacper</first_name>
                <last_name>Nicpon</last_name>
                <email>kacper.nicpon@example.com</email>
                <geoip_country />
            </payer>
            <status_datetime>2019-05-14T16:01:26.081277</status_datetime>
        </list-item>
        <list-item>
            <operation_commission_amount>-6.30</operation_commission_amount>
            <operation_withdrawal_amount>308.70</operation_withdrawal_amount>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/operations/M9916-08045/</href>
            <number>M9916-08045</number>
            <creation_datetime>2019-05-14T15:48:52.966608</creation_datetime>
            <type>payment</type>
            <status>completed</status>
            <amount>315.00</amount>
            <currency>PLN</currency>
            <original_amount>315.00</original_amount>
            <original_currency>PLN</original_currency>
            <account_id>654321</account_id>
            <related_operation />
            <description>Order nr: 234234234</description>
            <control>73423d22d2</control>
            <payer>
                <first_name>John</first_name>
                <last_name>Pollack</last_name>
                <email>johnp@example.com</email>
                <geoip_country />
            </payer>
            <status_datetime>2019-05-14T15:48:54.780431</status_datetime>
        </list-item>
    </results>
</root>

GET`operations/`

Resource returns a list of operations created for a given shop (ID) to which user has permission.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok

Meaning of parameters possible to send in request to filter the response:

PROPERTY	TYPE	MEANING / DESCRIPTION
`account_id`	int	shop ID (ID)
`type`	string	operation type; available values: `payment`, `payment_multimerchant_child`, `payout`, `payout_any_amount`, `refund`, `complaint`, `release_rollback`
`status`	string	operation status; available values: `new`, `processing`, `completed`, `rejected`, `processing_realization_waiting`, `processing_realization`
`creation_date_from`	string	from operation creation date ( format: YYYY-MM-DD )
`creation_date_to`	string	to operation creation date ( format: YYYY-MM-DD )
`status_date_from`	string	from the date of the last status of the operation ( format: YYYY-MM-DD )
`status_date_to`	string	to the date of the last status of the operation ( format: YYYY-MM-DD )
`description`	string	operation description (or its fragment)
`control`	string	operation control parameter (or its fragment)

Warning! Parameters: creation_date_(from|to) and status_date_(from|to) Please use interchangeable and do not connect them together in the same request.

Single operation details

Displaying details of single operation
resource:

GEToperations/{string:operation_number}/

request headers

GET /test_seller/api/v1/operations/M9987-19271/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Below is an exemplary request using and cURL library

curl -X GET "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9987-19271/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

Example 1, 'credit card registration' response:

{
    "operation_commission_amount": "0.00",
    "operation_withdrawal_amount": "0.00",
    "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9991-13333/?format=json",
    "number": "M9991-13333",
    "creation_datetime": "2018-12-06T09:37:40.316062",
    "type": "credit_card_registration",
    "status": "completed",
    "amount": "1.00",
    "currency": "PLN",
    "original_amount": "1.00",
    "original_currency": "PLN",
    "account_id": "123456",
    "related_operation": null,
    "description": "card registration",
    "control": "",
    "payer": {
        "first_name": "Jan",
        "last_name": "Kowalski",
        "email": "jan.kowalski@example.com",
        "geoip_country": null
    },
    "payment_method": {
        "channel_id": 248,
        "credit_card": {
            "href": "https://ssl.dotpay.pl/test_payment/payment_api/v1/cards/99bbfaa111a6e83967c7a2f2bf7c8d7f2fc2b637ytytd4138e7838dc765b4102e1577c3e4b2b74b453fb99d1d20ac1a6fb162886ac7db0819efc440c3315a019/",
            "issuer_identification_number": "401200",
            "masked_number": "XXXX XXXX XXXX 1112",
            "brand": {
                "name": "Visa",
                "codename": "visa",
                "logo": "https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/credit_card_brand/5b3dc9c1dadfce272760eb17/Visa_logo_200x100.png"
            },
            "id": "99bbfaa111a6e83967c7a2f2bf7c8d7f2fc2b637ytytd4138e7838dc765b4102e1577c3e4b2b74b453fb99d1d20ac1a6fb162886ac7db0819efc440c3315a019",
            "required_security_code": false,
            "remaining_daily_payment_limit": null,
            "expiration_date": {
                "expiration_year": "2020",
                "expiration_month": "12"
            },
            "unique_identifier": "11fcd1702c97c7c235fb80007b87d0452e18fbc35ab99d1cbcf9631b3676bb692c84bf50059b3f1ff2924d0a71d1967fe20bdc987603210972b054f825a6ac83"
        },
        "channel_country": "POL"
    },
    "real_description": "",
    "status_datetime": "2018-12-06T09:38:08.289731"
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <operation_commission_amount>0.00</operation_commission_amount>
    <operation_withdrawal_amount>0.00</operation_withdrawal_amount>
    <href>https://ssl.dotpay.pl/test_seller/api/v1/operations/M9991-13333/?format=xml</href>
    <number>M9991-13333</number>
    <creation_datetime>2018-12-06T09:37:40.316062</creation_datetime>
    <type>credit_card_registration</type>
    <status>completed</status>
    <amount>1.00</amount>
    <currency>PLN</currency>
    <original_amount>1.00</original_amount>
    <original_currency>PLN</original_currency>
    <account_id>123456</account_id>
    <related_operation />
    <description>card registration</description>
    <control />
    <payer>
        <first_name>Jan</first_name>
        <last_name>Kowalski</last_name>
        <email>jan.kowalski@example.com</email>
        <geoip_country />
    </payer>
    <payment_method>
        <channel_id>248</channel_id>
        <credit_card>
            <href>https://ssl.dotpay.pl/test_payment/payment_api/v1/cards/99bbfaa111a6e83967c7a2f2bf7c8d7f2fc2b637ytytd4138e7838dc765b4102e1577c3e4b2b74b453fb99d1d20ac1a6fb162886ac7db0819efc440c3315a019/</href>
            <issuer_identification_number>401200</issuer_identification_number>
            <masked_number>XXXX XXXX XXXX 1112</masked_number>
            <brand>
                <name>Visa</name>
                <codename>visa</codename>
                <logo>https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/credit_card_brand/5b3dc9c1dadfce272760eb17/Visa_logo_200x100.png</logo>
            </brand>
            <id>99bbfaa111a6e83967c7a2f2bf7c8d7f2fc2b637ytytd4138e7838dc765b4102e1577c3e4b2b74b453fb99d1d20ac1a6fb162886ac7db0819efc440c3315a019</id>
            <required_security_code>False</required_security_code>
            <remaining_daily_payment_limit />
            <expiration_date>
                <expiration_year>2020</expiration_year>
                <expiration_month>12</expiration_month>
            </expiration_date>
            <unique_identifier>11fcd1702c97c7c235fb80007b87d0452e18fbc35ab99d1cbcf9631b3676bb692c84bf50059b3f1ff2924d0a71d1967fe20bdc987603210972b054f825a6ac83</unique_identifier>
        </credit_card>
        <channel_country>POL</channel_country>
    </payment_method>
    <real_description />
    <status_datetime>2018-12-06T09:38:08.289731</status_datetime>
</root>

Example 2, 'payment completed', response:

{
    "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9937-13881/",
    "number": "M9937-13881",
    "creation_datetime": "2020-08-13T15:20:12.477408",
    "type": "payment",
    "status": "completed",
    "amount": "765.00",
    "currency": "PLN",
    "original_amount": "765.00",
    "original_currency": "PLN",
    "account_id": "123456",
    "related_operation": null,
    "description": "Platnosc ratalna za usluge",
    "control": "dfsdfs31212d",
    "payer": {
        "first_name": "John",
        "last_name": "Testowy",
        "email": "john@example.com"
    },
    "payment_method": {
        "channel_id": 55,
        "channel_reference_id": "CDEd3bdca6b2fa08bac2070ebf478183ad91668fd495a9884"
    },
    "status_datetime": "2020-08-13T15:20:14.232187"
}

<?xml version="1.0" encoding="utf-8"?>
<root>
    <href>https://ssl.dotpay.pl/test_seller/api/v1/operations/M9937-13881/?format=xml</href>
    <number>M9937-13881</number>
    <creation_datetime>2020-08-13T15:20:12.477408</creation_datetime>
    <type>payment</type>
    <status>completed</status>
    <amount>765.00</amount>
    <currency>PLN</currency>
    <original_amount>765.00</original_amount>
    <original_currency>PLN</original_currency>
    <account_id>123456</account_id>
    <related_operation></related_operation>
    <description>Platnosc ratalna za usluge</description>
    <control>dfsdfs31212d</control>
    <payer>
        <first_name>John</first_name>
        <last_name>Testowy</last_name>
        <email>john@example.com</email>
    </payer>
    <payment_method>
        <channel_id>55</channel_id>
        <channel_reference_id>CDEd3bdca6b2fa08bac2070ebf478183ad91668fd495a9884</channel_reference_id>
    </payment_method>
    <status_datetime>2020-08-13T15:20:14.232187</status_datetime>
</root>

Example 3, 'credit card payment rejected' with seller_code, response:

{
  "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9991-11135/?format=json",
  "number": "M9991-11135",
  "creation_datetime": "2020-10-07T12:44:36.573971",
  "type": "payment",
  "status": "rejected",
  "amount": "301.00",
  "currency": "PLN",
  "original_amount": "301.00",
  "original_currency": "PLN",
  "account_id": "123456",
  "related_operation": null,
  "description": "Payment for the order 23243",
  "control": "xcxgwfd54ereko6",
  "payer": {
    "first_name": "Jan",
    "last_name": "Kowal",
    "email": "Jan.Kowal-test@example.com",
    "geoip_country": null
  },
  "payment_method": {
    "channel_id": 248,
    "credit_card": {
      "issuer_identification_number": "411111",
      "masked_number": "XXXX XXXX XXXX 1111",
      "brand": {
        "name": "Visa",
        "codename": "visa",
        "logo": "https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/credit_card_brand/5b3dc9c1dadfce272760eb17/Visa_logo_200x100.png"
      }
    },
    "channel_country": "POL"
  },
    "real_description": "",
  "status_datetime": "2020-10-07T12:44:38.599311",
  "seller_code": "CC_INSUFFICIENT_FUNDS_OR_EXCEEDS_LIMIT"
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <href>https://ssl.dotpay.pl/test_seller/api/v1/operations/M9991-11135/?format=xml</href>
  <number>M9991-11135</number>
  <creation_datetime>2020-10-07T12:44:36.573971</creation_datetime>
  <type>payment</type>
  <status>rejected</status>
  <amount>301.00</amount>
  <currency>PLN</currency>
  <original_amount>301.00</original_amount>
  <original_currency>PLN</original_currency>
  <account_id>123456</account_id>
  <related_operation></related_operation>
  <description>Payment for the order 23243</description>
  <control>xcxgwfd54ereko6</control>
  <payer>
    <first_name>Jan</first_name>
    <last_name>Kowal</last_name>
    <email>Jan.Kowal-test@example.com</email>
    <geoip_country></geoip_country>
  </payer>
  <payment_method>
    <channel_id>248</channel_id>
    <credit_card>
      <issuer_identification_number>411111</issuer_identification_number>
      <masked_number>XXXX XXXX XXXX 1111</masked_number>
      <brand>
        <name>Visa</name>
        <codename>visa</codename>
        <logo>https://ssl.dotpay.pl/test_payment/cloudfs2/magellan_media/credit_card_brand/5b3dc9c1dadfce272760eb17/Visa_logo_200x100.png</logo>
      </brand>
    </credit_card>
    <channel_country>POL</channel_country>
  </payment_method>
  <real_description></real_description>
  <status_datetime>2020-10-07T12:44:38.599311</status_datetime>
  <seller_code>CC_INSUFFICIENT_FUNDS_OR_EXCEEDS_LIMIT</seller_code>
</root>

GET`operations/{string:operation_number}/`

Resource returns details of a given operation.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
404 Not Found	operation not found

Meaning of values returned in response:

PROPERTY	TYPE	MEANING / DESCRIPTION
`href`	string	API address where operation details are
`number`	string	operation number in Dotpay system
`creation_datetime`	string	creation date ( format: ISO 8601 (RFC 3339) )
`type`	string	operation type (see description of corresponding parameter `operation_type` in payment api)
`status`	string	operation status (see description of corresponding parameter `operation_status` in payment api)
`amount`	decimal	operation amount
`currency`	string	operation currency ( format: ISO 4217 )
`original_amount`	decimal	original operation amount
`original_currency`	string	original operation currency ( format: ISO 4217 )
`account_id`	int	shop number (ID)
`related_operation`	string	related operation (i.e. refund) if exists (see description of corresponding parameter `operation_related_number` in payment api)
`description`	string	operation description
`control`	string	operation control parameter (sent by seller service in payment order)
`payer.first_name`	string	buyer name
`payer.last_name`	string	buyer surname
`payer.email`	string	buyer email address
`status_datetime`	string	date of last transaction status ( format: ISO 8601 (RFC 3339) )

Additional / optional properties which might show up depending on shop configuration (ID):

PROPERTY	TYPE	MEANING / DESCRIPTION
`operation_commission_amount`	string	informs about collected commission for given operation, presented as a negative amount, therefore it contains the sign '-'
`operation_withdrawal_amount`	string	informs about withdrawal amount from given operation
`payer.geoip_country`	string	informs about country localization resulting from IP address from which payment was made. Format compatible with standard ISO 3166-1 (alpha-3)
`payment_method.channel_id`	int	payment channel number
`payment_method.channel_reference_id`	string	additional details of the operation, e.g. bank reference number
`payment_method.channel_country`	string	informs about country of payment processor through which payment was made. Format compatible with standard ISO 3166-1 (alpha-3)
`payment_method.payer_bank_account.name`	string	payment sender name
`payment_method.payer_bank_account.number`	string	bank account number which has been used to make the payment (format: IBAN)
`payment_method.credit_card.href`	string	link to details or to delete a card registered in Dotpay; presented only for operations with `completed` status
`payment_method.credit_card.issuer_identification_number`	string	credit card issuer identification number
`payment_method.credit_card.masked_number`	string	masked payment card number
`payment_method.credit_card.brand.name`	string	name of card type
`payment_method.credit_card.brand.codename`	string	codename of card type
`payment_method.credit_card.brand.logo`	string	logotype of card type
`payment_method.credit_card.id`	string	payment card id which can be used to make a payment without passing a full set of card data; presented only for operations with `completed` status
`payment_method.credit_card.required_security_code`	string	information if a payment by this payment card requires passing CVV2/CVC2 code; if `true`, the recurring payment using this card is impossible; however, 1-click payment requires passing additionally CVV2/CVC2 code
`payment_method.credit_card.remaining_daily_payment_limit`	string	information about remaining daily payment card limit; dictionary (e.g. {‘PLN’:500.00}) indexed by currency code and value of available limit this day is returned; this field is returned only in case of existing limit
`payment_method.credit_card.expiration_date.expiration_year`	string	year of card expiration date
`payment_method.credit_card.expiration_date.expiration_month`	string	month of card expiration date
`payment_method.credit_card.unique_identifier`	string	unique identifier of card registered in Dotpay (see description of corresponding parameter `credit_card_unique_identifier` in payment api)
`seller_code`	string	response code for rejected transactions, describing the possible reason for the refusal of the transaction. Examples of codes are presented in the table below.

Sample codes for rejected transactions returned in the parameter `seller code` :

`seller_code`	Description	Comments
CC_DO_NOT_HONOUR	The customer’s bank (Card Issuer) has declined the transaction. Only the customer can obtain a detailed reason for refusal from his bank.	you can repeat recurring payments
CC_AUTHORIZATION_DECLINED	The customer’s bank (Card Issuer) has declined the transaction.
CC_CARD_ABUSE	Card abuse (suspected fraud, card reported as lost or stolen).
CC_CONNECTION_FAIL_TO_THE_ISSUER	Problem with the connection to the card issuer's bank (the issuer's system is not available or not responding).	you can repeat recurring payments
CC_EXPIRED	Probably the card has expired or the wrong expiry date has been provided.
CC_INSUFFICIENT_FUNDS_OR_EXCEEDS_LIMIT	No funds or card limit exceeded.	you can repeat recurring payments
CC_INVALID_CARD_NUMBER	Incorrect card number, a card with this number does not exist.
CC_INVALID_CVV	The CVV code provided for the card is invalid.
CC_PAYMENT_NOT_SUPPORTED	The customer’s bank (Card Issuer) has declined the transaction. This card cannot be used for this type of transaction.
CC_RESTRICTED_STOLEN_LOST_CARD	Restricted card, reported as lost or stolen.

Warning! Card data are returned only for operations with completed status. To query details of operation again (eg. after receiving notification to address urlc about change of status) follow address given in href.

List of operations (payouts)

Displaying list of operations included in operation type payout
resource:

GEToperations/{string:operation_number}/operations/

request headers

GET /test_seller/api/v1/operations/M9987-19272/operations/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Below is an exemplary request using and cURL library

curl -X GET "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9987-19272/operations/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "operation_commission_amount": "-4.04",
            "operation_withdrawal_amount": "144.25",
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9963-12345/?format=json",
            "number": "M9963-12345",
            "creation_datetime": "2019-02-28T11:42:45.229309",
            "type": "payment",
            "status": "completed",
            "amount": "144.25",
            "currency": "PLN",
            "original_amount": "144.25",
            "original_currency": "PLN",
            "account_id": "123456",
            "related_operation": null,
            "description": "test payment No. 1",
            "control": "huQYtPHg",
            "payer": {
                "first_name": "Konrad",
                "last_name": "Kowal",
                "email": "Konrad.Kowal@example.com",
                "geoip_country": "POL"
            },
            "real_description": "",
            "status_datetime": "2019-02-28T11:43:25.396682"
        },
        {
            "operation_commission_amount": "-5.19",
            "operation_withdrawal_amount": "185.32",
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/operations/M9999-16718/?format=json",
            "number": "M9999-16718",
            "creation_datetime": "2019-02-28T11:30:45.374210",
            "type": "payment",
            "status": "completed",
            "amount": "185.32",
            "currency": "PLN",
            "original_amount": "185.32",
            "original_currency": "PLN",
            "account_id": "123456",
            "related_operation": null,
            "description": "test payment No. 2",
            "control": "RM1LVHj3",
            "payer": {
                "first_name": "John",
                "last_name": "Kruk",
                "email": "John.Kruk@example.com",
                "geoip_country": "POL"
            },
            "real_description": "",
            "status_datetime": "2019-02-28T11:31:15.118600"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <count>2</count>
    <next />
    <previous />
    <results>
        <list-item>
            <operation_commission_amount>-4.04</operation_commission_amount>
            <operation_withdrawal_amount>144.25</operation_withdrawal_amount>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/operations/M9963-12345/?format=xml</href>
            <number>M9963-12345</number>
            <creation_datetime>2019-02-28T11:42:45.229309</creation_datetime>
            <type>payment</type>
            <status>completed</status>
            <amount>144.25</amount>
            <currency>PLN</currency>
            <original_amount>144.25</original_amount>
            <original_currency>PLN</original_currency>
            <account_id>123456</account_id>
            <related_operation />
            <description>test payment No. 1</description>
            <control>huQYtPHg</control>
            <payer>
                <first_name>Konrad</first_name>
                <last_name>Kowal</last_name>
                <email>Konrad.Kowal@example.com</email>
                <geoip_country>POL</geoip_country>
            </payer>
            <real_description />
            <status_datetime>2019-02-28T11:43:25.396682</status_datetime>
        </list-item>
        <list-item>
            <operation_commission_amount>-5.19</operation_commission_amount>
            <operation_withdrawal_amount>185.32</operation_withdrawal_amount>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/operations/M9999-16718/?format=xml</href>
            <number>M9999-16718</number>
            <creation_datetime>2019-02-28T11:30:45.374210</creation_datetime>
            <type>payment</type>
            <status>completed</status>
            <amount>185.32</amount>
            <currency>PLN</currency>
            <original_amount>185.32</original_amount>
            <original_currency>PLN</original_currency>
            <account_id>123456</account_id>
            <related_operation />
            <description>test payment No. 2</description>
            <control>RM1LVHj3</control>
            <payer>
                <first_name>John</first_name>
                <last_name>Kruk</last_name>
                <email>John.Kruk@example.com</email>
                <geoip_country>POL</geoip_country>
            </payer>
            <real_description />
            <status_datetime>2019-02-28T11:31:15.118600</status_datetime>
        </list-item>
    </results>
</root>

GET`operations/{string:operation_number}/operations/`

Resource returns list of operations included in payout operation.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
404 Not Found	operation not found

PAYMENTS

Payment operations list

Displaying list of operations with type payment
resource:

GETpayments/

request headers

GET /test_seller/api/v1/payments/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X GET "https://ssl.dotpay.pl/test_seller/api/v1/payments/?creation_date_from=2019-05-14&status=completed" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

response:

{
    "count": 173,
    "next": "https://ssl.dotpay.pl/test_seller/api/v1/payments/?creation_date_from=2019-05-14&format=json&page=2&status=completed",
    "previous": null,
    "results": [
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/payments/M9137-11189/?format=json",
            "number": "M9137-11189",
            "creation_datetime": "2019-05-15T15:16:58.192314",
            "type": "payment",
            "status": "completed",
            "amount": "5.00",
            "currency": "PLN",
            "original_amount": "5.00",
            "original_currency": "PLN",
            "account_id": "654321",
            "related_operation": null,
            "description": "Abonament ABOf23fswefw34998f",
            "control": "sub:ABOf23fswefw34998f|5567",
            "payer": {
                "first_name": "John",
                "last_name": "Adams",
                "email": "adams@example.com"
            },
            "status_datetime": "2019-05-15T15:16:58.986617"
        },
        {
            "operation_commission_amount": "-6.30",
            "operation_withdrawal_amount": "308.70",
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/payments/M9916-58000/?format=json",
            "number": "M9916-58000",
            "creation_datetime": "2019-05-14T15:48:52.966608",
            "type": "payment",
            "status": "completed",
            "amount": "315.00",
            "currency": "PLN",
            "original_amount": "315.00",
            "original_currency": "PLN",
            "account_id": "123456",
            "related_operation": null,
            "description": "Order No.: 000000073/73",
            "control": "73",
            "payer": {
                "first_name": "Kacper",
                "last_name": "Kowal",
                "email": "kacper.kowal@example.com",
                "geoip_country": null
            },
            "status_datetime": "2019-05-14T15:48:54.780431"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <count>173</count>
    <next>https://ssl.dotpay.pl/test_seller/api/v1/payments/?creation_date_from=2019-05-14&amp;format=xml&amp;page=2&amp;status=completed</next>
    <previous />
    <results>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/payments/M9137-11189/?format=xml</href>
            <number>M9137-11189</number>
            <creation_datetime>2019-05-15T15:16:58.192314</creation_datetime>
            <type>payment</type>
            <status>completed</status>
            <amount>5.00</amount>
            <currency>PLN</currency>
            <original_amount>5.00</original_amount>
            <original_currency>PLN</original_currency>
            <account_id>654321</account_id>
            <related_operation />
            <description>Abonament ABOf23fswefw34998</description>
            <control>sub:ABOf23fswefw34998f|5567</control>
            <payer>
                <first_name>John</first_name>
                <last_name>Adams</last_name>
                <email>adams@example.com</email>
            </payer>
            <status_datetime>2019-05-15T15:16:58.986617</status_datetime>
        </list-item>
        <list-item>
            <operation_commission_amount>-6.30</operation_commission_amount>
            <operation_withdrawal_amount>308.70</operation_withdrawal_amount>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/payments/M9916-58000/?format=xml</href>
            <number>M9916-58000</number>
            <creation_datetime>2019-05-14T15:48:52.966608</creation_datetime>
            <type>payment</type>
            <status>completed</status>
            <amount>315.00</amount>
            <currency>PLN</currency>
            <original_amount>315.00</original_amount>
            <original_currency>PLN</original_currency>
            <account_id>123456</account_id>
            <related_operation />
            <description>Order No.: 000000073/73</description>
            <control>73</control>
            <payer>
                <first_name>Kacper</first_name>
                <last_name>Kowal</last_name>
                <email>kacper.kowal@example.com</email>
                <geoip_country />
            </payer>
            <status_datetime>2019-05-14T15:48:54.780431</status_datetime>
        </list-item>
    </results>
</root>

GET`payments/`

Details of single payment operation

Displaying details of single payment operation
resource:

GET/v1/payments/{string:operation_number}/

example corresponding to resource operations/{string: operation_number}/

Mark with `complete` flag

Marking operation type payment with complete flag
resource:

POSTpayments/{string: operation_number}/mark_as_complete/

request headers

POST /test_seller/api/v1/payments/M1234-56789/mark_as_complete/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X POST "https://ssl.dotpay.pl/test_seller/api/v1/payments/M1234-56789/mark_as_complete/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: POST, DELETE, OPTIONS

response:

{
  "detail": "ok"
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <detail>ok</detail>
</root>

In case of no permission to this operation:

response headers for HTTP status code: 403

HTTP/1.1 403 Forbidden
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: POST, OPTIONS

responses for HTTP status code: 403:

{
  "error_code": "UNKNOWN_ERROR",
  "detail": "error"
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <error_code>UNKNOWN_ERROR</error_code>
  <detail>error</detail>
</root>

POST`payments/{string: operation_number}/mark_as_complete/`

Resource allows to mark given operation (type: payment) with complete flag.

In payout configuration in Administration panel there is an option to activate creationof payouts only for operations marked with complete flag.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
403 Forbidden	no permission
404 Not Found	operation not found

Removing `complete` flag

Removing complete flag for operation type payment
resource:

DELETEpayments/{string: operation_number}/mark_as_complete/

request headers

DELETE /test_seller/api/v1/payments/M1234-56789/mark_as_complete/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X DELETE "https://ssl.dotpay.pl/test_seller/api/v1/payments/M1234-56789/mark_as_complete/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: POST, DELETE, OPTIONS

response:

{
  "detail": "ok"
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <detail>ok</detail>
</root>

In case of no permission to this operation:

response headers for HTTP status code: 403

HTTP/1.1 403 Forbidden
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: POST, OPTIONS

responses for HTTP status code: 403:

{
  "error_code": "UNKNOWN_ERROR",
  "detail": "error"
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <error_code>UNKNOWN_ERROR</error_code>
  <detail>error</detail>
</root>

DELETE`payments/{string: operation_number}/mark_as_complete/`

Resource allows to remove complete flag from a given operation (type: payment).

In payout configuration in Dotpay Administration panel, you can activate option that allows you to generate withdrawal request only from operations marked with complete flag.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
403 Forbidden	no permission
404 Not Found	operation not found

Payment refund

Payment refund type payment
resource:

POSTpayments/{string: operation_number}/refund/

request headers

POST /test_seller/api/v1/payments/M1234-56789/refund/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X POST "https://ssl.dotpay.pl/test_seller/api/v1/payments/M1234-56789/refund/" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \
     -d @data_to_post \

request (file @data_to_post in json or xml format including 2 payouts):

{
    "amount": "522.00",
    "description": "refund for transaction 3245",
    "control": "057badsg"
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <amount>23.22</amount>
  <description>refund for transaction 3245</description>
  <control>057badsg</control>
</root>

response headers for HTTP status code: 200:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: POST, OPTIONS

response:

{
  "detail": "ok"
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <detail>ok</detail>
</root>

response headers for HTTP status code: 403

HTTP/1.1 403 Forbidden
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: POST, OPTIONS

responses for HTTP status code: 403:

Case 1: Current balance is too low to realize this refund:

{
  "error_code": "INSUFFICIENT_FUNDS",
  "detail": "Not enough money to make refund, balance after refund will be \"-16.40 PLN\" and is less than \"0.00 PLN\""
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <error_code>INSUFFICIENT_FUNDS</error_code>
  <detail>Not enough money to make refund, balance after refund will be "-16.40 PLN" and is less than "0.00 PLN"</detail>
</root>

Case 2: for this operation refund has already been made (partial or total) and the remaining part of funds is insufficient to perform this operation:

{
  "error_code": "INVALID_AMOUNT",
  "detail": "Operation money \"185.32 PLN\", money already refunded / complaint / used for activation is \"145.00 PLN\", trying return \"122.00 PLN\""
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <error_code>INVALID_AMOUNT</error_code>
  <detail>Operation money "185.32 PLN", money already refunded / complaint / used for activation is "145.00 PLN", trying return "122.00 PLN"</detail>
</root>

Case 3: amount to be refunded is higher than amount of transaction itself:

{
  "error_code": "INVALID_AMOUNT",
  "detail": "Money \"522.00 PLN\" bigger than operation money \"185.32 PLN\""
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <error_code>INVALID_AMOUNT</error_code>
  <detail>Money "567.00 PLN" bigger than operation money "185.32 PLN"</detail>
</root>

Case 4: amount to be refunded is less than zero:

{
  "error_code": "INVALID_AMOUNT",
  "detail": "Money \"-12.00 PLN\" less or equal 0"
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <error_code>INVALID_AMOUNT</error_code>
  <detail>Money "-12.00 PLN" less or equal 0</detail>
</root>

Case 5: refunds are blocked for this account:

{
  "error_code": "BLOCKED_THE_POSSIBILITY",
  "detail": "Refunds are blocked for this account."
}

<?xml version="1.0" encoding="utf-8"?>
<root>
  <error_code>BLOCKED_THE_POSSIBILITY</error_code>
  <detail>Refunds are blocked for this account.</detail>
</root>

POST`payments/{string: operation_number}/refund/`

Resource allows to create a refund for a given operation.

HTTP status code meaning:

HTTP status code	DESCRIPTION
200 OK	ok
404 Not Found	operation not found
403 Forbidden	refusal to accept the request for refund; reason for refusal is given in parameters `error_code` and `detail`

Meaning returned errors for HTTP status code 403:

HTTP status code	`error_code`	exemplary description for `detail`
403 Forbidden	INSUFFICIENT_FUNDS	Not enough money to make refund, balance after refund will be \"-16.40 PLN\" and is less than \"0.00 PLN\"
403 Forbidden	INVALID_AMOUNT	Money \"522.00 PLN\" bigger than operation money \"185.32 PLN\"
403 Forbidden	INVALID_AMOUNT	Operation money \"185.32 PLN\", money already refunded / complaint / used for activation is \"145.00 PLN\", trying return \"122.00 PLN\"
403 Forbidden	INVALID_AMOUNT	Money \"-12.00 PLN\" less or equal 0
403 Forbidden	BLOCKED_THE_POSSIBILITY	Refunds are blocked for this account.

Meaning of values sent in request:

PROPERTY	TYPE	MEANING / DESCRIPTION
`amount`	decimal	refund amount
`description`	string	description
`control`	string	control parameter

REPORTS

Reports list

Displaying list of raports available for user
resource:

GETreports/

request headers

GET /test_seller/api/v1/reports/ HTTP/1.1
Host: ssl.dotpay.pl
Accept: application/[json|xml]
Authorization: Basic dXUYcjU7UNDc6QVFNQWJxOIT6Qg==
Content-Type: application/[json|xml]

Exemplary request using cURL library

curl -X GET "https://ssl.dotpay.pl/test_seller/api/v1/reports/?account_id=123456&creation_date_from=2019-01-01&creation_date_to=2019-02-20" \
     -u username:password
     -H'Accept: application/[json|xml]' \
     -H "Content-Type: application/[json|xml]" \

response headers:

HTTP/1.1 200 OK
Content-Type: application/[json|xml]
Vary: Accept-Encoding
Vary: Accept
Allow: GET, OPTIONS

response:



{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8708/",
            "creation_datetime": "2019-02-01T10:24:18.127714",
            "name": "report_invoice_PLN_123456_1-123456-ple-PLN-01-2019",
            "type": "ATOCA",
            "trigger": "Invoice",
            "format": "xlsx",
            "download_url": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8708/download/",
            "account_id": "123456"
        },
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8707/",
            "creation_datetime": "2019-02-01T10:24:18.127714",
            "name": "report_invoice_PLN_123456_1-123456-ple-PLN-01-2019",
            "type": "ATOCA",
            "trigger": "Invoice",
            "format": "csv",
            "download_url": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8707/download/",
            "account_id": "123456"
        },
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8634/",
            "creation_datetime": "2019-01-23T01:16:07.469652",
            "name": "report_operation_aggregation_PLN_123456__20190122_000000_20190123_000000",
            "type": "OAR",
            "trigger": "Daily",
            "format": "xlsx",
            "download_url": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8634/download/",
            "account_id": "123456"
        },
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8633/",
            "creation_datetime": "2019-01-23T01:16:07.469652",
            "name": "report_operation_aggregation_PLN_123456__20190122_000000_20190123_000000",
            "type": "OAR",
            "trigger": "Daily",
            "format": "csv",
            "download_url": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8633/download/",
            "account_id": "123456"
        },
        {
            "href": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8760/",
            "creation_datetime": "2019-01-25T02:15:29.947693",
            "name": "20190125021529_123456_M9171-93921_OAR",
            "type": "OAR",
            "trigger": "Payout",
            "format": "csv",
            "download_url": "https://ssl.dotpay.pl/test_seller/api/v1/reports/8760/download/",
            "account_id": "123456"
        }
    ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <count>5</count>
    <next />
    <previous />
    <results>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/reports/8708/</href>
            <creation_datetime>2019-02-01T10:24:18.127714</creation_datetime>
            <name>report_invoice_PLN_123456_1-123456-ple-PLN-01-2019</name>
            <type>ATOCA</type>
            <trigger>Invoice</trigger>
            <format>xlsx</format>
            <download_url>https://ssl.dotpay.pl/test_seller/api/v1/reports/8708/download/</download_url>
            <account_id>123456</account_id>
        </list-item>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/reports/8707/</href>
            <creation_datetime>2019-02-01T10:24:18.127714</creation_datetime>
            <name>report_invoice_PLN_123456_1-123456-ple-PLN-01-2019</name>
            <type>ATOCA</type>
            <trigger>Invoice</trigger>
            <format>csv</format>
            <download_url>https://ssl.dotpay.pl/test_seller/api/v1/reports/8707/download/</download_url>
            <account_id>123456</account_id>
        </list-item>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/reports/8634/</href>
            <creation_datetime>2019-01-23T01:16:07.469652</creation_datetime>
            <name>report_operation_aggregation_PLN_123456__20190122_000000_20190123_000000</name>
            <type>OAR</type>
            <trigger>Daily</trigger>
            <format>xlsx</format>
            <download_url>https://ssl.dotpay.pl/test_seller/api/v1/reports/8634/download/</download_url>
            <account_id>123456</account_id>
        </list-item>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/reports/8633/</href>
            <creation_datetime>2019-01-23T01:16:07.469652</creation_datetime>
            <name>report_operation_aggregation_PLN_123456__20190122_000000_20190123_000000</name>
            <type>OAR</type>
            <trigger>Daily</trigger>
            <format>csv</format>
            <download_url>https://ssl.dotpay.pl/test_seller/api/v1/reports/8633/download/</download_url>
            <account_id>123456</account_id>
        </list-item>
        <list-item>
            <href>https://ssl.dotpay.pl/test_seller/api/v1/reports/8760/</href>
            <creation_datetime>2019-01-25T02:15:29.947693</creation_datetime>
            <name>20190125021529_123456_M9171-93921_OAR</name>
            <type>OAR</type>
            <trigger>Payout</trigger>
            <format>csv</format>
            <download_url>https://ssl.dotpay.pl/test_seller/api/v1/reports/8760/download/</download_url>
            <account_id>123456</account_id>
        </list-item>
    </results>
</root>

GET`reports/`

Resource returns a list of reports created in all stores (ID) to which user have permission.

Meaning of values returned in table results:

PROPERTY	TYPE	MEANING / DESCRIPTION
href	string	API address where response is placed
creation_datetime	string	report creation date
name	string	report name
type	string	report type
trigger	string	trigger (possible values: `Invoice`, `Daily`, `Payout`)
format	string	report format (possible values: `csv`, `xlsx`, `pdf`, `mt940`)
download_url	string	report download address
account_id	int	shop number (ID)

Meaning of parameters possible to send in request to filter the response:

PROPERTY	TYPE	MEANING / DESCRIPTION
`account_id`	int	shop number (ID)
`creation_date_from`	string	from report creation date (format: YYYY-MM-DD)
`creation_date_to`	string	to report creation date (format: YYYY-MM-DD)
`type`	string	report type (eq `OAR`, `ATOCA`, `OAR_LEGACY`)
`trigger`	string	trigger (possible values: `Invoice`, `Daily`, `Payout`)

Routing table

In table below are listed all resources and their methods.

Resource methods:

RESOURCE	METHOD	DESCRIPTION
`accounts/`	GET	shops list (ID)
`accounts/{int: account_id}/`	GET	shop details (ID)
`accounts/{int: account_id}/channels/`	GET	shop payment channels list (ID)
`accounts/{int: account_id}/payment_links/`	POST	payment link generation
`accounts/{int: account_id}/payment_links/{string: token}/`	DELETE	payment link deletion
`accounts/{int: account_id}/payment_links/`	GET	payment links list
`accounts/{int: account_id}/payment_links/{string: token}/`	GET	payment link details
`accounts/{int: account_id}/payout/`	POST	payout from shop account balance (ID)

Methods for operations

RESOURCE	METHOD	DESCRIPTION
`operations/`	GET	operations list
`operations/{string: operation_number}/`	GET	single operation details
`operations/{string: operation_number}/operations/`	GET	list of operations included in payout operation

Payment methods

RESOURCE	METHOD	DESCRIPTION
`payments/`	GET	payment operations list
`payments/{string: operation_number}/`	GET	details of single payment operation
`payments/{string: operation_number}/mark_as_complete/`	POST	mark with “complete” flag
`payments/{string: operation_number}/mark_as_complete/`	DELETE	remove “complete” flag
`payments/{string: operation_number}/refund/`	POST	payment refund

Reports list

RESOURCE	METHOD	DESCRIPTION
`reports/`	GET	reports list

Change log

VERSION	DATE	CHANGES DESCRIPTION
1.71.10.1	2020-08-18	added a new optional parameter returned in operation details ( `seller_code` and sample requests )
1.71.10.1	2020-08-18	added a new optional parameter returned in operation details ( `channel_reference_id` and sample requests )
1.66.7.1	2020-02-18	new parameters added to Payment link (`p_info` and `p_email`), information on additional parameters for payment links has been supplemented, sample requests were updated
1.62.2.1	2019-10-30	new parameters added to filter operations list (`status_date_from` and `status_date_from`), typographical corrections
1.59.10.1	2019-07-09	typographical corrections
1.58.0.2	2019-06-03	typographical corrections (in the section of 'Payment link generation' - examples)
1.58.0.1	2019-05-30	typographical corrections
1.57.1.1	2019-05-15	creation of HTML version of this documentation, completion of data, added current examples
1.35.4.2	2017-04-06	added information about encoding to “III. INPUT / OUTPUT DATA FORMAT” section , syntax highlighting
1.35.4.1	2017-02-15	added parameter “buttontext” to resource /payment_links/
1.31.11.1	2016-07-07	added v1/reports/ resource , added „CHANGE LOG” section

This site uses cookies to deliver services and in accordance with the Privacy Policy.
You can specify the conditions for storage or access to cookies in your browser.

Seller administration panel APIv1.74.2.2 en

Introduction

Interface characteristics and address

Production environment:

Test environment:

Authentication and authorization

Authentication and authorization

GETaccounts/

request headers

response headers:

response:

HTTP status code meaning:

Requests limit number

Requests limit number

GETaccounts/

request headers:

response headers:

response:

HTTP status code meaning:

Input / output data format

Input / output data format

GETaccounts/

request headers

Format JSON

Format XML

Character encoding

Character encoding

Pagination

Pagination

GEToperations/?page={int}&page_size={int}

is going to return response fragment as below:

GEToperations/?page={int}&page_size={int}

RESOURCES

User shops list (ID)

Resource returns a list of all shops (ID)

resource:

GETaccounts/

request headers

Exemplary request using cURL library

response headers

response

response:

GETaccounts/

Shop details (ID)

Display details of store (ID) for which user has access

resource:

GETaccounts/{int: id}/

request headers

Exemplary request using cURL library

response headers:

response:

GETaccounts/{int: id}/

Shop payment channels list (ID)

resource:

GETaccounts/{int: id}/channels/

request headers

response headers:

response fragment:

response fragment:

GETaccounts/{int: id}/channels/

HTTP status code meaning:

Meaning of values returned in response:

Payment link generation

Resource allows to create payment links for a given shop (ID)

resource:

POSTaccounts/{int: id}/payment_links/

request headers

Exemplary request using cURL library

request (file @data_to_post in json or xml format):

response headers:

response:

POSTaccounts/{int: id}/payment_links/

Additional parameters that can be added to the created payment link:

HTTP status code meaning:

Payment link deletion

Payment link deletion

resource:

DELETEaccounts/{int: id}/payment_links/{token}/

request headers

Exemplary request using cURL library.

Seller administration panel API
v1.74.2.2 en

GET`accounts/`

GET`accounts/`

GET`accounts/`

GET`operations/?page={int}&page_size={int}`

GET`operations/?page={int}&page_size={int}`

GET`accounts/`

GET`accounts/`

GET`accounts/{int: id}/`

GET`accounts/{int: id}/`

GET`accounts/{int: id}/channels/`

GET`accounts/{int: id}/channels/`

POST`accounts/{int: id}/payment_links/`

POST`accounts/{int: id}/payment_links/`

DELETE`accounts/{int: id}/payment_links/{token}/`

DELETE`accounts/{int: id}/payment_links/{token}/`

GET`accounts/{int: id}/payment_links/`

GET`accounts/{int: id}/payment_links/`

GET`accounts/{int: id}/payment_links/{token}/`

GET`accounts/{int: id}/payment_links/{token}/`

POST`accounts/{int: id}/payout/`

POST`accounts/{int: id}/payout/`

GET`https://ssl.dotpay.pl/test_seller/api/operations/?account_id=123456&type=payout_any_amount&creation_date_from=2019-02-15&control=qwerty123`

GET`operations/`

GET`operations/`

GET`operations/{string:operation_number}/`

Example 3, 'credit card payment rejected' with `seller_code`, response:

GET`operations/{string:operation_number}/`

Sample codes for rejected transactions returned in the parameter `seller code` :

Displaying list of operations included in operation type `payout`

GET`operations/{string:operation_number}/operations/`