NAV Navbar

Wstęp

Dokumentacja zawiera opis procesów biznesowych oraz metod REST API udostępnianych przez Cinkciarz Pay. API pozwala w łatwy i bezpieczny sposób zautomatyzować proces zakładania płatności i zwrotów przez system Partnera.

API może być wykorzystane do:

Wymagania wstępne

W celu integracji z systemem Cinkciarz Pay, Partner musi posiadać:

Jak zacząć?

Procesy biznesowe realizacji płatności i zwrotu zostały opisane w sekcjach:

W celu utworzenia dyspozycji płatności wystarczy wykonać kilka prostych kroków:

  1. Należy pobrać token dostępowy przy pomocy zasobu POST /connect/token. Token ten należy umieszczać w nagłówku Authorization przy komunikacji z wszystkimi zasobami Cinkciarz Pay API.
  2. Należy dodać własny klucz publiczny w formacie PEM, wykorzystując zasób POST /public_keys.
  3. Własnym kluczem prywatnym należy podpisać zawartość żądania (przykład żądania znajduje się w rozdziale Utworzenie płatności).
  4. Należy wykonać żądanie utworzenia płatności na zasób POST /payments umieszczając w zawartości JWS. Wymagane jest również ustawienie nagłówka żądania zgodnie z informacjami zamieszczonymi w rozdziale Komunikacja z Cinkciarz Pay.
  5. Otrzymaną odpowiedź należy zdekodować oraz zweryfikować zgodnie z informacjami zamieszczonymi w rozdziale Komunikacja z Partnerem.
  6. Tak, utworzoną płatność należy przekazać Klientowi w celu zatwierdzenia. Pozostała część procesu została opisana w rozdziale Proces płatności.

Uwierzytelnienie

W celu skorzystania z Cinkciarz Pay niezbędne jest wykonanie uwierzytelnienia. Każde wywołanie API udostępnianego przez Cinkciarz Pay wymaga przesłania nagłówka Authorization, który zawiera token dostępowy tzw. OAuth 2.0 access token. W celu pobrania tokena należy skorzystać z zasobu POST /connect/token. Uwierzytelnienie realizowane jest z wykorzystaniem HTTP Basic Authentication, gdzie jako nazwę Użytkownika należy podać client_id, a jako hasło client_secret. W zawartości żądania należy podać parametr grant_type ustawiony na client_credentials oraz parametr scope z wartością pay_api.

Pobranie tokena dostępowego

curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -u "<client_id>:<client_secret>" \
     -d "grant_type=client_credentials&scope=pay_api" \
     "<CINKCIARZ_OIDC_HOST>/connect/token"

Odpowiedź:

{
  "access_token": "M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM",
  "expires_in": 900,
  "token_type": "Bearer"
}

Umożliwia pobranie tokena dostępowego do Cinkciarz Pay.

Zasób

POST <CINKCIARZ_OIDC_HOST>/connect/token

Nagłówki

Nazwa Wartość Uwagi
Authorization client_id:client_secret HTTP Basic Authentication.
Content-Type application/x-www-form-urlencoded

Zawartość

Parametry zgodne z trybem client_credentials:

Nazwa Wartość
grant_type client_credentials
scope-Type pay_api

Odpowiedź

Nazwa pola Typ Wymagalność Opis
access_token String TAK Token, który należy podać przy korzystaniu z API udostępnianego przez Cinkciarz Pay.
expires_in String TAK Czas ważności tokena w sekundach.
token_type String TAK Typ tokena.

Płatności

Utworzenie płatności

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d "@data.json" \
     "<CINKCIARZ_PAY_HOST>/payments"

data.json
     {
       "externalPaymentId": "342HHH88LKDJ89876767",
       "pointOfSaleId": "POS4589631365489654",
       "category": "E_COMMERCE",
       "totalAmount": {
         "currency": "PLN",
         "value": "19.99"
       },
       "description": "Payment description."
     }

Nagłówki odpowiedzi:

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

Odpowiedź:

{
  "paymentId": "PAY715037422182587",
  "approveUrl": "https://<CINKCIARZ_PAY_HOST>/approve"
}

Umożliwia utworzenie transakcji płatności.

Zasób

POST <CINKCIARZ_PAY_HOST>/payments

Nagłówki

Nazwa Wartość Uwagi
Authorization
Bearer <access_token>
Musi zawierać token dostępowy typu Bearer. Więcej informacji w Pobranie tokena dostępowego.
Content-Type application/json;charset=UTF-8

Zawartość

Obiekt PaymentData zawierający dane płatności

Nazwa pola Typ Wymagalność Ograniczenia Opis
totalAmount Amount TAK Kwota płatności wraz z walutą.
returnUrl String NIE min. 1 znak max. 256 znaków Adres URL, na który zostanie wykonane przekierowanie po opłaceniu płatności. Jako domyślny wykorzystywany jest adres URL przekazany przez Partnera w ramach konfiguracji punktu płatności.
errorUrl String NIE min. 1 znak max. 256 znaków Adres URL, na który zostanie wykonane przekierowanie po nieudanej próbie opłacenia płatności. Jako domyślny wykorzystywany jest adres URL przekazany przez Partnera w ramach konfiguracji punktu płatności.
pointOfSaleId String TAK 18 znaków Identyfikator punktu płatności.
notificationUrl String NIE min. 1 znak max. 256 znaków Adres URL, na który będą wysyłane powiadomienia o statusie płatności. Jako domyślny wykorzystywany jest adres URL, przekazany przez Partnera w ramach konfiguracji punktu płatności.
order Order NIE Dane zamówienia.
externalPaymentId String TAK min. 1 znak max. 36 znaków Identyfikator płatności po stronie Partnera.
description String TAK min. 1 znak max. 128 znaków Opis płatności.
category String TAK min. 1 znak max. 20 znaków Kategoria płatności.
disablePayLater Boolean NIE Flaga określająca, czy dla płatności ma być włączona funkcjonalność Zapłać później.

Obiekt Amount zawierający kwotę płatności

