Wstęp

Adresy interfejsu

API panelu administracyjnego Sprzedawcy został wykonany w stylu architektury REST

Adresy pod którymi dostępny jest interfejs to:

Środowisko produkcyjne:

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

Środowisko testowe:

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

Uwierzytelnianie i autoryzacja

Uwierzytelnianie i autoryzacja

Przykładowo dla zasobu:
GETaccounts/

nagłówki żądania

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

po wykonaniu żądania z błędnym loginem / hasłem zostanie zwrócona odpowiedź:

nagłówki odpowiedzi:

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

odpowiedź:

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

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

Uwierzytelnianie do API następuje poprzez podanie (metodą HTTP Basic authentication ) loginu i hasła użytkownika analogicznych dla danych logowania do GUI panelu administracyjnego Sprzedawcy. Po wywołaniu danego zasobu API zostanie zwrócona odpowiedź z odpowiednim kodem odpowiedzi HTTP.

Jeśli zaistnieje taka potrzeba, to jak w zaprezentowanym przykładzie zostanie zwrócona własność detail z tekstowym opisem błędu.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
201 OK	ok
401 Unauthorized	nie udało się uwierzytelnić
403 Forbidden	brak uprawnień

Limit ilości żądań

Limit ilości żądań

Przykładowo dla zasobu:
GETaccounts/

nagłówki żądania

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

po wykonaniu zbyt dużej ilości żądań w jednostce czasu zostanie zwrócona odpowiedź:

nagłówki odpowiedzi:

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

odpowiedź:

