NAV Navbar

API panelu administracyjnego
v1.74.2.2 pl

JSON XML

polski / english


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

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.

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."
}

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

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"
    },

  ...

}

GEToperations/?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"
        }
      ]
    }
  ]
}

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
      )
    )
  )
)

GETaccounts/

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

GETaccounts/{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
    },
  ]

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] => 
    )

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

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

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;

?>

POSTaccounts/{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ą

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

DELETEaccounts/{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
                }
            }
        }
    ]
}

GETaccounts/{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
   }
}

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

nagłówki odpowiedzi:

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

odpowiedź:

{
  "detail": "ok"
}

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
)

POSTaccounts/{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.

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:

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

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

GEToperations/

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

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

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

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

GEToperations/{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.

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

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

GETpayments/

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

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

POSTpayments/{string: operation_number}/mark_as_complete/

Zasób pozwala oznaczyć daną operację płatności (typ: payment) 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"
}

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

DELETEpayments/{string: operation_number}/mark_as_complete/

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

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

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

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

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

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

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

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

Przypadek 5: zwroty są zablokowane dla tego konta:

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

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

GETreports/

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.

JSON XML