Nazwa pola Typ Wymagalność Ograniczenia Opis
value Number TAK Kwota. Max. 21 znaków ze wsparciem dla 4 miejsc po separatorze dziesiętnym (jako separator dziesiętny używana jest kropka (.). Liczba miejsc po separatorze dziesiętnym zależy od waluty i została podana w Lista wspieranych walut.
currency String TAK 3 znaki Kod waluty zgodny z ISO 4217. Dozwolone kody walut zdefiniowane zostały w Lista wspieranych walut.

Obiekt Order

Nazwa pola Typ Wymagalność Ograniczenia Opis
customer Customer NIE Dane Klienta.
shippingAddress Address NIE Adres dostawy.
orderUrl String NIE max. 256 znaków Adres URL do zamówienia w systemie Partnera.
additionalInformation String NIE max. 512 znaków Informacje dodatkowe o zamówieniu.
products Array NIE Lista produktów zamówienia typu Product.

Obiekt Customer

Nazwa pola Typ Wymagalność Ograniczenia Opis
firstName String TAK max. 50 znaków Imię Klienta.
lastName String TAK max. 50 znaków Nazwisko Klienta.
companyName String NIE max. 100 znaków Nazwa firmy.
email String TAK max. 320 znaków Adres e-mail Klienta.
phone String NIE max. 26 znaków Numer telefonu Klienta.
address Address NIE Adres Klienta.
additionalInformation String NIE max. 512 znaków Dodatkowe informacje.

Obiekt Address

Nazwa pola Typ Wymagalność Ograniczenia Opis
street String TAK max. 138 znaków Ulica.
postalCode String TAK max. 16 znaków Kod pocztowy.
state String NIE max. 100 znaków Region.
city String TAK max. 100 znaków Miejscowość.
country String TAK dokładnie 2 znaki Dwuliterowy kod kraju zgodny z ISO 3166-1 alpha-2.

Obiekt Product

Nazwa pola Typ Wymagalność Ograniczenia Opis
name String TAK max. 100 znaków Nazwa produktu.
description String NIE max. 512 znaków Opis produktu.
quantity Number TAK zakres od 1-1000000 Liczba jednostek produktu.
amount Amount TAK Cena jednostkowa produktu.

Kategoria płatności

Określa sposób rozliczania z Partnerem.

Wartość Opis
MWF Prowizja stała.
E_COMMERCE Prowizja procentowa od wartości transakcji.

Odpowiedź

Obiekt PaymentInfo zawierający identyfikator utworzonej płatności i adres URL do akceptacji płatności.

Nazwa pola Typ Wymagalność Ograniczenia Opis
paymentId String TAK max. 40 znaków Identyfikator płatności w systemie Cinkciarz Pay.
approveUrl String TAK max. 256 znaków Adres URL, na który Partner przekierowuje Klienta w celu akceptacji utworzonej płatności.

Błędy API

Metoda POST /payments może zwrócić poniższe błędy biznesowe:

Lista płatności

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CINKCIARZ_PAY_HOST>/payments?paymentIds=PAY772237692548117&paymentIds=PAY815576576741391"

Nagłówki odpowiedzi:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

Odpowiedź:

{
    "data":[
        {
            "paymentId":"PAY772237692548117",
            "externalPaymentId":"128/06/2018",
            "status":"NEW"
        },
        {
            "paymentId":"PAY815576576741391",
            "externalPaymentId":"121/06/2018",
            "status":"COMPLETED"
        }
    ],
    "pagination":{
        "first":true,
        "last":true,
        "currentPageNumber":1,
        "currentPageElementsCount":2,
        "pageSize":10,
        "totalPages":1,
        "totalElements":2,
        "pageLimitExceeded":true
    }
}

Pobiera listę płatności o zadanych parametrach wyszukiwania.

Zasób

GET <CINKCIARZ_PAY_HOST>/payments

Nagłówki

Nazwa Wartość Uwagi
Authorization
Bearer <access_token>
Musi zawierać token dostępowy typu Bearer. Więcej informacji w Pobranie tokena dostępowego.

Parametry zapytania

Nazwa pola Typ Wymagalność Opis
paymentIds String NIE Identyfikatory płatności (parametr paymentIds musi być powielany w żądaniu np. /payments?paymentIds=1&paymentIds=2).
externalPaymentId String NIE Identyfikator zewnętrzny płatności.
creationDateFrom String NIE Data i czas utworzenia płatności od, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
creationDateTo String NIE Data i czas utworzenia płatności do, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
bookedDateFrom String NIE Data i czas zaksięgowania płatności od, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
bookedDateTo String NIE Data i czas zaksięgowania płatności do, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
pageNumber Number NIE Numer strony.
pageSize Number NIE Liczba elementów na stronie.
sort String NIE Kryteria sortowania.

Odpowiedź

Obiekt Response zawierający dane płatności

Nazwa pola Typ Wymagalność Ograniczenia Opis
data Array TAK max. 100 elementów Lista z elementami typu Payment.
pagination Pagination TAK max. 36 znaków Metadane zwróconej strony.

Obiekt Payment zawierający szczegóły płatności

Nazwa pola Typ Wymagalność Ograniczenia Opis
paymentId String TAK max. 40 znaków Identyfikator płatności w systemie Cinkciarz Pay.
externalPaymentId String TAK max. 36 znaków Identyfikator płatności w systemie Partnera.
status String TAK max. 14 znaków Status płatności. Wartości zgodne z cyklem życia płatności.

Obiekt Pagination zawierający metadane zwróconej strony z danymi płatności

Nazwa pola Typ Wymagalność Opis
first Boolean TAK Określa, czy zwrócone dane znajdują się na pierwszej stronie.
last Boolean TAK Określa, czy zwrócone dane znajdują się na ostatniej stronie.
currentPageNumber Number TAK Określa numer zwróconej strony.
currentPageElementsCount Number TAK Określa liczbę elementów na zwróconej stronie.
pageSize Number TAK Określa wielkość strony.
totalPages Number TAK Określa liczbę dostępnych stron.
totalElements Number TAK Określa liczbę dostępnych elementów.
pageLimitExceeded Boolean TAK Określa, czy limit stron został osiągnięty.

Błędy API

Metoda GET /payments może zwrócić jedynie błędy techniczne.

Powiadomienia płatności

Obiekt wysyłany na adres notificationUrl podany przez Partnera:

{
    "paymentId":"PAY815576576741391",
    "externalPaymentId":"121/06/2018",
    "code":"COMPLETED"
}

Po wykonaniu akcji przez Klienta na stronie zatwierdzania płatności realizowany jest asynchroniczny proces płatności. W ramach procesu wysyłane są powiadomienia o zmianie statusu płatności na adres notificationUrl podany przez Partnera przy tworzeniu płatności lub przy konfiguracji punktu płatności.

Poniżej znajduje się opis parametrów komunikatu, który jest wysyłany do Partnera.

Obiekt PaymentStatus

Nazwa pola Typ Wymagalność Ograniczenia Opis
paymentId String TAK max. 40 znaków Identyfikator płatności w systemie Cinkciarz Pay.
externalPaymentId String TAK max. 36 znaków Identyfikator płatności w systemie Partnera.
code String TAK max. 14 znaków Status płatności.
description String NIE max. 512 znaków Opis statusu płatności. Może być wysłany dla statusu REJECTED.

Pole code może przyjąć wartości z tabeli poniżej (odpowiadają one statusom płatności):

Nazwa statusu Opis
NEW Płatność została zatwierdzona przez Klienta.
COMPLETED Płatność została zakończona pomyślnie.
CANCELLED Płatność została anulowana przez system.
REJECTED Płatność została odrzucona przez Klienta.

Parametry przekierowania

Zdekodowany parametr data:

{
  "paymentId": "PAY893669703633781",
  "externalPaymentId": "464/46846/45",
  "result": "SUCCESS"
}

Po wykonaniu akcji przez Klienta na stronie zatwierdzania płatności realizowane jest przekierowanie na stronę Partnera. Jeżeli Klient wykonał pomyślnie akcję, to zostanie przekierowany na adres returnUrl podany przy tworzeniu płatności lub domyślnie skonfigurowany w punkcie płatności. W przypadku, gdy wystąpią problemy techniczne, Klient jest przekierowany na adres errorUrl (jest tak samo konfigurowalny, jak adres returnUrl).

Do adresu returnUrl podanego przez Partnera system Cinkciarz Pay dołącza informację o statusie płatności w parametrze data:

https://shop.com/success?data=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk4OTM2Njk3MDM2MzM3ODEiLCJleHRlcm5hbFBheW1lbnRJZCI6IjQ2NC80Njg0Ni80NSIsInJlc3VsdCI6IlNVQ0NFU1MifQ.S83VbMBroVHrAVfXs-tk_Q3BdulpAj3lni0vdegxZ7zCQHhJuIU_DYCFQ3OTG5-EHTJ6zzsmLjjzTw5S8XVy96MXQfHbJKY-jVWEAEB5mRiLgJMn4PssQRLgaGwWbhbFbvD5qqPCFpIz96-FWnkvoxuPaa86Ywfdhd-aPAZ43m3afIAXaKOt9Iy5A0fmsbtZsiwAtrFYMmPoNZcEl02NZ9paIaJ8RXaoU4oTKgMEVjZECQ4smqfnpVg7UD1UIw54F_NaTppx0fAAIZYp5n9lzT9-DwXMe875AbH0ZzRq6-500fSCmJQc3_ym9bM8Xa5gbKSlNQrw2t4pjxJkXbPOGw

Sekcja JWS Payload zawiera dane zapisane w formacie JSON.

Obiekt AdditionalParameters

Nazwa pola Typ Wymagalność Ograniczenia Opis
paymentId String TAK max. 40 znaków Identyfikator płatności w systemie Cinkciarz Pay.
externalPaymentId String TAK max. 36 znaków Identyfikator płatności z systemu Partnera.
result String TAK max. 50 znaków Status płatności. Dopuszczalne wartości opisano poniżej.

Dopuszczalne wartości pola result:

Wartość Opis
SUCCESS Płatność poprawnie zatwierdzona.
SUCCESS_WITH_PAY_LATER Płatność poprawnie zatwierdzona z wykorzystaniem funkcjonalności Zapłać później.
REJECTED Klient zrezygnował z zatwierdzenia płatności.
ERROR Nastąpił problem z zaakceptowaniem płatności (Klient może ponownie ją opłacić, jeżeli posiada link).

Zwroty

Utworzenie zwrotu

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d "@data.json" \
     "<CINKCIARZ_PAY_HOST>/refunds"

data.json
     {
       "paymentId": "PAY715037422182587",
       "reason": "Damaged cover"
       "amount": {
         "currency": "PLN",
         "value": "34.99"
       },
       "externalRefundId": "234/03/2016",
       "notificationUrl": "http://shop.com/notifications"
     }

Nagłówki odpowiedzi:

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

Odpowiedź:

{
  "id": "REF505142910935123"
}

Umożliwia utworzenie transakcji zwrotu do płatności.

Zasób

POST <CINKCIARZ_PAY_HOST>/refunds

Nagłówki

Nazwa Wartość Uwagi
Authorization
Bearer <access_token>
Musi zawierać token dostępowy typu Bearer. Więcej informacji w Pobranie tokena dostępowego.
Content-Type application/json;charset=UTF-8

Zawartość

Obiekt RefundData zawierający dane zwrotu

Nazwa pola Typ Wymagalność Ograniczenia Opis
paymentId String TAK max. 40 znaków Identyfikator płatności z systemu Cinkciarz Pay.
reason String TAK min. 5 znaków max. 512 znaków Powód, dla którego wykonywany jest zwrot.
totalAmount Amount NIE Kwota zwrotu. W przypadku, gdy kwota nie zostanie podana lub gdy jest ona równa kwocie płatności, utworzony zostanie zwrot pełny. Waluta musi być zawsze zgodna z walutą, w której dokonano płatności.
externalRefundId String NIE min. 1 znak max. 36 znaków Identyfikator zwrotu po stronie Partnera.
notificationUrl String NIE min. 1 znak max. 256 znaków Adres URL, na który będą wysyłane powiadomienia o statusie zwrotu. Jako domyślny wykorzystywany jest adres URL, przekazany przez Partnera w ramach umowy o współpracy.

Obiekt Amount zawierający kwotę zwrotu

Nazwa pola Typ Wymagalność Ograniczenia Opis
value Number TAK Kwota. Max. 21 znaków ze wsparciem dla 4 miejsc po separatorze dziesiętnym (jako separator dziesiętny używana jest kropka (.). Liczba miejsc po separatorze dziesiętnym zależy od waluty i została podana w Lista wspieranych walut.
currency String TAK 3 znaki Kod waluty zgodny z ISO 4217. Dozwolone kody walut zdefiniowane zostały w Lista wspieranych walut.

Odpowiedź

Obiekt RefundInfo zawierający identyfikator utworzonego zwrotu

Nazwa pola Typ Wymagalność Ograniczenia Opis
id String TAK max. 40 znaków Identyfikator zwrotu w systemie Cinkciarz Pay.

Błędy API

Metoda POST /refunds może zwrócić poniższe błędy biznesowe:

Lista zwrotów

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CINKCIARZ_PAY_HOST>/refunds?refundIds=REF192843325139567&refundIds=REF942484723821414"

Nagłówki odpowiedzi:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

Odpowiedź:

{
    "data":[
        {
            "refundId":"REF192843325139567",
            "externalRefundId":"128/06/2018",
            "status":"NEW"
        },
        {
            "refundId":"REF942484723821414",
            "externalRefundId":"121/06/2018",
            "status":"COMPLETED"
        }
    ],
    "pagination":{
        "first":true,
        "last":true,
        "currentPageNumber":1,
        "currentPageElementsCount":2,
        "pageSize":10,
        "totalPages":1,
        "totalElements":2,
        "pageLimitExceeded":true
    }
}

Pobiera listę zwrotów o zadanych parametrach wyszukiwania.

Zasób

GET <CINKCIARZ_PAY_HOST>/refunds

Nagłówki

Nazwa Wartość Uwagi
Authorization
Bearer <access_token>
Musi zawierać token dostępowy typu Bearer. Więcej informacji w Pobranie tokena dostępowego.

Parametry zapytania

Nazwa pola Typ Wymagalność Opis
paymentIds String NIE Identyfikatory płatności (parametr paymentIds musi być powielany w żądaniu np. /payments?paymentIds=1&paymentIds=2).
refundIds String NIE Identyfikatory zwrotów (parametr refundIds musi być powielany w żądaniu np. /payments?refundIds=1&refundIds=2).
externalRefundId String NIE Identyfikator zewnętrzny zwrotu.
creationDateFrom String NIE Data i czas utworzenia zwrotu od, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
creationDateTo String NIE Data i czas utworzenia zwrotu do, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
bookedDateFrom String NIE Data i czas zaksięgowania zwrotu od, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
bookedDateTo String NIE Data i czas zaksięgowania zwrotu do, zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.
pageNumber Number NIE Numer strony.
pageSize Number NIE Liczba elementów na stronie.
sort String NIE Kryteria sortowania.

Odpowiedź

Obiekt Response zawierający dane zwrotów

Nazwa pola Typ Wymagalność Ograniczenia Opis
data Array TAK max. 100 elementów Lista z elementami typu Refund.
pagination Pagination TAK max. 36 znaków Metadane zwróconej strony.

Obiekt Refund zawierający szczegóły zwrotu

Nazwa pola Typ Wymagalność Ograniczenia Opis
refundId String TAK max. 40 znaków Identyfikator zwrotu w systemie Cinkciarz Pay.
externalRefundId String NIE max. 36 znaków Identyfikator zwrotu w systemie Partnera.
status String TAK max. 20 znaków Status zwrotu. Wartości zgodne z cyklem życia zwrotu.

Obiekt Pagination zawierający metadane zwróconej strony z danymi zwrotów

Nazwa pola Typ Wymagalność Opis
first Boolean TAK Określa, czy zwrócone dane znajdują się na pierwszej stronie.
last Boolean TAK Określa, czy zwrócone dane znajdują się na ostatniej stronie.
currentPageNumber Number TAK Określa numer zwróconej strony.
currentPageElementsCount Number TAK Określa liczbę elementów na zwróconej stronie.
pageSize Number TAK Określa wielkość strony.
totalPages Number TAK Określa liczbę dostępnych stron.
totalElements Number TAK Określa liczbę dostępnych elementów.
pageLimitExceeded Boolean TAK Określa, czy limit stron został osiągnięty.

Błędy API

Metoda GET /refunds może zwrócić jedynie błędy techniczne.

Powiadomienia zwrotu

Obiekt wysyłany na adres notificationUrl podany przez Partnera:

{
    "refundId":"REF4589632145896",
    "externalRefundId":"121/06/2018",
    "code":"COMPLETED"
}

Po zleceniu zwrotu przez Partnera realizowany jest asynchroniczny proces zwrotu. W ramach procesu wysyłane są powiadomienia o zmianie statusu zwrotu na adres notificationUrl podany przez Partnera przy tworzeniu zwrotu lub przy konfiguracji punktu płatności.

Poniżej znajduje się opis parametrów komunikatu, który jest wysyłany do Partnera.

Obiekt RefundStatus

Nazwa pola Typ Wymagalność Ograniczenia Opis
refundId String TAK max. 40 znaków Identyfikator zwrotu w systemie Cinkciarz Pay.
externalRefundId String NIE max. 36 znaków Identyfikator zwrotu w systemie Partnera.
code String TAK max. 14 znaków Status zwrotu.

Pole code może przyjąć wartości z tabeli poniżej (odpowiadają one statusom zwrotu):

Nazwa statusu Opis
NEW Zwrot został utworzony.
PROCESSING Zwrot jest przetwarzany.
COMPLETED Zwrot został zakończony pomyślnie.

Błędy API - techniczne

Opis błędów zwracanych przez API Cinkciarz PAY dla wszystkich udostępnianych zasobów.

400 Bad Request

Nagłówki odpowiedzi:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
  "title" : "Bad Request",
  "status": 400,
  "detail": "Unexpected character ('f' (code 102)): was expecting comma to separate Object entries"
}

Zwracany, gdy żądanie ma nieprawidłową strukturę.

403 Forbidden

Nagłówki odpowiedzi:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
  "title" : "Forbidden",
  "status": 403
}