{
  "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>

W celu eliminacji nadużyć API posiada limit ilości żądań w danej jednostce czasu. W przypadku gdy klient przekroczy limit zwracany jest kod błędu 429 Too Many Requests. Kolejny request należy ponowić po czasie określonym w nagłówku Retry-After. Szczegóły błędu zostaną zwrócone w odpowiedzi żądania we własności detail.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
429 Too Many Requests	przekroczony limit ilości żądań w czasie

Format danych wejścia/wyjścia

Format danych wejścia/wyjścia

W przypadku wywołania zasobów z parametrem format (jak w poniższych przykładach), API zwróci odpowiedź w danym formacie.

Przykładowo dla zasobu:
GETaccounts/

nagłówki żądania
Format JSON

użycie parametru w nagłówku 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

lub użycie parametru w adresie zasobu /accounts/?format=json:

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

Format XML

użycie parametru w nagłówku 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

lub użycie parametru w adresie zasobu /accounts/?format=xml:

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

zostanie zwrócona odpowiedź:

{
  "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 ma możliwość komunikacji w formacie json (domyślnie) lub xml. Wybór formatowania odbywa się za pomocą przesłania nagłówków Accept oraz Content-Type lub dodatkowego parametru format (przekazanego metodą GET ), którego wartością jest nazwa danego formatu (json lub xml).

Kodowanie znaków

Kodowanie znaków

Przykładowo funkcja json_encode z PHP domyślnie zamienia znaki diakrytyczne na format \uXXXX oraz stosuje znak ucieczki dla znaku '/' :

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

zwróci wynik (niepoprawne kodowanie dla '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"

W takim przypadku aby uniknąć tego problemu należy skorzystać z predefiniowanych stałych JSON_UNESCAPED_UNICODE oraz JSON_UNESCAPED_SLASHES (ich łączna wartość numeryczna wynosi 320):

<?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>";
?>

zwróci wynik (poprawne kodowanie dla 'After json encode'):

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

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

W przypadku niektórych zasobów, przesyłane do Dotpay żądania wymagają podania specyficznych informacji, przykładowo dla wypłat będą to dane odbiorcy.

Paginacja

Stronicowanie

Przykładowo dla zasobu:
GEToperations/?page={int}&page_size={int}

zostanie zwrócona odpowiedź jak poniższy fragment:

{
  "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}`

Dla żądań wymagających zwrócenia większej ilości danych odpowiedź API jest paginowana (domyślnie dla jednej strony wyświetlane jest maksymalnie 100 elementów). Odpowiedź zawiera własności next oraz previous, w których znajduje się adres kolejnej / poprzedniej strony odpowiedzi, natomiast we własności count znajduje się ilość obiektów zwróconych w całej odpowiedzi.

Znaczenie parametrów możliwych do przesyłania w żądaniu w celu filtrowania odpowiedzi:

Własność	Typ	Znaczenie/opis
`page`	int	numer strony
`page_size`	int	Ilość elementów wyświetlana na jednej stronie (min: 1 ; maks: 100)

ZASOBY

Lista sklepów (ID) użytkownika

Wyświetlenie listy sklepów (ID) dostępnych dla użytkownika
zasób:

GETaccounts/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:

{
  "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>

Poniżej został zamieszczony przykład żądania (oraz odpowiedzi) wykorzystujący język PHP oraz bibliotekę cURL.

<?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>";
?>

odpowiedź:

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/`

Zasób zwraca listę wszystkich sklepów, do których zalogowany użytkownik posiada uprawnienia.

Własność	Typ	Znaczenie/opis
`count`	string	ilość dostępnych sklepów (ID) dla zalogowanego użytkownika
`next`	int	adres kolejnej strony odpowiedzi (paginacja)
`previous`	string	adres poprzedniej strony odpowiedzi (paginacja)
`result`	string	szczegółowe dane wynikowe

Szczegóły sklepu (ID)

Wyświetlenie szczegółów danego sklepu (ID) dla którego użytkownik ma dostęp
zasób:

GETaccounts/{int: id}/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:

    {
      "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}/`

Zasób zwraca szczegóły danego sklepu (ID) do którego zalogowany użytkownik posiada uprawnienia.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
404 Not Found	nie znaleziono sklepu
403 Forbidden	brak uprawnień

Własności zwrócone w odpowiedzi:

Własność	Typ	Znaczenie/opis
`href`	string	adres API, pod którym znajduje się odpowiedź dla danego sklepu (ID)
`id`	int	numer sklepu (ID)
`status`	string	status sklepu (ID)
`name`	string	nazwa sklepu (ID)
`mcc_code`	string	kod kategorii sprzedaży (MCC)
`main_url`	string	adres sprzedażowy sklepu (ID)
`config.urlc`	string	adres powiadomień urlc; adres zdefiniowany w apanelu administracyjnym na który są dostarczane notyfikacje urlc
`config.block_external_urlc`	bool	blokuj zewnętrzne urlc; możliwość przyjmowania adresu urlc przy inicjowaniu płatności. Przesłanie w ten sposób adresu nadpisuje ustawienia `config.urlc`.
`config.pin`	string	PIN (generowany automatycznie przy zakładaniu konta, można go zmienić logując się poprzez www do panelu administracyjnego)
`balance.balance_amount`	string	kwota dostępnego salda konta
`balance.balance_currency`	string	waluta dostępnego salda konta

Lista kanałów płatności sklepu (ID)

Wyświetlenie listy dostępnych kanałów płatności dla danego sklepu (ID)

zasób:

GETaccounts/{int: id}/channels/

nagłówki żądania

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]

nagłówki odpowiedzi:

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

fragment odpowiedzi:

  [
    {
      "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>

Poniżej został zamieszczony przykład żądania (oraz odpowiedzi) wykorzystujący język PHP oraz bibliotekę cURL.

<?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>";
?>

fragment odpowiedzi:

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/`

Zasób zwraca listę dostępnych kanałów płatności dla danego sklepu (ID).

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
404 Not Found	nie znaleziono sklepu

Własności zwrócone w odpowiedzi:

Własność	Typ	Znaczenie/opis
`id`	int	numer kanału płatności
`name`	string	nazwa kanału płatności
`logo`	string	adres url, pod którym znajduje się logotyp kanału płatności
`group`	string	grupa do jakiej należy kanał płatności
`is_blocked_by_seller`	bool	blokada kanału przez Sprzedawcę
`is_disabled`	bool	kanał wyłączony
`is_offline`	bool	kanał w trybie offline, tj. nie jest w stanie zaksięgować płatności w czasie rzeczywistym

Tworzenie linku płatniczego

Tworzenie zakodowanych linków płatniczych dla danego sklepu (ID)
zasób:

POSTaccounts/{int: id}/payment_links/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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 \

żądanie (plik @data_to_post w formacie json xml):

{
   "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>

nagłówki odpowiedzi:

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/123456/payment_links/no68ellkfim0xoppj3212ygimgyfz7r1/

odpowiedź:

{
   "href": "https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/no68ellkfim0xoppj3212ygimgyfz7r1/?format=json",
   "payment_url": "https://ssl.dotpay.pl/test_payment/?pid=no68ellkfim0xoppj3212ygimgyfz7r1",
   "token": "no68ellkfim0xoppj3212ygimgyfz7r1",
   "amount": "73.60",
   "currency": "PLN",
   "description": "test payment from link",
   "control": "202cb9dsf52d23434ed",
   "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": "28B",
         "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": "My Best Shop",
      "p_email": null,
      "p_www": null
   }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <href>https://ssl.dotpay.pl/test_seller/api/v1/accounts/123456/payment_links/no68ellkfim0xoppj3212ygimgyfz7r1/?format=xml</href>
   <payment_url>https://ssl.dotpay.pl/test_payment/?pid=no68ellkfim0xoppj3212ygimgyfz7r1</payment_url>
   <token>no68ellkfim0xoppj3212ygimgyfz7r1</token>
   <amount>73.60</amount>
   <currency>PLN</currency>
   <description>test payment from link</description>
   <control>202cb9dsf52d23434ed</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>28B</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>My Best Shop</p_info>
      <p_email />
      <p_www />
   </seller>
</root>

Jeżeli dla sklepu wymagane jest przesłanie w przekierowaniu do Dotpay również parametru chk, do wygenerowanego przez api linku, należy wyliczyć i dodać dodatkowy parametr. Przykład wyliczenia wartości parametru chk dla linku płatniczego w języku PHP:

<?php

##  przykład konstrukcji linku płatniczego 
##  w przypadku konieczności podawania dodatkowego parametru 'chk'



// PIN przepisany z konfiguracji danego konta (ID)
  $DotpayPin = "Oi9xSl8lE4cJhygjKn2L1MW2MBqkv234";

// parametr opcjonalny: wskazuje w jakim języku ma być prezentowana formatka płatnicza po przekierowaniu płacącego
  $lang = "en";

// wygenerowany {token} dla linku płatniczego
  $pid = "rfhu4jb5ym657g3xluf4bbqfmbyj6t17";


### liczenie wartości parametru 'chk':

 // $chkchain = $DotpayPin . $lang . $pid; // gdy użyto dodatkowo parametru 'lang'
    $chkchain = $DotpayPin . $pid;
         $chk = hash('sha256', $chkchain);

## gotowy link płatniczy:

// $payment_link = "https://ssl.dotpay.pl/t2/?chk=" . $chk . "&pid=" . $pid . "&lang=" . $lang; // gdy użyto dodatkowo parametru 'lang'
   $payment_link = "https://ssl.dotpay.pl/t2/?chk=" . $chk . "&pid=" . $pid;

  echo $payment_link;

?>

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

Zasób pozwala stworzyć link płatniczy dla danego sklepu (ID).

Wygenerowanie linku do płatności oznacza utworzenie specjalnego tokenu, którego wywołanie pozwoli na odgórne zdefiniowanie wymienionych w żądaniu parametrów, a tym samym uniemożliwi modyfikację danych płatności.

W przypadku, gdy podczas tworzenia linku NIE zostanie zdefiniowany język płatności (parametr language), możliwe jest dodanie do utworzonego linku dodatkowego parametru lang co pozwoli określić język, w jakim wyświetlona ma zostać strona płatności.

Poniżej podany jest przykład wywołania strony płatności z dodatkowym parametrem lang = en w celu zaprezentowania formularza w języku angielskim:

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

gdzie składowe linku to payment_url&lang=en

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

Dodatkowe parametry, które mogą być dodane do utworzonego linku płatniczego:

Nazwa parametru	Typ	Znaczenie/opis
`lang`	string	Język prezentowanych stron i formularzy dokonywania płatności
`buttontext`	string	Treść, która zostanie wyświetlona na przycisku powrotu do serwisu sprzedawcy
`ignore_last_payment_channel`	string	ignorowanie ostatnio wybranej przez klienta metody płatności
`expiration_date`	string	data przedawnienia żądania płatności
`p_info`	string	nazwa odbiorcy płatności, która zostanie wyświetlona klientowi na stronie płatności serwisu Dotpay
`p_email`	string	adres e-mail, który zostanie wyświetlony kupującemu w celu kontaktu ze sprzedawcą
`api_version`	string	wersja wykorzystywanego api

Przygotowany link z tokenem można przykładowo przesłać w wiadomości e-mail do kupującego.

Utworzony link płatniczy może być wykorzystywany wielokrotnie, aż do momentu usunięcia go lub wygaśnięcia daty ważności jeśli ta została ustalona podczas jego generownia.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
201 Created	utworzono link
404 Not Found	nie znaleziono sklepu

Znaczenie własności przesyłanych w żądaniu (z wyjątkiem href, payment_url, token) oraz zwracanych w odpowiedzi:

Własność	Typ	Znaczenie/opis
`href`	string	adres API, pod którym znajdują się szczegóły utworzonego linku
`payment_url`	string	wygenerowany link płatniczy
`token`	string	token identyfikujący płatność
`amount`	decimal	kwota
`currency`	string	waluta - format: ISO 4217
`description`	string	opis płatności
`control`	string	parametr pozwalający na przechowanie ciągu (np. numeru zamówienia ze sklepu Sprzedawcy) o długości do 1000 znaków. Parametr w formie niezmienionej jest odsyłany do serwisu Sprzedawcy w powiadomieniu URLC
`language`	string	język - format: ISO 639-1 (analogiczny opis do parametru `lang` w payment api)
`channel_id`	string	numer kanału płatności
`ch_lock`	string	parametr umożliwiający zablokowanie określonego kanału płatności
`onlinetransfer`	string	sposób wyświetlenia kanałów offline na stronie płatności - UWAGA: parametr tymczasowo niedostępny
`redirection_type`	string	metoda odwołania do serwisu Sprzedawcy po dokonanej płatności (analogiczny opis do parametru `type` w payment api)
`buttontext`	string	treść przycisku powrotu do serwisu sprzedawcy
`url`	string	adres na który jest realizowany powrót do Sprzedawcy
`urlc`	string	adres na który zostanie przesłana notyfikacja URLC
`expiration_datetime`	string	data ważności linku - format: YYYY-MM-DDTHH:MM:SS
`payer.first_name`	string	imię osoby płacącej
`payer.last_name`	string	nazwisko osoby płacącej
`payer.email`	string	email osoby płacącej
`payer.phone`	string	telefon osoby płacącej
`payer.address.street`	string	ulica
`payer.address.building_number`	string	numer budynku
`payer.address.flat_number`	string	numer mieszkania
`payer.address.postcode`	string	kod pocztowy
`payer.address.city`	string	miasto
`payer.address.region`	string	region
`payer.address.country`	string	Nazwa kraju, z którego pochodzi osoba dokonująca płatność. Format zgodny ze standardem ISO 3166-1 alfa-3
`recipient.account_number`	string	numer rachunku odbiorcy płatności - format: IBAN
`recipient.company`	string	nazwa firmy odbiorcy płatności
`recipient.first_name`	string	imię odbiorcy płatności
`recipient.last_name`	string	nazwisko odbiorcy płatności
`recipient.address.street`	string	ulica
`recipient.address.building_number`	string	numer budynku
`recipient.address.flat_number`	string	numer mieszkania
`recipient.address.postcode`	string	kod pocztowy
`recipient.address.city`	string	miasto
`seller.p_info`	string	Nazwa odbiorcy płatności, która zostanie wyświetlona klientowi na stronie płatności serwisu Dotpay
`seller.p_email`	string	Adres e-mail, który zostanie wyświetlony kupującemu w celu kontaktu ze sprzedawcą

Uwaga!
Domyślnie dla sklepu wymagane jest przesłanie w przekierowaniu do Dotpay również parametru chk. W przypadku generowania linków płatniczych z poziomu panelu administracyjnego, parametr chk dodawany jest automatycznie do linku.

Natomiast, gdy link płatniczy generowany za pomocą niniejszego API panelu administracyjnego, konieczne jest wygenerowanie dodatkowo poprawnej wartości parametru chk oraz dołączenie jej do linku płatniczego.

Przykład konstrukcji linku płatniczego w sytuacji gdy dla danego konta (ID) włączona jest wymagalność przesyłania parametru chk :
https://ssl.dotpay.pl/t2/?chk={chk}&pid={token}

Opis sposobu wyliczenia parametru chk znajduje się w dokumentacji integracji płatności w rozdziale Ochrona integralności parametrów przekierowania (CHK).

Usunięcie linku płatniczego

Usnięcie linku płatniczego
zasób:

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

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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}/`

Zasób pozwala usunąć stworzony link płatniczy dla danego sklepu (ID).

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
204 No Content	poprawnie usunięto link
404 Not Found	nie znaleziono sklepu

Lista linków płatniczych

Lista linków płatniczych
zasób:

GETaccounts/{int: id}/payment_links/

nagłówki żądania

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]

nagłówki odpowiedzi:

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

odpowiedź:


{
    "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/`

Zasób zwraca listę linków płatniczych dla danego sklepu (ID).

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
404 Not Found	nie znaleziono sklepu

Szczegóły linku płatniczego

Wyświetlenie szczegółów konkretnego linku płatniczego
zasób:

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

nagłówki żądania

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]

nagłówki odpowiedzi:

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

odpowiedź:

{
   "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}/`

Zasób zwraca szczegóły danego linku płatniczego.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
404 Not Found	nie znaleziono sklepu

Wypłata środków z salda sklepu (ID) / Multiwypłata

Wypłata środków z salda sklepu / Multiwypłata
zasób:

POSTaccounts/{int: id}/payout/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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 \

żądanie (plik @data_to_post w formacie json lub xml zawierający 2 wypłaty):

{
    "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>

nagłówki odpowiedzi:

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

odpowiedź:

{
  "detail": "ok"
}

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

Poniżej został zamieszczony przykład żądania (oraz odpowiedzi) wykorzystujący język PHP oraz bibliotekę cURL.

żądanie:

<?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>";

?>

odpowiedź:

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

stdClass Object
(
    [detail] => ok
)

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

Zasób pozwala zlecić wypłatę środków z salda danego sklepu (ID). Wykonanie żądania powoduje powstanie operacji typu payout_any_amount dla każdego obiektu tablicy transfers.

Jeśli w żądaniu nie zostanie przesłany numer rachunku do wypłaty (account_number), to dla powstałej operacji zostanie przypisany domyślny numer rachunku określony w konfiguracji sklepu, w panelu administracyjnym.

Informacja: Brak odpowiedniej konfiguracji konta (ID), wynikającej z umowy, spowoduje zignorowanie danych przesłanych w account_number.

Powstanie oraz status operacji można zweryfikować za pomocą zasobu operations/.

W celu optymalizacji żądania sugerujemy filtrowanie ich za pomocą account_id, type, creation_date_from oraz control (wskazane jest, aby był on unikalny), na przykład:

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

Porada:
W celu optymalizacji procesu, sugerujemy odbiór notyfikacji urlc dla transakcji typu payout_any_amount& dla statusu new. Poproś Dotpay o włączenie notyfikacji urlc dla tego typu operacji. Dzięki temu po zarejestrowaniu transakcji wypłaty zostaniesz o tym poinformowany i nie będzie konieczne odpytywanie api zgodnie z powyższym opisem.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
403 Forbidden	brak uprawnień
404 Not Found	nie znaleziono sklepu

Znaczenie własności przesyłanych w żądaniu:

Własność	Typ	Znaczenie/opis
`currency`	string	waluta w jakiej dokonywane są wypłaty, format: ISO 4217
`transfers.amount`	decimal	kwota wypłacanych środków podana z częścią setną (zawsze dwa miejsca po separatorze). Separatorem części setnej jest znak kropki.
`transfers.control`	string	unikalny identyfikator operacjinadawany przez Sprzedawcę
`transfers.description`	string	opis wypłaty
`transfers.recipient.account_number`	string	numer konta bankowego, na który zostaną wypłacone środki (format: IBAN)
`transfers.recipient.name`	string	nazwa odbiorcy przelewu

OPERACJE

Lista operacji

Wyświetlenie listy operacji dostępnych dla danego użytkownika
zasób:

GEToperations/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:

{
    "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/`

Zasób zwraca listę operacji utworzonych we wszystkich sklepach (ID), do których dany użytkownik ma uprawnienia.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok

Znaczenie parametrów możliwych do przesyłania w żądaniu w celu filtrowania odpowiedzi:

Własność	Typ	Znaczenie/opis
`account_id`	int	numer sklepu (ID)
`type`	string	typ operacji; dostępne wartości: `payment`, `payment_multimerchant_child`, `payout`, `payout_any_amount`, `refund`, `complaint`, `release_rollback`
`status`	string	status operacji; dostępne wartości: `new`, `processing`, `completed`, `rejected`, `processing_realization_waiting`, `processing_realization`
`creation_date_from`	string	od daty utworzenia operacji ( format: YYYY-MM-DD )
`creation_date_to`	string	do daty utworzenia operacji ( format: YYYY-MM-DD )
`status_date_from`	string	od daty ostatniego statusu operacji ( format: YYYY-MM-DD )
`status_date_to`	string	do daty ostatniego statusu operacji ( format: YYYY-MM-DD )
`description`	string	opis (bądź jego fragment) operacji
`control`	string	parametr kontrolny (bądź jego fragment) operacji

Uwaga! Parametry: creation_date_(from|to) oraz status_date_(from|to) proszę używać zamiennie i nie łączyć ich razem w tym samym żądaniu.

Szczegóły pojedynczej operacji

Wyświetlenie szczegółów pojedynczej operacji
zasób:

GEToperations/{string:operation_number}/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

Przykład 1, 'rejestracja karty', odpowiedź:

{
    "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>

Przykład 2, 'płatność wykonana', odpowiedź:

{
    "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>

Przykład 3, 'płatność kartowa odmowna', zwracany seller_code, odpowiedź:

{
  "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}/`

Zasób zwraca szczegóły danej operacji.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
404 Not Found	nie znaleziono operacji

Znaczenie podstawowych własności zwracanych w odpowiedzi

Własność	Typ	Znaczenie/opis
`href`	string	adres API, pod którym znajdują się szczegóły danej operacji
`number`	string	numer operacji w systemie Dotpay
`creation_datetime`	string	data utworzenia operacji ( format: ISO 8601 (RFC 3339) )
`type`	string	typ operacji (zobacz opis analogicznego parametru `operation_type` w payment api)
`status`	string	status operacji (zobacz opis analogicznego parametru `operation_status` w payment api)
`amount`	decimal	kwota zaksięgowanej operacji
`currency`	string	waluta zaksięgowanej operacji ( format: ISO 4217 )
`original_amount`	decimal	oryginalna kwota przesłana w zleceniu płatności
`original_currency`	string	waluta kwoty przesłanej w zleceniu płatności ( format: ISO 4217 )
`account_id`	int	numer sklepu (ID)
`related_operation`	string	operacja powiązana (np. zwrot), jeśli takowa istnieje (zobacz opis analogicznego parametru `operation_related_number` w payment api)
`description`	string	opis operacji
`control`	string	parametr kontrolny operacji (przesłany przez serwis Sprzedawcy w zleceniu płatności)
`payer.first_name`	string	imię osoby dokonującej płatność
`payer.last_name`	string	nazwisko osoby dokonującej płatność
`payer.email`	string	email osoby dokonującej płatność
`status_datetime`	string	data ostatniego statusu transakcji ( format: ISO 8601 (RFC 3339) )

Dodatkowe / opcjonalne własności jakie mogą wystąpić w zależności od konfiguracji sklepu (ID):

Własność	Typ	Znaczenie/opis
`operation_commission_amount`	string	informuje o pobranej prowizji dla danej operacji, prezentowany jako kwota ujemna, dlatego zawiera znak '-'
`operation_withdrawal_amount`	string	informuje o kwocie wypłaty środków z danej operacji
`payer.geoip_country`	string	Informuje o lokalizacji kraju wynikającej z adresu IP z jakiego została wykonana płatność. Format zgodny ze standardem ISO 3166-1 (alfa-3)
`payment_method.channel_id`	int	numer kanału, jakim została wykonana płatność
`payment_method.channel_reference_id`	string	dodatkowe szczegóły operacji, np. bankowy numer referencyjny
`payment_method.channel_country`	string	informuje o kraju procesora płatności, poprzez którego została wykonana płatność. Format zgodny ze standardem ISO 3166-1 (alfa-3)
`payment_method.payer_bank_account.name`	string	nazwa nadawcy przelewu
`payment_method.payer_bank_account.number`	string	numer rachunku bankowego z jakiego została dokonana płatność (format: IBAN)
`payment_method.credit_card.href`	string	link do szczegółów, bądź usunięcia zarejestrowanej w Dotpay karty; prezentowany tylko dla operacji w stanie `completed`
`payment_method.credit_card.issuer_identification_number`	string	numer identyfikacyjny wydawcy karty
`payment_method.credit_card.masked_number`	string	zamaskowany numer karty
`payment_method.credit_card.brand.name`	string	nazwa typu karty
`payment_method.credit_card.brand.codename`	string	nazwa kodowa typu karty
`payment_method.credit_card.brand.logo`	string	logotyp typu karty
`payment_method.credit_card.id`	string	identyfikator karty, który można użyć do wykonania płatności bez podawania kompletu danych zapisanej wcześniej do usługi karty; prezentowany tylko dla operacji w stanie `completed`
`payment_method.credit_card.required_security_code`	string	informacja o tym czy płatność tą kartą wymaga każdorazowo podania kodu CVV2/CVC2; jeśli `true` to płatność cykliczna tą kartą nie jest możliwa, natomiast płatność 1-click wymaga podania dodatkowo kodu CVV2/CVC2
`payment_method.credit_card.remaining_daily_payment_limit`	string	informacja o pozostałym limicie dziennym na karcie; zwracany jest słownik (np. {'PLN': 500.00}) indeksowany kodem waluty z wartością, na którą można jeszcze wykonać płatności tego dnia; pole zwracane jest tylko w przypadku gdy limit występuje
`payment_method.credit_card.expiration_date.expiration_year`	string	rok wygaśnięcia karty
`payment_method.credit_card.expiration_date.expiration_month`	string	miesiąc wygaśnięcia karty
`payment_method.credit_card.unique_identifier`	string	unikalny identyfikator karty zarejestrowanej w Dotpay (zobacz opis analogicznego parametru `credit_card_unique_identifier` w payment api)
`seller_code`	string	kod odpowiedzi dla transakcji odmownych, opisujący możliwy powód odmowy realizacji transakcji. Przykładowe kody prezentowane są w poniższej tabeli.

Przykładowe kody dla transakcji odmownych zwracane w parametrze `seller_code` :

`seller_code`	Opis	Uwagi
CC_DO_NOT_HONOUR	Odmowa banku wystawcy karty, szczegółowy powód odmowy może uzyskać w swoim banku jedynie posiadacz karty.	można ponawiać płatności typu recurring
CC_AUTHORIZATION_DECLINED	Odmowa banku wystawcy karty.
CC_CARD_ABUSE	Nadużycie na karcie (podejrzenie oszustwa, karta zgłoszona jako zgubiona lub skradziona).
CC_CONNECTION_FAIL_TO_THE_ISSUER	Problem z połączeniem do banku wystawcy karty (system wystawcy nie jest dostępny lub nie odpowiada).	można ponawiać płatności typu recurring
CC_EXPIRED	Prawdopodobnie karta straciła ważność lub podano błędną datę ważności
CC_INSUFFICIENT_FUNDS_OR_EXCEEDS_LIMIT	Brak środków lub przekroczony limit na karcie.	można ponawiać płatności typu recurring
CC_INVALID_CARD_NUMBER	Błędny numer karty, karta o takim numerze nie istnieje.
CC_INVALID_CVV	Podany kod CVV dla karty jest nieprawidłowy.
CC_PAYMENT_NOT_SUPPORTED	Odmowa banku wystawcy karty. Ta karta nie może być używana do tego typu transakcji.
CC_RESTRICTED_STOLEN_LOST_CARD	Karta zastrzeżona, zgłoszona jako zgubiona lub skradziona.

Uwaga! Dane karty zwracane są tylko dla operacji w stanie completed. Ponowne odpytanie o szczegóły operacji (np. po uzyskaniu notyfikacji na adres urlc o zmianie statusu) należy wykonać na adres wskazany w href.

Lista operacji (wypłaty)

Wyświetlenie listy operacji zawartych operacji typu payout
zasób:

GEToperations/{string:operation_number}/operations/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:

{
    "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/`

Zasób zwraca listę operacji zawartych w operacji typu payout (wypłata).

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
404 Not Found	nie znaleziono operacji

PŁATNOŚCI

Lista operacji płatności

Wyświetlenie listy operacji płatności typu payment
zasób:

GETpayments/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:

{
    "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/`

Szczegóły pojedynczej operacji płatności

Wyświetlenie szczegółów pojedynczej operacji płatności typu payment
zasób:

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

przykład analogiczny do zasobu operations/{string: operation_number}/

Oznaczenie flagą `complete`

Oznaczenie flagą complete operacji płatności typu payment
zasób:

POSTpayments/{string: operation_number}/mark_as_complete/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:

{
  "detail": "ok"
}

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

W przypadku braku uprawnień użytkownika do tej operacji:

nagłówki odpowiedzi dla HTTP status code: 403

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

odpowiedzi dla 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/`

Zasób pozwala oznaczyć daną operację płatności (typ: payment) flagą complete.

W konfiguracji wypłat w panelu administracyjnym istnieje możliwość aktywacji opcji, która umożliwia generowanie polecenia wypłat środków jedynie z operacji oznaczonych flagą complete.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
403 Forbidden	brak uprawnień
404 Not Found	nie znaleziono operacji

Usunięcie flagi `complete`

Usunięcie flagi complete, którą została oznaczona dana operacja płatności typu payment
zasób:

DELETEpayments/{string: operation_number}/mark_as_complete/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:

{
  "detail": "ok"
}

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

W przypadku braku uprawnień użytkownika do tej operacji:

nagłówki odpowiedzi dla HTTP status code: 403

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

odpowiedzi dla 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/`

Zasób pozwala usunąć flagę complete, którą została oznaczona dana operacja płatności (typ: payment).

W konfiguracji wypłat w panelu administracyjnym istnieje możliwość aktywacji opcji, która umożliwia generowanie polecenia wypłat środków jedynie z operacji oznaczonych flagą complete.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
403 Forbidden	brak uprawnień
404 Not Found	nie znaleziono operacji

Zwrot operacji płatności

Zwrot operacji płatności typu payment
zasób:

POSTpayments/{string: operation_number}/refund/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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 \

żądanie (plik @data_to_post w formacie json lub xml zawierający 2 wypłaty):

{
    "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>

nagłówki odpowiedzi dla HTTP status code: 200:

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

odpowiedź:

{
  "detail": "ok"
}

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

nagłówki odpowiedzi dla HTTP status code: 403

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

odpowiedzi dla HTTP status code: 403:

Przypadek 1: Bieżące saldo jest zbyt niskie aby zrealizować ten zwrot:

{
  "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>

Przypadek 2: dla tej operacji był już dokonany zwrot (częściowy lub całkowity) a pozostała część środków jest niewystarczająca do wykonania tej operacji:

{
  "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>

Przypadek 3: podana kwota do zwrotu jest wyższa od kwoty samej transakcji:

{
  "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>

Przypadek 4: podana kwota do zwrotu jest mniejsza od zera:

{
  "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>

Przypadek 5: zwroty są zablokowane dla tego konta:

{
  "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/`

Zasób pozwala zlecić zwrot danej operacji płatności.

Znaczenie zwracanych kodów odpowiedzi HTTP:

HTTP status code	OPIS
200 OK	ok
404 Not Found	nie znaleziono operacji
403 Forbidden	odmowa przyjęcia żądania zwrotu; przyczyna odmowy podan jest w parametrach `error_code` oraz `detail`

Znaczenie zwracanych błędów dla HTTP status code 403:

HTTP status code	`error_code`	przykładowy opis dla `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.

Znaczenie własności przesyłanych w żądaniu:

Własność	Typ	Znaczenie/opis
`amount`	decimal	kwota zwrotu
`description`	string	opis
`control`	string	Parametr kontrolny

RAPORTY

Lista raportów

Wyświetlenie listy raportów dostępnych dla użytkownika
zasób:

GETreports/

nagłówki żądania

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]

Przykładowe żądanie z wykorzystaniem biblioteki cURL

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]" \

nagłówki odpowiedzi:

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

odpowiedź:



{
    "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/`

Zasób zwraca listę raportów utworzonych we wszystkich sklepach (ID), do których dany użytkownik ma uprawnienia.

Znaczenie własności zwracanych w tablicy results:

Własność	Typ	Znaczenie/opis
href	string	adres API, pod którym znajdują się szczegóły danego raportu
creation_datetime	string	data utworzenia raportu
name	string	nazwa raportu
type	string	typ raportu
trigger	string	przełącznik (możliwe wartości: `Invoice`, `Daily`, `Payout`)
format	string	format raportu (możliwe wartości: `csv`, `xlsx`, `pdf`, `mt940`)
download_url	string	adres do pobrania raportu
account_id	int	numer sklepu (ID), którego dotyczy raport

Znaczenie parametrów możliwych do przesyłania w żądaniu w celu filtrowania odpowiedzi:

Własność	Typ	Znaczenie/opis
`account_id`	int	numer sklepu (ID)
`creation_date_from`	string	od daty utworzenia raportu (format: YYYY-MM-DD)
`creation_date_to`	string	do daty utworzenia raportu (format: YYYY-MM-DD)
`type`	string	typ raportu (np. `OAR`, `ATOCA`, `OAR_LEGACY`)
`trigger`	string	przełącznik (możliwe wartości: `Invoice`, `Daily`, `Payout`)

Tabela routingu

W poniższej tabeli zostały zestawione zasoby oraz metody ich wywołania.

Metody dotyczące zasobów:

Zasób	Metoda	Znaczenie/opis
`accounts/`	GET	lista sklepów (ID) użytkownika
`accounts/{int: account_id}/`	GET	szczegóły sklepu (ID)
`accounts/{int: account_id}/channels/`	GET	lista kanałów płatności sklepu (ID)
`accounts/{int: account_id}/payment_links/`	POST	utworzenie linku płatniczego
`accounts/{int: account_id}/payment_links/{string: token}/`	DELETE	usunięcie linku płatniczego
`accounts/{int: account_id}/payment_links/`	GET	lista linków płatniczych
`accounts/{int: account_id}/payment_links/{string: token}/`	GET	szczegóły linku płatniczego
`accounts/{int: account_id}/payout/`	POST	wypłata środków z

Metody dotyczące operacji

Zasób	Metoda	Znaczenie/opis
`operations/`	GET	lista operacji
`operations/{string: operation_number}/`	GET	szczegóły pojedynczej operacji
`operations/{string: operation_number}/operations/`	GET	lista operacji zawartych w operacji payout

Metody dotyczące płatności

Zasób	Metoda	Znaczenie/opis
`payments/`	GET	lista operacji płatności
`payments/{string: operation_number}/`	GET	szczegóły pojedynczej operacji płatności
`payments/{string: operation_number}/mark_as_complete/`	POST	oznaczenie flagą "complete"
`payments/{string: operation_number}/mark_as_complete/`	DELETE	usunięcie flagi "complete"
`payments/{string: operation_number}/refund/`	POST	zwrot operacji płatności

Lista raportów

Zasób	Metoda	Znaczenie/opis
`reports/`	GET	lista raportów

Dziennik zmian

Wersja	Data	Opis zmian
1.74.2.1	2020-11-16	dodano nowy opcjonalny parametr zwracany w szczegółach operacji ( `seller_code` oraz przykłady )
1.71.10.1	2020-08-18	dodano nowy opcjonalny parametr zwracany w szczegółach operacji ( `channel_reference_id` oraz przykłady )
1.66.7.1	2020-02-18	dodano nowe parametry do obsługi linków płatniczych (`p_info` i `p_email`), uzupełniono informacje na temat parametrów dodatkowych do linków płatniczych, oraz przykłady
1.62.2.1	2019-10-30	dodano nowe parametry do filtrowania listy operacji (`status_date_from` i `status_date_from`)
1.59.10.1	2019-07-09	poprawki typograficzne
1.58.0.2	2019-06-03	poprawki typograficzne (w sekcji 'Tworzenie linku płatniczego' - przykłady)
1.58.0.1	2019-05-30	poprawki typograficzne
1.57.1.1	2019-05-22	utworzenie wersji HTML niniejszej dokumentacji, uzupełnienie danych, dodanie aktualnych przykładów
1.35.4.2	2017-04-06	dodanie informacji o kodowaniu do rozdziału „III. FORMAT DANYCH WEJŚCIA / WYJŚCIA” , kolorowanie składni
1.35.4.1	2017-02-15	dodanie parametru „buttontext” do zasobu /payment_links/
1.31.11.1	2016-07-07	dodanie zasobu /v1/reports/ , dodanie rozdziału „DZIENNIK ZMIAN”

Strona korzysta z plików cookies w celu realizacji usług i zgodnie z Polityką prywatności.
Możesz określić warunki przechowywania lub dostępu do plików cookies w Twojej przeglądarce.

API panelu administracyjnegov1.74.2.2 pl

Wstęp

Adresy interfejsu

Środowisko produkcyjne:

Środowisko testowe:

Uwierzytelnianie i autoryzacja

Uwierzytelnianie i autoryzacja

GETaccounts/

nagłówki żądania

nagłówki odpowiedzi:

odpowiedź:

Znaczenie zwracanych kodów odpowiedzi HTTP:

Limit ilości żądań

Limit ilości żądań

GETaccounts/

nagłówki żądania

nagłówki odpowiedzi:

odpowiedź:

Znaczenie zwracanych kodów odpowiedzi HTTP:

Format danych wejścia/wyjścia

Format danych wejścia/wyjścia

GETaccounts/

nagłówki żądania

Format JSON

Format XML

Kodowanie znaków

Kodowanie znaków

Paginacja

Stronicowanie

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

zostanie zwrócona odpowiedź jak poniższy fragment:

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

ZASOBY

Lista sklepów (ID) użytkownika

Wyświetlenie listy sklepów (ID) dostępnych dla użytkownika

zasób:

GETaccounts/

nagłówki żądania

Przykładowe żądanie z wykorzystaniem biblioteki cURL

nagłówki odpowiedzi:

odpowiedź:

odpowiedź:

GETaccounts/

Szczegóły sklepu (ID)

Wyświetlenie szczegółów danego sklepu (ID) dla którego użytkownik ma dostęp

zasób:

GETaccounts/{int: id}/

nagłówki żądania

Przykładowe żądanie z wykorzystaniem biblioteki cURL

nagłówki odpowiedzi:

odpowiedź:

GETaccounts/{int: id}/

Lista kanałów płatności sklepu (ID)

zasób:

GETaccounts/{int: id}/channels/

nagłówki żądania

nagłówki odpowiedzi:

fragment odpowiedzi:

fragment odpowiedzi:

GETaccounts/{int: id}/channels/

Znaczenie zwracanych kodów odpowiedzi HTTP:

Własności zwrócone w odpowiedzi:

Tworzenie linku płatniczego

Tworzenie zakodowanych linków płatniczych dla danego sklepu (ID)

zasób:

POSTaccounts/{int: id}/payment_links/

nagłówki żądania

Przykładowe żądanie z wykorzystaniem biblioteki cURL

żądanie (plik @data_to_post w formacie json xml):

nagłówki odpowiedzi:

odpowiedź:

POSTaccounts/{int: id}/payment_links/

Dodatkowe parametry, które mogą być dodane do utworzonego linku płatniczego:

Znaczenie zwracanych kodów odpowiedzi HTTP:

Usunięcie linku płatniczego

Usnięcie linku płatniczego

zasób:

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

nagłówki żądania

Przykładowe żądanie z wykorzystaniem biblioteki cURL

API panelu administracyjnego
v1.74.2.2 pl

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}/`

Przykład 3, 'płatność kartowa odmowna', zwracany `seller_code`, odpowiedź:

GET`operations/{string:operation_number}/`

Przykładowe kody dla transakcji odmownych zwracane w parametrze `seller_code` :

Wyświetlenie listy operacji zawartych operacji typu `payout`

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