Zwracany, gdy Klient nie posiada dostępu do żądanego zasobu.

405 Method Not Allowed

Nagłówki odpowiedzi:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
  "title" : "Method Not Allowed",
  "status": 405,
  "detail": "Request method 'PUT' not supported"
}

Zwracany, gdy wywoływana metoda na zasobie jest inna niż zdefiniowana.

409 Conflict

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "title" : "Conflict",
    "status": 409,
    "detail": "Currency from paymentData.totalAmount is different than the currency from products"
}

Zwracany, gdy wystąpią błędy walidacji biznesowej.

415 Unsupported Media Type

Nagłówki odpowiedzi:

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "title" : "Unsupported Media Type",
    "status": 415,
    "detail": "Content type 'application/x-www-form-urlencoded' not supported"
}

Wysłana zawartość żądania jest niewspieranego typu.

500 Internal Server Error

Nagłówki odpowiedzi:

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "title" : "Internal Server Error",
    "status": 500
}

Wystąpił nieoczekiwany błąd.

503 Service Unavailable

Nagłówki odpowiedzi:

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "title" : "Service Unavailable",
    "status": 503
}

Serwis nie jest dostępny.

Błędy API - biznesowe

Opis błędów zwracanych przez API Cinkciarz PAY, których typ jest zdefiniowany przez klucz type.

invalid-pem

Nagłówki odpowiedzi:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
  "type": "invalid-pem",
  "status": 400,
  "title": "Can not read public key from PEM",
  "detail": "Can not read public key from PEM",
}

Zwracany, gdy wysyłany klucz publiczny jest nieprawidłowy.

invalid-public-key

Nagłówki odpowiedzi:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
  "type": "invalid-public-key",
  "status": 400,
  "title": "Invalid public key",
  "detail": "Invalid public key",
}

Zwracany, gdy podczas dodawania nowego klucza publicznego, klucz będzie niepoprawny.

sample-text-signature-not-match

Nagłówki odpowiedzi:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
  "type": "sample-text-signature-not-match",
  "status": 400,
  "title": "Sample text signature not match",
  "detail": "Sample decoded text must have signed with SHA-256 signature",
}

Zwracany, gdy podczas dodawania nowego klucza publicznego, przykładowa wiadomość w polu encodedText została podpisana z wykorzystaniem innej sygnatury niż SHA-256.

validation-error

Nagłówki odpowiedzi:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
  "type": "validation-error",
  "status": 400,
  "title": "Request parameters are not valid",
  "detail": "Property 'category1' with value 'E_COMMERCE' is unknown for object 'PaymentData'",
  "validation-errors": [
    {
      "message-key": "unknown-property",
      "context-key": "category1",
      "message": "Unsupported 'category1' property"
    }
  ]
}

Zwracany, gdy podane parametry żądania są nieprawidłowe.

point-of-sale-not-found

Nagłówki odpowiedzi:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type"  : "point-of-sale-not-found",
    "title" : "Point of sale not found",
    "status": 404,
    "detail": "Point of sale with identifier POS458963214589658 not found"
}

Identyfikator punktu płatności jest niepoprawny.

store-not-found

Nagłówki odpowiedzi:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type"  : "store-not-found",
    "title" : "Store not found",
    "status": 404,
    "detail": "Store with identifier STR458963125698745 not found"
}

Identyfikator sklepu powiązanego z punktem płatności jest niepoprawny.

contract-category-not-supported

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "contract-category-not-supported",
    "title" : "Category not supported",
    "status": 409,
    "detail": "Partner contract not support E_COMMERCE category"
}

Kategoria podana w dyspozycji płatności jest inna niż zdefiniowana w umowie.

payment-money-below-limit

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type"  : "payment-money-below-limit",
    "title" : "Payment money below limit",
    "status": 409,
    "detail": "Payment money 0.01 EUR is below 1 EUR limit for EUR currency"
}

Podana kwota płatności znajduje się poniżej zdefiniowanej wartości dla danej waluty.

payment-not-completed

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "payment-not-completed",
    "title" : "Payment not completed",
    "status" : 409,
    "detail" : "Payment is not completed"
}

Płatność, na którą jest realizowany zwrot nie jest zakończona.

point-of-sale-currency-not-supported

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type"  : "point-of-sale-currency-not-supported",
    "title" : "Currency not supported",
    "status": 409,
    "detail": "Point of sale with identifier POS45896321569859 not support JPY currency"
}

Waluta podana w dyspozycji płatności jest inna niż zdefiniowana dla punktu płatności.

point-of-sale-forbidden-error-url

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "point-of-sale-forbidden-error-url",
    "title" : "Forbidden error url",
    "status": 409,
    "detail": "Error url is not allowed in point of sale with identifier POS444785125632569"
}

Podany url wykorzystywany przy przekierowaniu Klienta nie został zdefiniowany w punkcie płatności.

point-of-sale-forbidden-notification-url

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "point-of-sale-forbidden-notification-url",
    "title" : "Forbidden notification url",
    "status": 409,
    "detail": "Notification url is not allowed in point of sale with identifier POS458963215697589"
}

Podany url dla otrzymywania powiadomień nie został zdefiniowany w punkcie płatności.

point-of-sale-forbidden-return-url

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "point-of-sale-forbidden-return-url",
    "title" : "Forbidden return url",
    "status": 409,
    "detail": "Return url is not allowed in point of sale with identifier POS444785125632569"
}

Podany url wykorzystywany przy przekierowaniu Klienta nie został zdefiniowany w punkcie płatności.

point-of-sale-not-active

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type"  : "point-of-sale-not-active",
    "title" : "Point of sale not active",
    "status": 409,
    "detail": "Point of sale with identifier POS458963214589658 is not active"
}

Punkt płatności jest nieaktywny.

refund-amount-too-large

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "refund-amount-too-large",
    "title" : "Refund amount too large",
    "status" : 409,
    "detail" : "Refund amount (or sum of the all partial refunds amount) is higher than payment amount"
}

Kwota zwrotu przekracza kwotę płatności. W przypadku zwrotu częściowego suma wszystkich kwot zwrotów częściowych przekracza kwotę płatności.

refund-incorrect-currency-code

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "refund-incorrect-currency-code",
    "title" : "Incorrect refund currency code",
    "status" : 409,
    "detail" : "Refund currency code not match with payment currency code"
}

Waluta zwrotu jest inna niż waluta, którą dokonano płatności.

sample-text-verification-failed

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "sample-text-verification-failed",
    "title" : "Sample text verification failed",
    "status": 409,
    "detail": "Signed text from encodedText not equals to unsigned text from decodedText"
}

Zwracany, gdy podpisana wiadomość w polu encodedText nie jest zgodna z wartością podaną w decodedText.

public-key-has-wrong-length

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type" : "public-key-has-wrong-length",
    "title" : "Public key has wrong bytes length",
    "status": 409,
    "detail": "Client public key must have a minimum of 2 048 bytes"
}

Zwracany, gdy dodawany klucz publiczny jest mniejszy niż 2048 bajtów.

transaction-limit-exceed

Nagłówki odpowiedzi:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json;charset=UTF-8

Odpowiedź:

{
    "type":"transaction-limit-exceed",
    "title":"Transaction limit exceed",
    "status":409,
    "detail":"Transaction limit 10 PLN exceed",
    "money":{
        "currency":"PLN",
        "value":"10"
    }
}

Dzienny limit transakcji został przekroczony przez Partnera.

Procesy biznesowe

Proces płatności

Poniżej przedstawiony został proces płatności. Przedstawiony scenariusz zawiera tylko pozytywny przypadek, który ma na celu przedstawić logikę działania całego procesu.

alt text

Warunki wstępne

Klient utworzył, w sklepie internetowym Merchanta koszyk z listą produktów do zakupu.

Scenariusz

  1. Klient na stronie sklepu wybrał metodę płatności udostępnianą przez Merchanta, a następnie kliknął przycisk „Płacę” (Krok 1.).
  2. Serwer Merchanta wysyła komunikat PaymentData do serwera Cinkciarz Pay (Krok 2.).
  3. Serwer Cinkciarz Pay sprawdza poprawność otrzymanego komunikatu i tworzy dyspozycję płatności (Krok 3.).
  4. Serwer Cinkciarz Pay wysyła odpowiedź PaymentInfo do serwera Merchanta (Krok 4.).
  5. Serwer Merchanta zapisuje status transakcji potwierdzający przyjęcie dyspozycji w Cinkciarz Pay (Krok 5.) i przekierowuje Klienta na adres approveUrl otrzymany w odpowiedzi PaymentInfo (Krok 6.).
  6. Klient loguje się do serwisu Cinkciarz Pay (Krok 7.), wybiera konto walutowe, z którego będzie realizowana płatność i klika przycisk „Zapłać” (Krok 8.).
  7. Serwer Cinkciarz Pay przyjmuje do przetwarzania zaakceptowaną przez Klienta płatności (Krok 9.).
  8. Serwer Cinkciarz Pay wykonuje przekierowanie do serwera Merchanta - na adres returnUrl podany przy zakładaniu dyspozycji płatności (zwykle na stronę z podziękowaniem za dokonany zakup) (Krok 10.).

Równolegle do kroków 11. i 12. realizowany jest proces przetwarzania płatności:

  1. Serwer Cinkciarz Pay po zakończeniu przetwarzania płatności wysyła do serwera Merchanta na adres notificationUrl komunikat PaymentStatus z informacją o statusie transakcji (Krok 12.).
  2. Serwer Merchanta zapisuje status zakończonej transakcji (Krok 13.) i wysyła kod odpowiedzi HTTP 200 OK, który oznacza poprawne otrzymanie informacji o statusie transakcji (Krok 14.).
  3. Serwer Merchanta akceptuje wykonaną transakcję płatności (Krok 15.).

Cykl życia płatności

alt text

Proces zwrotu

Zwrot środków na portfel Klienta może być wykonany w dwóch trybach:

Zwrot realizowany jest zawsze w walucie, w której dokonana była płatność. Dla pełnego zwrotu podanie kwoty i waluty nie jest wymagane, natomiast dla zwrotu częściowego waluta musi być zgodna z walutą, w której dokonana została płatność.

W przypadku zwrotu częściowego, suma wszystkich kwot poszczególnych zwrotów częściowych nie może przekroczyć całkowitej kwoty płatności, dla której wykonywany jest zwrot.

Zwrot na kwotę równą kwocie płatności traktowany jest jako zwrot pełny. Jeśli istnieje zwrot częściowy dla płatności, to nie jest możliwe wykonanie zwrotu całkowitego.

Przedstawiony scenariusz zawiera tylko pozytywny przypadek dla zwrotu pełnego, który ma przedstawić logikę działania całego procesu.

alt text

Warunki wstępne

W systemie Cinkciarz Pay istnieje zakończona płatność, dla której ma zostać wykonany zwrot.

Scenariusz

  1. Serwer Partnera wysyła komunikat RefundData do serwera Cinkciarz Pay (Krok 1.).
  2. Serwer Cinkciarz Pay tworzy zwrot (Krok 2.).
  3. Serwer Cinkciarz Pay wysyła odpowiedź RefundInfo do Partnera (Krok 3.).
  4. Serwer Partnera zapisuje informację o utworzeniu zwrotu (Krok 4.).

Równolegle do kroku 4. realizowany jest proces przetwarzania zwrotu:

  1. Serwer Cinkciarz Pay po zakończeniu przetwarzania zwrotu wysyła do serwera Partnera na adres notificationUrl komunikat RefundStatus z informacją o statusie zwrotu (Krok 5.).
  2. Serwer Partnera zapisuje informację o wykonaniu zwrotu (Krok 6.) i i wysyła kod odpowiedzi HTTP 200 OK, który oznacza poprawne otrzymanie informacji o statusie zwrotu (krok 7.).

Cykl życia zwrotu

alt text

Status CANCELED może wystąpić w sytuacjach, gdy portfel Partnera nie zawierał wystarczających środków, aby zrealizować zwrot.

Bezpieczeństwo

System Cinkciarz Pay stosuje poniższe elementy, które zapewniają bezpieczeństwo komunikacji z systemem Partnera:

Autentyczność komunikatu

Specyfikacja JSON Web Signature definiuje, w jaki sposób mogą być podpisane przesyłane komunikaty. JWS jest kodowany przy użyciu base64url i składa się z trzech części oddzielonych od siebie kropkami (.). Ogólna struktura JWS wygląda następująco:

base64url(utf8(header)).base64url(payload).base64url(signature)

Przykładowy minimalny nagłówek JWS akceptowany przez Cinkciarz Pay:

{
    "alg": "RS256",
    "kid": "iQn7M-Eyzw5sde5GwaOu51Xzl8WFXJzNW3pmCBENhhk"
}

Header

Pierwsza część to nagłówek (header), który zawiera m.in. informację o zastosowanym do wyliczenia sygnatury algorytmie - parametr "alg". Możliwe wartości, jakie może przyjmować parametr "alg" zostały podane w tabeli poniżej:

Identyfikator Nazwa algorytmu
RS256 SHA256withRSA
RS384 SHA384withRSA
RS512 SHA512withRSA

Minimalny nagłówek JWS oprócz parametru "alg" musi zawierać także parametr "kid" identyfikujący klucz publiczny, który służy do weryfikacji sygnatury.

Payload

Druga część JWS to tzw. payload, który zawiera przesyłany komunikat. Specyfikacja JWS nie definiuje typu przesyłanego komunikatu (może to być np. XML lub String), jednak Cinkciarz Pay wymaga by komunikat przesyłany był w formacie JSON (kodowanie UTF-8).

Signature

Trzecia część JWS to cyfrowy podpis (signature), który wyliczany jest z zastosowaniem algorytmu podanego w nagłówku JWS dla połączonych ze sobą zakodowanego nagłówka i zakodowanego komunikatu, oddzielonych znakiem kropki (.).

Komunikacja z Cinkciarz Pay

JWS Header

{
  "alg": "RS256",
  "typ": "JWT",
  "cty": "application/json",
  "kid": "DFDOlB7DU6-0hRYA5Uu4BbTG-qrecsKtBHSy3TjiIs8"
}

JWS Payload

{
  "description": "Payment description",
  "externalPaymentId": "342HHH88LKDJ89876767",
  "category": "E_COMMERCE",
  "pointOfSaleId": "POS45896321596547859",
  "totalAmount": {
    "currency": "USD",
    "value": 19.99
  }
}

Przykładowe żądanie utworzenia płatności:

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/jose+json" \
     -d "@payload.jws" \
     "<CINKCIARZ_PAY_HOST>/payments"

payload.jws
     eyJraWQiOiJERkRPbEI3RFU2LTBoUllBNVV1NEJiVEctcXJlY3NLdEJIU3kzVGppSXM4IiwiY3R5IjoiYXBwbGljYXRpb24vanNvbiIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.ew0KICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbiIsDQogICJleHRlcm5hbFBheW1lbnRJZCI6ICIzNDJISEg4OExLREo4OTg3Njc2NyIsDQogICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwNCiAgInBvaW50T2ZTYWxlSWQiOiAiUE9TNDU4OTYzMjE1OTY1NDc4NTkiLA0KICAidG90YWxBbW91bnQiOiB7DQogICAgImN1cnJlbmN5IjogIlVTRCIsDQogICAgInZhbHVlIjogMTkuOTkNCiAgfQ0KfQ.J2uDZEZL_hlgLAscv3EMX8lKCPBOf1X3UoUEDGhBF0cKFSAvHaDAAtnyzacL53RWsaHmAfDTRHqqFuF6g6wBRStbWukC1pOqXNEYHTXgfHJ01Sh7JZr7IRuX92ol-OgiP7DK01wDnlZ80_wGnJUpWGQjiQEoUzJhOcFyZ44_jSKh7dwU7SWh9wj5FWmC1A8RlBXLpMf6QWCKlA1njw4r7RXUmbLLbdiA71Oiy1LN_Ezf8srYP5y_QhhtoyXxkLEe75YP5ky6d0UObrKpUVbhvj7lwnqMzZVBfD1aIL5F2s8gUg8nQeCUWPUYIRvDNQkmAFTSbqjD2sCG1ysm8JDspA

Nagłówki odpowiedzi:

HTTP/1.1 201 Created
Content-Type: application/jose+json

Odpowiedź:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb247Y2hhcnNldD1VVEYtOCIsImtpZCI6InpDNGo0QWNoZHp3S1hTX01xc2g0QWZ3VnlTdUdzRmdnT18yeHY1dHVzemsifQ.eyJwYXltZW50SWQiOiAiUEFZNzE1MDM3NDIyMTgyNTg3IiwiYXBwcm92ZVVybCI6ICJodHRwczovLzxDSU5LQ0lBUlpfUEFZX0hPU1Q-L2FwcHJvdmUifQ.T8YBr9hhEjIEe2JtFEuVo0GAssd2-9ZL7IEGjMNoamqD6c9Ha1W6Nunlrs-CpYHUabejhcI6Z3EKzuA8Ra9YyKki_BOoK_oPAnKSJMaP6DgYeJ0cxqawqdMYkT0Ku3TpUwte-hwIoWVNFKqfjBncwNfhAXPyx4Ti6eqAQENpL8VmfvsrcmLn96BqbxYo1Hp07K_AmVulJs701a_s0BdSysLmAyhmLcQfVwSWCpTgMc7NXbe1R95T6xRYCsif2FvVZke4cM8f9zDZZI5-V7tgUhx8v3BVUEtanjPsPdDcTUs5ZLYl6EH8yCtWECGxbxxJbV2WDGJTPn6mbNRBtsjsNQ

Wszystkie komunikaty wysyłane z systemu Partnera do systemu Cinkciarz Pay muszą być przesyłane w formacie JWS. Jedynie w przypadku dodawania klucza publicznego nie jest wymagane podpisywanie komunikatu.

Poniżej przedstawiony został przykładowy JWS (Compact Serialized), jaki może być przesłany do Cinkciarz Pay:

eyJraWQiOiJERkRPbEI3RFU2LTBoUllBNVV1NEJiVEctcXJlY3NLdEJIU3kzVGppSXM4IiwiY3R5IjoiYXBwbGljYXRpb24vanNvbiIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.ew0KICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbiIsDQogICJleHRlcm5hbFBheW1lbnRJZCI6ICIzNDJISEg4OExLREo4OTg3Njc2NyIsDQogICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwNCiAgInBvaW50T2ZTYWxlSWQiOiAiUE9TNDU4OTYzMjE1OTY1NDc4NTkiLA0KICAidG90YWxBbW91bnQiOiB7DQogICAgImN1cnJlbmN5IjogIlVTRCIsDQogICAgInZhbHVlIjogMTkuOTkNCiAgfQ0KfQ.J2uDZEZL_hlgLAscv3EMX8lKCPBOf1X3UoUEDGhBF0cKFSAvHaDAAtnyzacL53RWsaHmAfDTRHqqFuF6g6wBRStbWukC1pOqXNEYHTXgfHJ01Sh7JZr7IRuX92ol-OgiP7DK01wDnlZ80_wGnJUpWGQjiQEoUzJhOcFyZ44_jSKh7dwU7SWh9wj5FWmC1A8RlBXLpMf6QWCKlA1njw4r7RXUmbLLbdiA71Oiy1LN_Ezf8srYP5y_QhhtoyXxkLEe75YP5ky6d0UObrKpUVbhvj7lwnqMzZVBfD1aIL5F2s8gUg8nQeCUWPUYIRvDNQkmAFTSbqjD2sCG1ysm8JDspA

Po zdekodowaniu JWS otrzymuje się JWS Header oraz JWS Payload zawierający minimalny komunikat PaymentData. Do podpisu użyto algorytmu asymetrycznego RSASSA-PKCS1-V1_5 with SHA-256 (RS256). W celu weryfikacji sygnatury należy wykorzystać przykładowy klucz publiczny:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtbQuQMzUo5jTMLdq7Y0p
QuZbOwiAJ7Ty3oB3aww78wAEY8Irb+Ns9fkwRadUaKfkT9OMuj6EWos6QvxFXRAe
kxqMVoTnQaaZsAEA471ZBdt3sZxTxDQhf96I7JOTr1BA1J2fgQN1zRB8hnMotEF1
iaGTBtI1yN1RypSsL/mpdgF05E1Urh2OqMSDbv9Arl1cBqt79jJzAXi0uj2CyVp8
7ID0NruLSwD2zFRxW5/NAee1w4lAbuk7EBMCPLkrikW7xsKQyGIubMO4cpeCWZwU
FTnWOHgpft+HdQqnkaTCpWLIEFOG7DRh7h3kU6oHXIoH7KkhMBRNdw104ZNk1rQw
WwIDAQAB
-----END PUBLIC KEY-----

Do weryfikacji odpowiedzi otrzymanej z Cinkciarz Pay należy użyć klucza publicznego udostępnianego przez API GET /jwks.

Komunikacja z Partnerem

Przykładowa odpowiedź API:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb247Y2hhcnNldD1VVEYtOCIsImtpZCI6InpDNGo0QWNoZHp3S1hTX01xc2g0QWZ3VnlTdUdzRmdnT18yeHY1dHVzemsifQ.eyJwYXltZW50SWQiOiAiUEFZNzE1MDM3NDIyMTgyNTg3IiwiYXBwcm92ZVVybCI6ICJodHRwczovLzxDSU5LQ0lBUlpfUEFZX0hPU1Q-L2FwcHJvdmUifQ.T8YBr9hhEjIEe2JtFEuVo0GAssd2-9ZL7IEGjMNoamqD6c9Ha1W6Nunlrs-CpYHUabejhcI6Z3EKzuA8Ra9YyKki_BOoK_oPAnKSJMaP6DgYeJ0cxqawqdMYkT0Ku3TpUwte-hwIoWVNFKqfjBncwNfhAXPyx4Ti6eqAQENpL8VmfvsrcmLn96BqbxYo1Hp07K_AmVulJs701a_s0BdSysLmAyhmLcQfVwSWCpTgMc7NXbe1R95T6xRYCsif2FvVZke4cM8f9zDZZI5-V7tgUhx8v3BVUEtanjPsPdDcTUs5ZLYl6EH8yCtWECGxbxxJbV2WDGJTPn6mbNRBtsjsNQ

Nagłówki odpowiedzi:

HTTP/1.1 201 Created
Content-Type: application/jose+json

JWS Header

{
  "alg": "RS256",
  "typ": "JWT",
  "cty": "application/json;charset=UTF-8",
  "kid": "zC4j4AchdzwKXS_Mqsh4AfwVySuGsFggO_2xv5tuszk"
}

JWS Payload

{
  "paymentId": "PAY715037422182587",
  "approveUrl": "https://<CINKCIARZ_PAY_HOST>/approve"
}

Wszystkie komunikaty oraz odpowiedzi wysyłane z systemu Cinkciarz Pay do systemu Partnera są wysyłane w formacie JWS. Przykłady zawarte w dokumentacji dla uproszczenia są podawane w formie zdekodowanej. W celu weryfikacji otrzymanego komunikatu należy pobrać klucz publiczny Cinkciarz Pay i przy jego pomocy zweryfikować autentyczność otrzymanych danych.

Autentyczność parametrów URL

Zdekodowany parametr data (sekcja JWS Payload):

{
  "paymentId": "PAY893669703633781",
  "externalPaymentId": "464/46846/45",
  "result": "SUCCESS"
}

System Cinkciarz Pay po przekierowaniu Klienta na stronę Partnera zamieszcza w ramach skonfigurowanego adresu URL dodatkowe parametry określające status realizacji płatności przez Klienta. W celu zapewnienia autentyczności, parametry te są podpisywane.

Poniżej zaprezentowany jest przykładowy adres URL:

https://shop.com/success?data=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk4OTM2Njk3MDM2MzM3ODEiLCJleHRlcm5hbFBheW1lbnRJZCI6IjQ2NC80Njg0Ni80NSIsInJlc3VsdCI6IlNVQ0NFU1MifQ.S83VbMBroVHrAVfXs-tk_Q3BdulpAj3lni0vdegxZ7zCQHhJuIU_DYCFQ3OTG5-EHTJ6zzsmLjjzTw5S8XVy96MXQfHbJKY-jVWEAEB5mRiLgJMn4PssQRLgaGwWbhbFbvD5qqPCFpIz96-FWnkvoxuPaa86Ywfdhd-aPAZ43m3afIAXaKOt9Iy5A0fmsbtZsiwAtrFYMmPoNZcEl02NZ9paIaJ8RXaoU4oTKgMEVjZECQ4smqfnpVg7UD1UIw54F_NaTppx0fAAIZYp5n9lzT9-DwXMe875AbH0ZzRq6-500fSCmJQc3_ym9bM8Xa5gbKSlNQrw2t4pjxJkXbPOGw

Dodanie klucza publicznego

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d "@public-key.json" \
     "<CINKCIARZ_PAY_HOST>/public_keys"

public-key.json { "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnIo4OMp7I5ugVgGQquUL\nFFdC0m1sL+1e7M1zX8lobKPJpQwApDKaEFTBWjrK5aXvzAsxqKzKzG3yUCSGqa/f\nhuzdzs3kBlvIFCPwk5dM5uc5v2+2W0SF0/8lF3NBUjK2jz8s3Nyb3cCWCfysRF+1\nKhF/4ushqX4spCraIU2GkavZ6ETn/Oyfu1fJnZSuH16fwj2OwGsFnTUHam5yrihn\nhtxIkp4eUbhBOkjMMwb4XLygD1dlcg61Pbe60dmuwV+ZWQzfoi4QzlZd9kpePEva\nbPar+AUItKilx5XvNm86PLGBbcsGIMhtew019UP0MrgF1S2/99ZsF2V76haipaXS\nkQIDAQAB\n-----END PUBLIC KEY-----", "sampleData": { "decodedText": "test", "encodedText": "HHjI8WE+jlc/K7vgoYCAqe0NlIGpEHkIcx7iUze2T2hOMOpVogtAUq2XJLDWIkJ6kOIFAfYWrCfXullMIfRKix7ch9CHnBTGg0e0DHOZEw42C/50YhMzg1GpfLSJutQpOMU/KEjSXdvuJiKwngHWqpvJTxHTYJkPkLHzUzANz3iB1XB8KBepnHBW2WQ8SUBb8qw27AD1Gc6bySIgx8OoFSpZAsyDQanPtz/TkYBpakakRdw0ISc/cAM8KKTjOxTbHOwWcNDlwAmoBNS+eUGeH/yNBwjPnK1TS0yhmdgrerIrJ+yZm1VI5EHPbzWMBWx142LE/M9d9AEozAMYCUtOlg==" } }

Nagłówki odpowiedzi:

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

Odpowiedź:

{
  "kid": "lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ"
}

W celu umożliwienia bezpiecznej komunikacji pomiędzy Cinkciarz Pay i systemem Partnera istotne jest dostarczenie przez Partnera klucza publicznego, którym będą weryfikowane komunikaty wysyłane przez system. Klucz publiczny należy dostarczyć w formacie PEM wywołując zasób POST /public_keys.

Zasób

POST <CINKCIARZ_PAY_HOST>/public_keys

Nagłówki

Nazwa Wartość Uwagi
Authorization
Bearer <access_token>
Musi zawierać token dostępowy typu Bearer. Więcej informacji w Pobranie tokena dostępowego.
Content-Type application/json;charset=UTF-8

Zawartość

Obiekt PublicKey zawierający dane klucza publicznego

Nazwa pola Typ Wymagalność Opis
pem String TAK Klucz publiczny Partnera.
sampleData SampleData NIE Obiekt zawierający przykładowe teksty do weryfikacji klucza publicznego.

Obiekt SampleData zawierający przykładowe teksty do weryfikacji klucza publicznego

Nazwa pola Typ Wymagalność Opis
decodedText String NIE Przykładowy tekst przesyłany w celu weryfikacji poprawności klucza publicznego.
encodedText String NIE Przykładowy tekst z pola decodedText podpisany przez klucz prywatny z sygnaturą SHA-256.

Odpowiedź

Nazwa pola Typ Wymagalność Opis
kid String TAK Identyfikator klucza publicznego Partnera.

Błędy API

Metoda POST /public_keys może zwrócić poniższe błędy biznesowe:

Pobranie kluczy publicznych

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CINKCIARZ_PAY_HOST>/public_keys"

Nagłówki odpowiedzi:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

Odpowiedź:

{
 "publicKeys": [
   {
     "kid": "chi09N6Bog_0IvtrahDhZRGF7kiHTAhQaIm4x_wdpQU",
     "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoPYw28jrN71VoWHfSkTR\nb4v8OdYMjwZRs2dg5vPZjv0xryNAqHpHYP5+SCpEz6YRFGzuCWhqkNgSKmZgLBxv\nBVJt8YqZOtbnB4as/4TI0dy73YUmw00LYXLTcrS6al6OFtC4SehUREgoVG9V8Hlf\nx9T0bnNOW5R0z3LvkC+Y8e1Gm+xtX+K5uX00md5TI1jk5GqoE9D7cuv5mBX50Igi\nzMqbZYttu/gdA3TWD6JnceMU2WPKJDLowGN4RnUtQJQiApfRQZDPblB+9AKJkiTy\n8N4g9hAVmKbwC3cehO1vMB7ujOlJrNAXjh1rO7B3OJQ0JXcpb2UhrPZ/DIuRdLvX\n6QIDAQAB\n-----END PUBLIC KEY-----"
   }
 ]
}

Dodane klucze publiczne można pobrać wywołując zasób GET /public_keys.

Zasób

GET <CINKCIARZ_PAY_HOST>/public_keys

Nagłówki

Nazwa Wartość Uwagi
Authorization
Bearer <access_token>
Musi zawierać token dostępowy typu Bearer. Więcej informacji w Pobranie tokena dostępowego.

Odpowiedź

Obiekt PublicKeys zawierający listę dodanych kluczy publicznych

Nazwa pola Typ Wymagalność Opis
publicKeys Array NIE Lista obiektów typu PublicKey.

Obiekt PublicKey zawierający informację o kluczu publicznym

Nazwa pola Typ Wymagalność Opis
kid String TAK Identyfikator klucza publicznego.
pem String TAK Klucz publiczny.
expiredDate String NIE Data i czas wygaśnięcia klucza zgodna z ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.

Błędy API

Metoda GET /public_keys może zwrócić jedynie błędy techniczne.

Pobranie klucza Cinkciarz Pay

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CINKCIARZ_PAY_HOST>/jwks"

Nagłówki odpowiedzi:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

Odpowiedź:

{
 "keys": [
   {
     "kty": "RSA",
     "kid": "zC4j4AchdzwKXS_Mqsh4AfwVySuGsFggO_2xv5tuszk",
     "use": "sig",
     "n": "hFava6Gd2uyA9XHmD7IIxiKD-S2vBcJ0QtgjodtvDeI4y3r5Ab_s_XMvTvbdSkCf0nmK84UwWwayQwnTboafvktCRndfnvSXWCVClgiVWJmnNibPhtsMI_uelmc99OjtPM93UZ6_yiohi1mKpC_w8MygxHX7R3rFMxssO5h-qXPfjWYWAiC0-B_Vf592E52N-dOF_yUi5hAP14gFbPv_LSWn2dSWkg2i6n5lTL6QzNQueBw3Q04odYXrbALPm1M0ucwgDewWW8LTzRAsqKwIeY9iTblq9ywxnExbq5qORgtNVk3zunqEYRKQfJIINFZgJSmqxxAfvnzlJyvuih97zQ",
     "e": "AQAB"
   }
 ]
}

W celu weryfikacji komunikatów otrzymywanych z systemu Cinkciarz Pay wymagane jest posiadanie klucza publicznego systemu Cinkciarz Pay. W celu pozyskania klucza należy wykorzystać zasób GET /jwks.

Zasób

GET <CINKCIARZ_PAY_HOST>/jwks

Nagłówki

Nazwa Wartość Uwagi
Authorization
Bearer <access_token>
Musi zawierać token dostępowy typu Bearer. Więcej informacji w Pobranie tokena dostępowego.

Odpowiedź

Obiekt PublicKeys zawierający listę kluczy publicznych systemu Cinkciarz Pay

Nazwa pola Typ Wymagalność Opis
keys Array TAK Lista obiektów typu PublicKey.

Obiekt PublicKey zawierający informację o kluczu publicznym Cinkciarz Pay

Nazwa pola Typ Wymagalność Opis
kty String TAK Typ klucza.
kid String TAK Identyfikator klucza publicznego.
use String TAK Sposób użycia klucza.
n String TAK Moduł standardowego PEM.
e String TAK Wykładnik standardowego PEM.

Błędy API

Metoda GET /jwks może zwrócić jedynie błędy techniczne.

Lista wspieranych walut

Waluta Kod waluty Liczba cyfr po separatorze dziesiętnym Minimalna liczba jednostek waluty dla transakcji
United Arab Emirates Dirham AED 2 1
Australia Dollar AUD 2 1
Bulgaria Lev BGN 2 1
Canada Dollar CAD 2 1
Switzerland Franc CHF 2 1
China Yuan Renminbi CNY 2 1
Czech Republic Koruna CZK 2 10
Denmark Krone DKK 2 10
Euro EUR 2 1
United Kingdom Pound GBP 2 1
Hong Kong Dollar HKD 2 1
Croatia Kuna HRK 2 1
Hungary Forint HUF 0 100
Israeli New Sheqel ILS 2 1
Japan Yen JPY 0 100
Mexico Peso MXN 2 1
Norway Krone NOK 2 10
New Zealand Dollar NZD 2 1
Poland Zloty PLN 2 1
Romania New Leu RON 2 1
Russia Ruble RUB 2 10
Sweden Krona SEK 2 10
Singapore Dollar SGD 2 1
Turkey Lira TRY 2 1
United States Dollar USD 2 1
South Africa Rand ZAR 2 1

Algorytm wysyłania powiadomień

Nieudana próba wysłania: Kolejna próba wysłania za:
1 10 sekund
2 20 sekund
3 30 sekund
4 - 300 120 sekund
> 300 Kolejne próby nie będą podejmowane