NAV Navbar
cURL unsigned cURL signed

Introduction

This documentation includes a description of business processes and REST API methods made available via Conotoxia Pay. The API enables simple and safe automation of the process of making payments and refunds by the Partner's system.

API can be used for:

The API applies to the following payment processing models:

The business processes for executing payments and refunds are described in the section:

How to start?

In the first stage, you must register the Partner's account and create the store structures. The steps are described below which are necessary to start using Conotoxia Pay API.

Store creation

  1. You should set up a company account at conotoxia.com and complete your company profile.
  2. In the next step you should move to the Merchant's panel and add your store and point of sale. Note that point of sale URL addresses should be configured correctly:
    • URL address for payment creation notification - notifications about the payment status will be sent to this address. They are described in more detail in the payment notifications chapter.
    • URL address for refund creation notification - notifications about the refund status will be sent to this address. They are described in more detail in the refund notifications chapter.
    • URL address for successfully executed payment - the client will be redirected to this address after successful payment approval at Conotoxia Pay. Redirection is described in more detail in redirection parameters chapter.
    • URL address for unsuccessful payment - the client will be redirected to this address after unsuccessful payment approval at Conotoxia Pay. Redirection is described in more detail in redirection parameters chapter.
  3. After creating the store structure, you need to add your own public key in PEM format. The description of key generation is described in more detail in the generating a public key section. More information on communication security is available in the communication with Conotoxia Pay section.
  4. The last step is to generate access data to Conotoxia Pay API. This operation can be performed on the configuration page in the Merchant's panel.

After completing the above steps, the Partner should have the following data necessary for communication with Conotoxia Pay API:

Creation of a payment order

To create a payment request, simply follow a few easy steps:

  1. Generate the access token using the POST /connect/token resource. This token should be placed in the Authorization header when communicating with all resources of the Conotoxia Pay API.
  2. With your own private key, you must sign the request body (an example of the request can be found in the chapter Creating a payment). Note that JWS which will be sent to Conotoxia Pay API should have public key identifier (kid) in header section. It will be used to verify request by Conotoxia Pay system.
  3. Execute request on the POST /payments resource by placing in the request body JWS data and set correct header according to the information provided in the Communication with Conotoxia Pay section.
  4. The received response should be decoded and verified in accordance with the information provided in the Communication with the Partner section.
  5. The response contains the address to which the customer should be redirected in order to approve the payment. The rest of the process is described in the Payment Process section.

Authentication

In order to use Conotoxia Pay it is necessary to process authentication. Each request of the API provided by Conotoxia Pay requires sending an Authorization header, which contains an access token called OAuth 2.0 access token. In order to generate the token, use the POST /connect/token resource. Authentication is performed using HTTP Basic, where the user name is api_client_id and the password api_client_secret. In the body of the request, specify the grant_type parameter set to client_credentials and the scope parameter with the pay_api value.

Generating access token

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

Response body:

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

Enables getting the Conotoxia Pay access token.

Resource

POST <CONOTOXIA_OIDC_HOST>/connect/token See server addresses

Request headers

Name Value Remarks
Authorization api_client_id:api_client_secret HTTP Basic Authentication.
Content-Type application/x-www-form-urlencoded

Request body

Parameters according to client_credentials mode

Name Value
grant_type client_credentials
scope pay_api

Response

Field name Type Required Description
access_token String YES Token, which must be indicated when using the API provided by Conotoxia Pay.
expires_in String YES Token validity time in seconds.
token_type String YES Token type.

Payments

Setting up payments

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: en,pl;q=0.9,pl-PL;q=0.8" \
     -d "@data.json" \
     "<CONOTOXIA_PAY_HOST>/payments"

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

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/jose+json" \
     -H "Accept-Language: en,pl;q=0.9,pl-PL;q=0.8" \
     -d "@data.jws" \
     "<CONOTOXIA_PAY_HOST>/payments"

data.jws
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJleHRlcm5hbFBheW1lbnRJZCI6IjM0MkhISDg4TEtESjg5ODc2NzY3IiwicG9pbnRPZlNhbGVJZCI6IlBPUzQ1ODk2MzEzNjU0ODk2NTQiLCJjYXRlZ29yeSI6IkVfQ09NTUVSQ0UiLCJ0b3RhbEFtb3VudCI6eyJjdXJyZW5jeSI6IlBMTiIsInZhbHVlIjoxOS45OX0sImRlc2NyaXB0aW9uIjoiUGF5bWVudCBkZXNjcmlwdGlvbi4ifQ.FH8Ex3JCeCwud4fC_CifILcbrO6EYmjMoh1Q8ERLzfL_-T3Ieeepo4a6r8O7trpvcQKMZ6Pj9jt1SyZ7MzDFXuHXlmSl1FVwR3yqKQDZesxgmAo6ujmdNwJ0muEgUVXw9EAsbc9RKE6fFNCcMekmmkXem8-hFHueJoXZIWNOIVwBHgrMefkOSVQNHz_QD6pWrt5vhJVt1aSLnSBE1sm1Ks-ocoISPwR6MtiyXwiyCisvnTfEXvewDAFmm9b3X7YTXLtBWdKqTs8AnuiLqTx_-DwcNYX4ZPNEgTvZ7BQe_DbcTmdzfewQLVJ4Wg5REyTLUNtyxSxfZVQT_5ZTYtwQWA

Response headers:

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

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

Response body:

{
  "paymentId": "PAY715037422182587",
  "approveUrl": "https://<CONOTOXIA_APPROVAL_HOST>/approve",
  "token": "dGBcEMQoyff6OCQY5l1rehXAwgCDnEwhtp573P1EJyswGBJ79G"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk3MTUwMzc0MjIxODI1ODciLCJhcHByb3ZlVXJsIjoiaHR0cHM6Ly88Q09OT1RPWElBX0FQUFJPVkFMX0hPU1Q-L2FwcHJvdmUiLCJ0b2tlbiI6ImRHQmNFTVFveWZmNk9DUVk1bDFyZWhYQXdnQ0RuRXdodHA1NzNQMUVKeXN3R0JKNzlHIn0.KD3zD9f_xOuhVZXAMt3fyVpYlXx48rHLqNIEwGKAjHyd84_-j7oowPw8IIWZI3qdx33Z5woLMmyetH6SQpJJXjB4em826Ihg7JaZoQ0eAVez9CY0E83x51SpIwUIeKJ5I-m1-VT87dnP8yMwwD0TE212PTRjY3eNTVC3uTtu1vlYyL8fhfa3FvmjLqmCpHEEIHuJSBCsKH95mOhJlM-OgREtNX043RPyiCxl2p88lpMtOjoLYYwAIOYsVqqpylaey8xeY3kuseAIfxiPJzNIz0LJ9NdzDzWTcDUW-fVtNhG6sQXfulEazFd4qYbATimQ7Jf9Ld50LW5qHCsM-fCacA

Enables setting up a payment transaction.

Resource

POST <CONOTOXIA_PAY_HOST>/payments See server addresses

Request headers

Name Value Required Remarks
Authorization
Bearer <access_token>
 YES It must contain a Bearer access token. For more information, see Generating access token.
Content-Type
application/json
 or for signed form
application/jose+json
 YES
Accept-Language
 <language> NO A header that sets one of the two payment interface domains. For pl, it is <CINKCIARZ_PAY_WEB_HOST>, and for other languages (or no header setting), it is <CONOTOXIA_PAY_WEB_HOST>. It must comply with the RFC 7231 specification.

Request body

PaymentData object containing payment data

Field name Type Required Limit Description
totalAmount Amount YES Payment amount with the currency.
notificationUrl String NO min. 1 character max. 2048 characters A URL to which payment status notifications will be sent. As a default, the URL provided by the Partner in the configuration of the point of sale is used.
returnUrl String NO min. 1 character max. 2048 characters The URL to which the redirection will be made after payment. As a default, the URL provided by the Partner in the configuration of the point of sale is used.
errorUrl String NO min. 1 character max. 2048 characters A URL to which a redirection will be made after an unsuccessful payment attempt. As a default, the URL provided by the Partner in the configuration of the point of sale is used.
notificationUrlParameters Object NO max. 1024 characters Additional parameters, which are sent in URL payment status notifications.
pointOfSaleId String YES 18 characters Point of sale identifier.
externalPaymentId String YES min. 1 character max. 64 characters Payment identifier on the Partner's side.
storeCustomer StoreCustomer NO Store customer data which are used for reducing payment process by automatic payer data filling.
description String YES min. 1 character max. 128 characters Payment description.
category String YES min. 1 character max. 20 characters Payment category. Default value should be E_COMMERCE.
disablePayLater Boolean NO Flag specifying whether the functionality should be activated for Pay Later.
selectedPaymentMethod SelectedPaymentMethod NO It allows to redirect the customer directly to the selected payment method after redirecting him to the approveUrl address.

Amount object containing payment amount

Field name Type Required Limit Description
value Number YES Amount. Max. 19 characters with support for 2 places after the decimal separator (a dot (.) is used as the decimal separator). The number of places after the decimal separator depends on the currency and is given in the List of supported currencies.
currency String YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.

StoreCustomer object containing store customer data

Field name Type Required Limit Description
firstName String NO max. 100 characters Store customer first name.
lastName String NO max. 100 characters Store customer last name.
email String NO max. 512 characters Store customer email address.

Payment category

Defines the method of accounting with the Partner.

Value Description
MWF Fixed commission.
E_COMMERCE Percentage of commission based on the transaction value (default value).

Selected payment method

Field name Type Required Description
type String YES The available values are below.
issuer String NO The available values are below. The field can be completed only for the PAY_BY_LINK payment method.

The type field can take the following values:

Value Description
BLIK BLIK payment method
PAY_BY_LINK In this case, field issuer should be also completed

The issuer field can take the following values:

Value Description
MTRANSFER Mbank
ALIOR Alior Bank
BNP_PARIBAS BNP Paribas
IPKO PKO BP
PEKAO24 Bank Pekao SA
INTELIGO Inteligo
IDEA_BANK Idea Bank
SANTANDER Santander Bank Polska
GETIN Getin Bank
NOBLE Noble Bank
CREDIT_AGRICOLE Credit Agricole
BANK_NOWY_BFG Bank Nowy BFG
MILLENNIUM Milennium
CITI_HANDLOWY Citi Handlowy
BOS Bank Ochrony Środowiska
POCZTOWY24 Bank Pocztowy
PLUS_BANK Plus Bank
BANK_SPOLDZIELCZY SGB-Bank
BANK_SPOLDZIELCZY_W_BRODNICY Bank Spółdzielczy w Brodnicy
NEST Nest Bank
ENVELO Envelo Bank
ING ING Bank Śląski

Response body

PaymentInfo object containing the identifier of the created payment, the URL to accept the payment and the payment token.

Field name Type Required Limit Description
paymentId String YES max. 40 characters Payment identifier in the Conotoxia Pay system.
approveUrl String YES max. 256 characters The URL to which the Partner redirects the customer in order to accept the created payment.
token String YES max. 50 characters Unique token for payment confirmation.

API errors

The POST /payments method can return following business errors:

List of payments

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

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

HTTP/1.1 200 Success
Content-Type: application/jose+json

Response body:

{
  "data": [
    {
      "paymentId": "PAY772237692548117",
      "externalPaymentId": "128/06/2018",
      "status": "PROCESSING",
      "amount": {
        "value": 153.13,
        "currency": "EUR"
      },
      "description": "Order 000000001",
      "partner": {
        "commission": {
          "fee": {
            "value": 1.25,
            "currency": "EUR"
          }
        }
      },
      "type": "ONLINE_PAYMENT",
      "createdDate": "2021-02-17T11:36:15.367Z"
    },
    {
      "paymentId": "PAY815576576741391",
      "externalPaymentId": "121/06/2018",
      "status": "BOOKED",
      "amount": {
        "value": 23.52,
        "currency": "EUR"
      },
      "description": "Order 000000002",
      "type": "ONLINE_PAYMENT",
      "createdDate": "2021-01-11T07:26:33.302Z",
      "bookedDate": "2021-01-11T07:29:36.468Z"
    }
  ],
  "pagination": {
    "first": true,
    "last": true,
    "currentPageNumber": 1,
    "currentPageElementsCount": 2,
    "pageSize": 10,
    "totalPages": 1,
    "totalElements": 2,
    "pageLimitExceeded": true
  }
}

eyJhbGciOiJSUzI1NiIsImtpZCI6Il8yNzVUd3dYOVhtaVotak1wLTJwNDZ0SUsyZE0tR2xWM3dYTU1GUTM5UUEifQ.ewogICAiZGF0YSI6WwogICAgICB7CiAgICAgICAgICJwYXltZW50SWQiOiJQQVk3NzIyMzc2OTI1NDgxMTciLAogICAgICAgICAiZXh0ZXJuYWxQYXltZW50SWQiOiIxMjgvMDYvMjAxOCIsCiAgICAgICAgICJzdGF0dXMiOiJQUk9DRVNTSU5HIiwKICAgICAgICAgImFtb3VudCI6ewogICAgICAgICAgICAidmFsdWUiOjE1My4xMywKICAgICAgICAgICAgImN1cnJlbmN5IjoiRVVSIgogICAgICAgICB9LAogICAgICAgICAiZGVzY3JpcHRpb24iOiJPcmRlciAwMDAwMDAwMDEiLAogICAgICAgICAicGFydG5lciI6ewogICAgICAgICAgICAiY29tbWlzc2lvbiI6ewogICAgICAgICAgICAgICAiZmVlIjp7CiAgICAgICAgICAgICAgICAgICJ2YWx1ZSI6MS4yNSwKICAgICAgICAgICAgICAgICAgImN1cnJlbmN5IjoiRVVSIgogICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICAgfSwKICAgICAgICAgInR5cGUiOiJPTkxJTkVfUEFZTUVOVCIsCiAgICAgICAgICJjcmVhdGVkRGF0ZSI6IjIwMjEtMDItMTdUMTE6MzY6MTUuMzY3WiIKICAgICAgfSwKICAgICAgewogICAgICAgICAicGF5bWVudElkIjoiUEFZODE1NTc2NTc2NzQxMzkxIiwKICAgICAgICAgImV4dGVybmFsUGF5bWVudElkIjoiMTIxLzA2LzIwMTgiLAogICAgICAgICAic3RhdHVzIjoiQk9PS0VEIiwKICAgICAgICAgImFtb3VudCI6ewogICAgICAgICAgICAidmFsdWUiOjIzLjUyLAogICAgICAgICAgICAiY3VycmVuY3kiOiJFVVIiCiAgICAgICAgIH0sCiAgICAgICAgICJkZXNjcmlwdGlvbiI6Ik9yZGVyIDAwMDAwMDAwMiIsCiAgICAgICAgICJ0eXBlIjoiT05MSU5FX1BBWU1FTlQiLAogICAgICAgICAiY3JlYXRlZERhdGUiOiIyMDIxLTAxLTExVDA3OjI2OjMzLjMwMloiLAogICAgICAgICAiYm9va2VkRGF0ZSI6IjIwMjEtMDEtMTFUMDc6Mjk6MzYuNDY4WiIKICAgICAgfQogICBdLAogICAicGFnaW5hdGlvbiI6ewogICAgICAiZmlyc3QiOnRydWUsCiAgICAgICJsYXN0Ijp0cnVlLAogICAgICAiY3VycmVudFBhZ2VOdW1iZXIiOjEsCiAgICAgICJjdXJyZW50UGFnZUVsZW1lbnRzQ291bnQiOjIsCiAgICAgICJwYWdlU2l6ZSI6MTAsCiAgICAgICJ0b3RhbFBhZ2VzIjoxLAogICAgICAidG90YWxFbGVtZW50cyI6MiwKICAgICAgInBhZ2VMaW1pdEV4Y2VlZGVkIjp0cnVlCiAgIH0KfQ.EuuDkfr9rv90nlZ0hbjTGa014qw_oB8EDTy1DEwfpgeFuEOK7yeEJztPX07jhT3pwdIB7Dc8c9sbSCgKMCvIjoXReNicw6LyJxQwyTs9tR8BEF-UWoLKxSqUP1h_T4jpPw9YH8GMGa1UZI9nktICNezbz35fAk5UH5RhMtIbvrpxVyz4AgBGv5oxqOOS2tXj1vIjZnJ8Vu46LkLKhUZ7RyHjJxUrf5UjkghwMY4URqkKD7jX7-YENfNy5tnH1kfyvtn1osxRfjDGY1wX4JbFUlVFJdkHed0WhcEIIoqYf4MUZ6yD5XvUu1784V3Gq2VVmvoVZiawAU-nUZtbmskr4w

The payment list can be viewed in the Merchant's panel on the payments page or can be get using the resource below.

Resource

GET <CONOTOXIA_PAY_HOST>/payments See server addresses

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Field name Type Required Description
paymentIds String NO Payment identifiers (the paymentIds parameter must be duplicated in the request e.g. /payments?paymentIds=PAY772237692548117&paymentIds=PAY815576576741391).
externalPaymentId String NO External payment identifier.
createdDateFrom String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of payment creation from.
createdDateTo String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of payment creation to.
bookedDateFrom String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of payment accounting from.
bookedDateTo String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of payment accounting to.
pageNumber Number NO Page number.
pageSize Number NO Number of elements per page.
sort String NO Sorting criteria.

Sort field value for payments

You can sort the following fields:

To sort in descending order by the payment creation date, enter a value: paymentDate,DESC.

Response body

Response object containing payment data

Field name Type Required Limit Description
data Array YES max. 100 elements A list with elements of the Payment type.
pagination Pagination YES Metadata of the returned page.

Payment object containing payment details

Field name Type Required Limit Description
paymentId String YES max. 40 characters Payment identifier in the Conotoxia Pay system.
externalPaymentId String YES max. 64 characters Payment identifier in the Partner system.
status String YES max. 14 characters Payment status. Values according to the life cycle of the payment.
amount Amount YES Payment amount with the currency.
description String YES min. 1 character max. 128 characters Payment description.
partner Partner NO Partner details.
type String YES max. 20 characters Payment type.
createdDate String YES max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of created payment.
cancelledDate String NO max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of cancelled payment.
bookedDate String NO max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of booked payment.

The type field can take the following values:

Value Description
ONLINE_PAYMENT Online payment
PAYMENT_LINK_PARTNER Payment by link

Partner object containing partner information

Field name Type Required Limit Description
commission Commission NO Fees incurred by the Partner.

Amount object including payment amount and payment currency

Field name Type Required Limit Description
value Number YES Amount. Max. 19 characters with support for 2 places after the decimal separator (a dot (.) is used as the decimal separator). The number of places after the decimal separator depends on the currency and is given in the List of supported currencies.
currency String YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.

Commission object including information about payment fees charged

Field name Type Required Limit Description
fee Fee YES Fee amount with the currency.

Fee object containing the payment fee value

Field name Type Required Limit Description
value Number YES Amount. Max. 19 characters with support for 2 places after the decimal separator (a dot (.) is used as the decimal separator). The number of places after the decimal separator depends on the currency and is given in the List of supported currencies.
currency String YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.

Pagination object containing metadata of the returned payment data page

Field name Type Required Description
first Boolean YES Defines whether the returned data are on the first page.
last Boolean YES Defines whether the returned data are on the last page.
currentPageNumber Number YES Defines the number of the returned page.
currentPageElementsCount Number YES Defines the number of elements on the returned page.
pageSize Number YES Defines the page size.
totalPages Number YES Defines the number of available pages.
totalElements Number YES Defines the number of available elements.
pageLimitExceeded Boolean YES Defines whether the page limit has been reached.

API errors

The GET /payments method can only return technical errors.

Payment notifications

Object sent to the notificationUrl address provided by the Partner:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk4MTU1NzY1NzY3NDEzOTEiLCJleHRlcm5hbFBheW1lbnRJZCI6IjEyMS8wNi8yMDE4IiwiY29kZSI6IkNPTVBMRVRFRCIsInR5cGUiOiJQQVlNRU5UIn0.OvFeZeef4wWRMV5uLTlYwKXnSKGDbNLXJ1FpHiRHLQ5fxLcNMibMdYX8sXsvBsBWcjOrZOj4GKSBG1HGu9HLpdRJOE0WtL4P6CMV0_blzfXAwI_Pf6EIR0Iv84PmT2RBeUKn12ndLEirSoeap3PGeSo6z1-58mRGStZ9juSLP27MzKWb_l93FgVh5TNH3BWFsmXY2AOE9s1epZidLoGgB-XFuC6rLDA34FuC1Ao3BbLYSoo1DMxd6_TWVCO-jnPsIeofZdfbDkY1rV1SEeqxcQscsy1HHMZB02rehXI-8V4l4K2OhSXLY0Nhq7Qe3_KSWVVXTQCZmoROz6KAAdxTfA

Request headers:

Content-Type: application/json

Content-Type: application/jose+json

After the customer executes the action, an asynchronous payment process is carried out on the payment approval page. As part of the process, notifications about the change of payment status are sent to the notificationUrl address provided by the Partner when creating the payment or when configuring the point of sale. Notifications are sent by POST method and may be delivered to the Partner's system in a random order. This is due to the fact that there may be delays between the Conotoxia Pay system and the Partner's system or the system may be unavailable at the time of sending the notification. If the Partner receives one of the notifications ending the payment process, he should not respond to other notifications, which will be delivered to his system for a given payment.

Below is a description of the message parameters, which is sent to the Partner.

PaymentStatus object

Field name Type Required Limit Description
paymentId String YES max. 40 characters Payment identifier in the Conotoxia Pay system.
externalPaymentId String YES max. 64 characters Payment identifier in the Partner system.
code String YES max. 14 characters Payment status.
type String YES max. 7 characters Notification type. Value for payment PAYMENT.
description String NO max. 512 characters Description of the payment status. Can be sent for REJECTED status.
completedDate String NO max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of completed payment. Always sent for the COMPLETED status.
cancelledDate String NO max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of cancelled payment. Always sent for the CANCELLED status.
rejectedDate String NO max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of rejected payment. Always sent for the REJECTED status.
paymentMethod String NO max. 15 characters Payment method chosen by the customer. A value is always sent for the COMPLETED status and can be sent for CANCELLED and REJECTED statuses.
reasonType String NO max. 32 characters Reason for the cancellation. The value is always sent for the CANCELLED status.
additionalParameters Object NO max. 1024 characters Additional parameters defined in create payment request.

The code field can take values from the table below:

Status Description
PROCESSING The payment has been approved by the customer.
COMPLETED The payment was successfully completed.
BOOKED Funds are available to the partner.
CANCELLED The payment has been cancelled by the system.
REJECTED The payment has been rejected by the customer.

The paymentMethod field can take values from the table below:

Payment method Description
CURRENCY_WALLET Currency wallet
CREDIT_CARD Payment card
IDEAL iDEAL
EPS EPS
UNIONPAY UnionPay
BLIK BLIK
TRUSTLY Trustly
PAY_BY_LINK Online transfer
GOOGLE_PAY Google Pay
PAYPAL PayPal
SKRILL_WALLET Skrill
APPLE_PAY Apple Pay
RAPID_TRANSFER Rapid Transfer
VIPPS Vipps

The reasonType field can take values from the table below:

Reason type Description
TOKEN_EXPIRED The time to pay for the payment transaction is over
PAY_LATER_EXPIRED The time to pay for the deferred transaction has expired
NOT_AVAILABLE Payment transaction not permitted
PROCESS_EXPIRED Payment transaction expired
AUTHENTICATION_FAILED_3_DS 3D Secure authentication was not executed, or it did not execute successfully
BLOCKED_CARD The card used for the transaction is blocked
EXPIRED_CARD The card used for the transaction has expired
INVALID_CARD_NUMBER The specified card number is incorrect or invalid
CVC_DECLINED The specified card security code is invalid
NOT_ENOUGH_BALANCE The card does not have enough money to cover the payable amount
WITHDRAWAL_COUNT_EXCEEDED The number of withdrawals permitted for the shopper's card has exceeded
WITHDRAWAL_AMOUNT_EXCEEDED The withdrawal amount permitted for the shopper's card has exceeded
TRANSACTION_NOT_PERMITTED Payment transaction not permitted
CVC_LENGTH_INVALID CVC is not the right length
EXPIRY_DATE_INVALID Expiry date invalid
INVALID_CVC Invalid CVC
NOT_SUPPORTED The recipient's bank does not support or does not allow this type of transaction
RESTRICTED_CARD The card is restricted
UNSUPPORTED_CURRENCY_SPECIFIED Unsupported currency specified
OTHER Payment cancelled

Redirection parameters

Decoded data parameter:

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

After the customer executes the action on the payment approval page, redirection to the Partner's website is carried out. If the customer has successfully completed the action, it will be redirected to the returnUrl address given in the payment settings or configured by default in the point of sale. In case of technical problems, the customer is redirected to the errorUrl address (it is configured in the same way as the returnUrl address).

To the returnUrl address provided by the Partner, the Conotoxia Pay system attaches information about the payment status in the data parameter:

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

The JWS Payload section contains data saved in JSON format.

AdditionalParameters object

Field name Type Required Limit Description
paymentId String YES max. 40 characters Payment identifier in the Conotoxia Pay system.
externalPaymentId String YES max. 64 characters Payment identifier in the Partner system.
result String YES max. 50 characters Payment status. The permitted values are described below.

Permitted values of the result field:

Value Description
SUCCESS Payment correctly approved.
SUCCESS_WITH_PAY_LATER Payment correctly approved using the Pay Later functionality.
REJECTED Customer resigned from payment approval.
ERROR A problem occurred while accepting the payment (the customer can pay again if he has a link).
PENDING The payment is processed.

BLIK Level 0

After creating the payment, the transaction can be approved bypassing the payment interface for the BLIK method (BLIK Level 0). The provided resources will allow the payment to be made without redirecting the customer to an external payment page.

Example of usage:
alt text

Method availability

Before confirming payment using the BLIK method (BLIK Level 0), you can check its availability by using the resource below.

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_PAY_HOST>/payments/methods?currency=PLN&pointOfSaleId=PAY815576576741391"

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

HTTP/1.1 200 Success
Content-Type: application/jose+json

Response body:

{
  "data": [
    {
      "type": "BLIK",
      "status": "ACTIVE"
    }
  ]
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJkYXRhIjpbeyJ0eXBlIjoiQkxJSyIsInN0YXR1cyI6IkFDVElWRSJ9XX0.Oo8llkqARDeUjaU-L8Ff7GquPHPZ1eZRzbhtTmi0dc70s76J2Bh3X2iJ631-W3PQGcxuqp34pKboghYxyqq9ctC2AXFGUc-jfPi2DVOrLm08QAc31CjJB7zRXIHl5tXQYbcGqAFH4J-Ks-xQIG7jpW82W6hPS4BPyxE4wnxqh_De40-bu-q4hFjzW3_5O5CCagjuvEVnd24HyShzVCfBm2CNVeRz_nlEjvCLkjMn5kiceNAEPD-Rpxv82lDXnHxW3EX1pdPHIKdYXoFD0HnPvTqQA47hvSFu-NtLa1FxiAF2OpRWk5KzJK7VZ0SlLGLVwyLuygjOCG7cUmIm0GaztA

Resource

GET <CONOTOXIA_PAY_HOST>/payments/methods?currency={currency}&pointOfSaleId={pointOfSaleId}

Request headers

Name Value Required Remarks
Authorization
Bearer <access_token>
 YES It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Name Type Required Description
currency String YES Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.
pointOfSaleId String YES Point of sale identifier.

Response body

Response object containing payment methods data

Name Type Required Description
data Array YES A list with elements of the PaymentMethod type.

PaymentMethod object containing payment method details

Name Type Required Description
type String YES Payment method type.
status String YES Payment method status.

The status field can take the following values:

Value Description
ACTIVE Payment method is available.
UNAVAILABLE Payment method is unavailable.

Payment confirmation

Enables confirmation of payment transactions for the BLIK method (BLIK Level 0). In this case, the transaction is confirmed in the same currency as provided in the payment creation step.

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: pl,cs;q=0.9,en;q=0.8,pl-PL;q=0.7" \
     -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)" \
     -H "User-Real-Ip: 64.233.160.25" \
     -H "User-Real-Port: 45688" \
     -H "User-Screen-Resolution: 1920x1080" \
     -H "fingerprint: {"some.domain":"1df8g16161f8we81sfwe8"}" \
     -d "@data.json" \
     "<CONOTOXIA_PAY_HOST>/payments/token/BernF3Ix5ozjyOBkePeiMkZNgideCMkvUox7bn8Povvq8CXYkv/confirmations"

data.json
{
  "type": "BLIK",
  "blikCode": "123456",
  "additionalData": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Kowalski"
  },
  "notificationsLocale": "en-GB"
}

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/jose+json" \
     -H "Accept-Language: pl,cs;q=0.9,en;q=0.8,pl-PL;q=0.7" \
     -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)" \
     -H "User-Real-Ip: 64.233.160.25" \
     -H "User-Real-Port: 45688" \
     -H "User-Screen-Resolution: 1920x1080" \
     -H "fingerprint: {"some.domain":"1df8g16161f8we81sfwe8"}" \
     -d "@data.jws" \
     "<CONOTOXIA_PAY_HOST>/payments/token/BernF3Ix5ozjyOBkePeiMkZNgideCMkvUox7bn8Povvq8CXYkv/confirmations"

data.jws
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiQkxJSyIsImJsaWtDb2RlIjoiMTIzNDU2IiwiYWRkaXRpb25hbERhdGEiOnsiZW1haWwiOiJqLmtvd2Fsc2tpQGNvbm90b3hpYS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJLb3dhbHNraSJ9LCJub3RpZmljYXRpb25zTG9jYWxlIjoiZW4tR0IifQ.dJAliOmP8hOThHP73JfPoMgTA1TKktTgnTyj9idzJhTWMyy_St5GgfobWtX85y0SZmohEfm4SOgoBQbArvJFmbTmhJJjpXi5EnTqWL-HFF1i0OoHCD3Em3RBEDtSnVTIVTKyWKshl1puM-LbYdRr02iHlALrM7r72Snc8KrFfYM2_t5kvTzvlNFvMo_TLu_45F-n-2VR8GeyP6bjT9pZm3v1wjbSZbVXYpFXPmJgbAhECng4jEIguE9OQaeP8kKG6_NYYZR5GW72S0zDAjCMCy5bdLWXbe8mr8Ohj6Sf8xAPoSX3vKHyrElO9G4R0CvFUNE7d2V4pNaGtlus4MjXKg

Response headers:

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

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

Response body:

{
  "paymentStatus": "WAITING_FOR_NOTIFICATION"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50U3RhdHVzIjoiV0FJVElOR19GT1JfTk9USUZJQ0FUSU9OIn0.Up-KrFC3ikd3W88C7-vUu5sJFFva-p34p4kgHpaF0yTF3IKuOUc6fSivleWwZy6pV5mGvYR2_nzdMs3xH5nfHrzj4Cwws9Mi0ZwxWy9Zm-fcnmbMsPBQ1NbsuTIvC8SmZccmJHdVR8wxAtXVkFKiDGJ66_h0UdrUWKijhlpoZ-B_WULd8tSP5iOnAyamohx7_JwAKAapLxagZdexi_Fmoh3IYyzzVe8gEjR3g7upWJ5NU_8AK_6e17aiSskXnEe9-lMrcShG3M2FwU7qvCGrAN6QYxq5g-n0-RbG-wkzX6GSQMQUJcAcy5r5sP6t7ZxwBZ36BNOBYBxWNwLjCoIXxQ

Resource

POST <CONOTOXIA_PAY_HOST>/payments/token/{token}/confirmations

Request headers

Name Value Required Remarks
Authorization
Bearer <access_token>
 YES It must contain a Bearer access token. For more information, see Generating access token.
Content-Type
application/json
 or for signed form
application/jose+json
 YES
Accept-Language
 <language> YES The header sets the appropriate language for the email notifications with the payment status that the customer will receive. It must comply with the RFC 7231 specification.
User-Agent User-Agent header value from user browser. YES
User-Real-Ip User IP. YES
User-Real-Port User port. YES
User-Screen-Resolution User screen resolution (eg. 1920x1080). YES
fingerprint Hash of user session identifier. YES

Path parameters

Name Type Required Description
token String YES Payment token from the token field in the PaymentInfo object.

Request body

Name Type Required Description
type String YES Payment method type.
blikCode String YES Code from the BLIK (BLIK Level 0) system. The field is required for the selected BLIK payment method.
additionalData AdditionalData YES Additional information about Customer.
notificationsLocale String NO A parameter that overrides the Accept-Language header, which sets the appropriate language for email notifications with the payment status that the customer will receive. It must comply with the BCP 47 standard.

The notificationsLocale field can take the following values:

Value Description
en-GB English
pl-PL Polish

AdditionalData object containing customer's data

Name Type Required Description
email String YES Customer's e-mail.
firstName String YES Customer's first name.
lastName String YES Customer's last name.

Response body

Name Type Required Description
paymentStatus String YES Payment status.

The paymentStatus field can take the following values:

Value Description
INITIATED Payment initiated.
WAITING_FOR_NOTIFICATION Payment is waiting for confirmation from external payment provider.
AUTHORIZATION_REQUESTED Payment requires authorization in external payment provider.
CANCELLED Payment cancelled.
CONFIRMED Payment confirmed.

API errors

The POST /payments/token/{token}/confirmations method can return following business errors:

Payment status

Allows to check the payment status after its confirmation. The resource can be used to update the status of the transaction confirmed with the BLIK (BLIK Level 0) payment method in the client's browser.

curl -X 'GET' \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_PAY_HOST>/payments/status?paymentId=PAY445458962445154"

Response headers:

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

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

Response body:

{
  "paymentStatus": "CONFIRMED",
  "paymentId": "PAY445458962445154"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50U3RhdHVzIjoiQ09ORklSTUVEIiwicGF5bWVudElkIjoiUEFZNDQ1NDU4OTYyNDQ1MTU0In0.HQHzzoMgBh-gjc1EFlpcSozMSG4HGCaO_U2kWrLLTIihyMLcv-_ySPCLguA8r4OKeXeQRzaX2rCPAVwUyA8Xyuhy9bHXgNHjURw_4OfZy1DvkJxLy6HujsrRixd8NjXKT23bsDSb0Wv_HPn6KL2ATF1vOH0TjNP0dkIe26gcBjPLfo7Sez22nHgjqhWZBIsaZBh9GRr3zURdyjAJkQAzeSPu93OGwPPGsqZVY2oELkXP7sP9iwOKe9BrR2hqskJsWC4PTY8JZvuWOlv8-ho8EZfgugwL6bMn0qh8XVa_Ld5uOuZo2wePhdvGPVrZi7pVWMCIu6iNj9V8tVA0okflOA

Resource

GET <CONOTOXIA_PAY_HOST>/payments/status?paymentId={paymentId}

Request headers

Name Value Required Remarks
Authorization
Bearer <access_token>
 YES It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Name Type Required Description
paymentId String Yes Payment identifier from the paymentId field in the PaymentInfo object.

Response body

Name Type Required Description
paymentId String YES Payment identifier.
paymentStatus String YES Payment status.

The paymentStatus field can take the following values:

Value Description
INITIATED Payment initiated.
WAITING_FOR_NOTIFICATION Payment is waiting for confirmation from external payment provider.
AUTHORIZATION_REQUESTED Payment requires authorization in external payment provider.
CANCELLED Payment cancelled.
CONFIRMED Payment confirmed.

EPS

After creating the payment, the transaction can be approved bypassing the payment interface for the EPS method. The provided resources will allow the payment to be made by directly redirecting the customer to the bank's website. Example sequence diagrams are provided in the chapter Payment process - EPS.

Example of usage:
alt text

Method availability

Before confirming payment using the EPS method, it is necessary to check its availability by using the resource below.

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_PAY_HOST>/payments/methods?currency=EUR&pointOfSaleId=PAY815576576741391"

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

HTTP/1.1 200 Success
Content-Type: application/jose+json

Response body:

{
  "data": [
    {
      "type": "EPS",
      "status": "ACTIVE",
      "issuers": [
        {
          "id": "edc8afd1-6258-4982-b523-aab56e423c8a",
          "name": "Bank name",
          "code": "BANK_CODE"
        }
      ]
    }
  ]
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJkYXRhIjpbeyJ0eXBlIjoiRVBTIiwic3RhdHVzIjoiQUNUSVZFIiwiaXNzdWVycyI6W3siaWQiOiJlZGM4YWZkMS02MjU4LTQ5ODItYjUyMy1hYWI1NmU0MjNjOGEiLCJuYW1lIjoiQmFuayBuYW1lIiwiY29kZSI6IkJBTktfQ09ERSJ9XX1dfQ.H-_hA-eIbjzZBZn3Td-Nl17zKjV5Tq8qkaHQVD50MOVEJEMg-DpOKC_Sb1UujT3ppxJBsfYpsCN5_i7EouTuxK14V-3ckcNiuJt-ZkE_ZMwgV0TmUiNC-ONJJv2AE9YhgzkOH1K_xzkDEoqk5DDz3HMFAHyhyhllaxmE6s7izU4Nu-6o3Q2j_wfUN9dT-R9YWxJ-q_jT88-oes4kRwYEVTd63ov4f9y7svSxvyCOifBfRkvIQkWjmcen-x2LMpg0XUkDxRU0YjSk4Z1SR8D4lmBHihucB8jKTqnbCp6QnHIFhwXKpYkFGwFw9UMsfbt3UCDaEdPM1A5nD2yPNqVYUQ

Resource

GET <CONOTOXIA_PAY_HOST>/payments/methods?currency={currency}&pointOfSaleId={pointOfSaleId}

Request headers

Name Value Required Remarks
Authorization
Bearer <access_token>
 YES It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Name Type Required Description
currency String YES Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.
pointOfSaleId String YES Point of sale identifier.

Response body

Response object containing payment methods data

Nazwa pola Typ Wymagalność Opis
data Array TAK A list with elements of the PaymentMethod type.

PaymentMethod object containing payment method details

Name Type Required Description
type String YES Payment method type.
status String YES Payment method status.
issuers Array NO A list with elements of the Issuer type.

The status field can take the following values:

Value Description
ACTIVE Payment method is available.
UNAVAILABLE Payment method is unavailable.

Issuer object containing bank details

Name Type Required Description
id String YES Bank identifier.
name String YES Bank name.
code String YES Bank code.

Bank icons

For each available bank represented by the Issuer object, you can retrieve the icon and present it to the customer.

Resource

GET <CONOTOXIA_PAY_HOST>/images/logos/eps/{issuerId}.svg

Path parameters

Name Type Required Description
issuerId String YES Bank identifier from the id field in the Issuer object.

Payment confirmation

Enables confirmation of payment transactions for the EPS method. In this case, the transaction is confirmed in the same currency as provided in the payment creation step.

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: pl,cs;q=0.9,en;q=0.8,pl-PL;q=0.7" \
     -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)" \
     -H "User-Real-Ip: 64.233.160.25" \
     -H "User-Real-Port: 45688" \
     -H "User-Screen-Resolution: 1920x1080" \
     -H "fingerprint: {"some.domain":"1df8g16161f8we81sfwe8"}" \
     -d "@data.json" \
     "<CONOTOXIA_PAY_HOST>/payments/token/BernF3Ix5ozjyOBkePeiMkZNgideCMkvUox7bn8Povvq8CXYkv/confirmations"

data.json
{
  "type": "EPS",
  "issuer": "6c48eff1-48be-4751-8eaa-71b96cc06b4d",
  "issuerCode": "BANK_CODE",
  "additionalData": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Kowalski"
  },
  "notificationsLocale": "en-GB"
}

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/jose+json" \
     -H "Accept-Language: pl,cs;q=0.9,en;q=0.8,pl-PL;q=0.7" \
     -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)" \
     -H "User-Real-Ip: 64.233.160.25" \
     -H "User-Real-Port: 45688" \
     -H "User-Screen-Resolution: 1920x1080" \
     -H "fingerprint: {"some.domain":"1df8g16161f8we81sfwe8"}" \
     -d "@data.jws" \
     "<CONOTOXIA_PAY_HOST>/payments/token/BernF3Ix5ozjyOBkePeiMkZNgideCMkvUox7bn8Povvq8CXYkv/confirmations"

data.jws
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiRVBTIiwiaXNzdWVyIjoiNmM0OGVmZjEtNDhiZS00NzUxLThlYWEtNzFiOTZjYzA2YjRkIiwiaXNzdWVyQ29kZSI6IkJBTktfQ09ERSIsImFkZGl0aW9uYWxEYXRhIjp7ImVtYWlsIjoiai5rb3dhbHNraUBjb25vdG94aWEuY29tIiwiZmlyc3ROYW1lIjoiSm9obiIsImxhc3ROYW1lIjoiS293YWxza2kifSwibm90aWZpY2F0aW9uc0xvY2FsZSI6ImVuLUdCIn0.SIocHLiz-_FTdoq2TF88wg9EbnTjJKBuc1T3tvAJLKnpylZBVS5Navck0qIBc-7Y28wyTdVYDg_zHkCoTbzFAB94WdRc0X4_gN55cx4QAxwgWaUmnmSy5BLAVu_Wwj2D9_QU7UMKT_EU5jAjSsm93GjAlXBxzmg-mJ6rsEzER2Tf2tosPPlBX4Vr25qteurcv5RpQSTcw3wZhw4TBtLpw--YfBBXcM9_g3jFKU5k4T0CEbZCzPciA7KDTMbPaz1phV97tcelcMJLDDMxfiew6gRgWftoGd0JqAd2dehhS3U2i7YbyhO62mccSBjxaOy4qS6J77OkbKJntReFW5RKuA

Response headers:

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

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

Response body:

{
  "redirectUrl": "https://www.example.com/redirect",
  "redirectMethod": "GET"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJyZWRpcmVjdFVybCI6Imh0dHBzOi8vd3d3LmV4YW1wbGUuY29tL3JlZGlyZWN0IiwicmVkaXJlY3RNZXRob2QiOiJHRVQifQ.J5h5_dlyWEmLviMRGQaVMH-b7jBv5CwUQvMWAO51HERInNjqfDWkZdAjB56AARR6BK_FLN7UBPB9DFwtChoReR6xg20gOJld4Ctl00l2wvZ6lPRazIt4MA1Quo3pkM7p64vZQ6QX2mM8vVRqMjdGQc8HgEhHgnwgciU8w9rdxWbFxTWdZnalG2Fu9KXIKG5ZnWTmYO3L91HEWwL9SjI_lL_Os7r8V_ORPQPIX5-A3RUR3s1kTiI0gwPJzRlWzhVTIlRbnRBvj6m5GTJkK3ULug01k1O9UfWoaKNRgJ9TSMNgTi1PHdbm1P_rZRZ5FqMeTb2tWhcRBJquCTaHXF_BNQ

Resource

POST <CONOTOXIA_PAY_HOST>/payments/token/{token}/confirmations

Request headers

Name Value Required Remarks
Authorization
Bearer <access_token>
 YES It must contain a Bearer access token. For more information, see Generating access token.
Content-Type
application/json
 or for signed form
application/jose+json
 YES
Accept-Language
 <language> YES The header sets the appropriate language for the email notifications with the payment status that the customer will receive. It must comply with the RFC 7231 specification.
User-Agent User-Agent header value from user browser. YES
User-Real-Ip User IP. YES
User-Real-Port User port. YES
User-Screen-Resolution User screen resolution (eg. 1920x1080). YES
fingerprint Hash of user session identifier. YES

Path parameters

Name Type Required Description
token String YES Payment token from the token field in the PaymentInfo object.

Request body

Name Type Required Description
type String YES Payment method type.
issuer String YES Bank identifier from the id field in the Issuer object.
issuerCode String YES Bank code from the code field in the Issuer object.
additionalData AdditionalData YES Additional information about customer.
notificationsLocale String NO A parameter that overrides the Accept-Language header, which sets the appropriate language for email notifications with the payment status that the customer will receive. It must comply with the BCP 47 standard.

The notificationsLocale field can take the following values:

Value Description
en-GB English
pl-PL Polish

AdditionalData object containing customer's data

Name Type Required Description
email String YES Customer's e-mail.
firstName String YES Customer's first name.
lastName String YES Customer's last name.

Response body

Name Type Required Description
redirectUrl String YES The bank's URL to which the customer should be redirected.
redirectMethod String YES The HTTP method that should be used for redirection.

API errors

The POST /payments/token/{token}/confirmations method can return following business errors:

Refunds

Setting up refunds

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     -d "@data.json" \
     "<CONOTOXIA_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"
}

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

data.jws
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk3MTUwMzc0MjIxODI1ODciLCJyZWFzb24iOiJEYW1hZ2VkIGNvdmVyIiwiYW1vdW50Ijp7ImN1cnJlbmN5IjoiUExOIiwidmFsdWUiOjM0Ljk5fSwiZXh0ZXJuYWxSZWZ1bmRJZCI6IjIzNC8wMy8yMDE2Iiwibm90aWZpY2F0aW9uVXJsIjoiaHR0cDovL3Nob3AuY29tL25vdGlmaWNhdGlvbnMifQ.NacbH-nTXcqY8Yv7Ib1B2l2RUS-vRe8MTGauT_9wYEoGUdpZD8Pks8T2_dLVGxtO4An66VNHn61YYNY3XQCVAaeb2oQ_g1jXacTNIFIgoMCF8v6-nKu3sigYgvCntuM98XfRgLD-T7i6chR-TizggWhJ5dSpNRXwEpNfV9YGUgtroLb9Bt4H99Ys-S6Twzfg23Bj6JZEFb121Dsk7cZE2TEdwDjkiM3PUaWqIVbPDXP-N-kYx2ZZKrv4kIyLBa9990i4yn_KxCHcPSrPcyXE4cROTOSjunfCX_y-PfM96H7oR-5vI9cVnuPrSaF2kf6cHjtsUPnOHGqA7Owj7zfEvQ

Response headers:

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

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

Response body:

{
  "id": "REF505142910935123"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJpZCI6IlJFRjUwNTE0MjkxMDkzNTEyMyJ9.fNuI_zsMz8JPhAiQjpvcGYwiYGkFuR6LWdueA4RgU-GcCzH4RdZULnMg4V-hyu3Of0G6u9qaqVw8SSPRRy_O59CijaYLI6cMSzg2W5L-mMHVUveWTgI-DLQ1v0Jemx5sri27vsq7TDMcfDNnGigWFkmvJx1nYeWS_1lTzXdYrDHxldjJhGUbF2aLr_hzrn4SRqlTf0XYc8vVGm65OS64iowFn2osd-ByXAr9LOMUsSenW14qwBLwth9_BartZO_ce1j1sBlBTYGlgPpy6xVaQjbaUcJySEqVY0vwXpCGPygLyYqt0w55F82s2bW7Qg7QW4bUu5GNAVjTai4QKjUHSg

Allows to create a refund for payment transaction. The refund creation can be also made from the Merchant's panel on the payment details page.

Resource

POST <CONOTOXIA_PAY_HOST>/refunds See server addresses

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.
Content-Type
application/json
 or for signed form
application/jose+json

Request body

RefundData object containing refund data

Field name Type Required Limit Description
paymentId String YES max. 40 characters Payment identifier in the Conotoxia Pay system.
reason String YES min. 5 characters max. 512 characters Reason for which the refund is made.
amount Amount NO Refund amount. If the amount is not specified or if it is equal to the amount of the payment, a full refund will be created. The currency must always correspond to the currency in which the payment was made.
externalRefundId String NO min. 1 character max. 64 characters Refund identifier in the Partner system.
notificationUrl String NO min. 1 character max. 2048 characters The URL to which the refund status notifications will be sent. As a default, the URL provided by the Partner in the configuration of the point of sale is used.
notificationUrlParameters Object NO max. 1024 characters Additional parameters, which are sent in URL refund status notifications.

Amount object containing refund amount

Field name Type Required Limit Description
value Number YES Amount. Max. 19 characters with support for 2 places after the decimal separator (a dot (.) is used as the decimal separator). The number of places after the decimal separator depends on the currency and is given in the List of supported currencies.
currency String YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.

Response body

RefundInfo object containing the identifier of the refund created

Field name Type Required Limit Description
id String YES max. 40 characters Refund identifier in the Conotoxia Pay system.

API errors

The POST /refunds can return the following business errors:

List of refunds

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

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

HTTP/1.1 200 Success
Content-Type: application/jose+json

Response body:

{
  "data": [
    {
      "refundId": "REF192843325139567",
      "externalRefundId": "128/06/2018",
      "status": "NEW",
      "amount": {
        "value": 9.99,
        "currency": "EUR"
      },
      "description": "Wrong order",
      "type": "PARTIAL",
      "createdDate": "2020-01-24T10:06:10.945Z"
    },
    {
      "refundId": "REF942484723821414",
      "externalRefundId": "121/06/2018",
      "status": "COMPLETED",
      "amount": {
        "value": 109.99,
        "currency": "EUR"
      },
      "description": "Wrong order",
      "partner": {
        "commission": {
          "fee": {
            "value": 1.25,
            "currency": "EUR"
          }
        }
      },
      "type": "FULL",
      "createdDate": "2020-11-25T15:14:38.226Z",
      "bookedDate": "2020-11-25T15:15:50.140Z"
    }
  ],
  "pagination": {
    "first": true,
    "last": true,
    "currentPageNumber": 1,
    "currentPageElementsCount": 2,
    "pageSize": 10,
    "totalPages": 1,
    "totalElements": 2,
    "pageLimitExceeded": true
  }
}

eyJhbGciOiJSUzI1NiIsImtpZCI6Il8yNzVUd3dYOVhtaVotak1wLTJwNDZ0SUsyZE0tR2xWM3dYTU1GUTM5UUEifQ.ewogICAiZGF0YSI6WwogICAgICB7CiAgICAgICAgICJyZWZ1bmRJZCI6IlJFRjE5Mjg0MzMyNTEzOTU2NyIsCiAgICAgICAgICJleHRlcm5hbFJlZnVuZElkIjoiMTI4LzA2LzIwMTgiLAogICAgICAgICAic3RhdHVzIjoiTkVXIiwKICAgICAgICAgImFtb3VudCI6ewogICAgICAgICAgICAidmFsdWUiOjkuOTksCiAgICAgICAgICAgICJjdXJyZW5jeSI6IkVVUiIKICAgICAgICAgfSwKICAgICAgICAgImRlc2NyaXB0aW9uIjoiV3Jvbmcgb3JkZXIiLAogICAgICAgICAidHlwZSI6IlBBUlRJQUwiLAogICAgICAgICAiY3JlYXRlZERhdGUiOiIyMDIwLTAxLTI0VDEwOjA2OjEwLjk0NVoiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAgInJlZnVuZElkIjoiUkVGOTQyNDg0NzIzODIxNDE0IiwKICAgICAgICAgImV4dGVybmFsUmVmdW5kSWQiOiIxMjEvMDYvMjAxOCIsCiAgICAgICAgICJzdGF0dXMiOiJDT01QTEVURUQiLAogICAgICAgICAiYW1vdW50Ijp7CiAgICAgICAgICAgICJ2YWx1ZSI6MTA5Ljk5LAogICAgICAgICAgICAiY3VycmVuY3kiOiJFVVIiCiAgICAgICAgIH0sCiAgICAgICAgICJkZXNjcmlwdGlvbiI6Ildyb25nIG9yZGVyIiwKICAgICAgICAgInBhcnRuZXIiOnsKICAgICAgICAgICAgImNvbW1pc3Npb24iOnsKICAgICAgICAgICAgICAgImZlZSI6ewogICAgICAgICAgICAgICAgICAidmFsdWUiOjEuMjUsCiAgICAgICAgICAgICAgICAgICJjdXJyZW5jeSI6IkVVUiIKICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9CiAgICAgICAgIH0sCiAgICAgICAgICJ0eXBlIjoiRlVMTCIsCiAgICAgICAgICJjcmVhdGVkRGF0ZSI6IjIwMjAtMTEtMjVUMTU6MTQ6MzguMjI2WiIsCiAgICAgICAgICJib29rZWREYXRlIjoiMjAyMC0xMS0yNVQxNToxNTo1MC4xNDBaIgogICAgICB9CiAgIF0sCiAgICJwYWdpbmF0aW9uIjp7CiAgICAgICJmaXJzdCI6dHJ1ZSwKICAgICAgImxhc3QiOnRydWUsCiAgICAgICJjdXJyZW50UGFnZU51bWJlciI6MSwKICAgICAgImN1cnJlbnRQYWdlRWxlbWVudHNDb3VudCI6MiwKICAgICAgInBhZ2VTaXplIjoxMCwKICAgICAgInRvdGFsUGFnZXMiOjEsCiAgICAgICJ0b3RhbEVsZW1lbnRzIjoyLAogICAgICAicGFnZUxpbWl0RXhjZWVkZWQiOnRydWUKICAgfQp9.Q1ydhLIDwWM4WX_bISLiMvfSSvd7DtOvcXLhwFyygYs8vZVDVrTpGCZOHAY9wpfEc0DcAbPZfC-i3EX5hf7Z_D5RbmOzBV3oazWRKZNuf8WflGI2K8J--gJNwuJKUq01tqVab2WLKv_EF7_zybuP9SZmhgKYJnZbz0AIiDW3H4hmieRm6GLjImSXNphel-eg4q4dT83wRndnmxpFdu_lbUa5BiQn9MrEk0uHdOVVnqP8vtZcfvlfF8KGoEAyCn7vFZGMBNmyaUXtipd3PRiXyepgV4oKfUTUbpOYdSBrilUHvDrvhXHmX9Kx0g7SVOfHRrs3WDfXZe9telxnljARTg

The list of refunds can be viewed in the Merchant's panel on the refunds list or can be get using the resource below.

Resource

GET <CONOTOXIA_PAY_HOST>/refunds See server addresses

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Field name Type Required Description
paymentIds String NO Payment identifiers (the paymentIds parameter must be duplicated in the request e.g. /payments?paymentIds=PAY772237692548117&paymentIds=PAY815576576741391)
refundIds String NO Refund identifiers (parameter refundIds must be duplicated in the request e.g. /payments?refundIds=REF192843325139567&refundIds=REF942484723821414).
externalRefundId String NO External payment identifier.
createdDateFrom String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of refund creation from.
createdDateTo String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of refund creation to.
bookedDateFrom String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of refund booking from.
bookedDateTo String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of refund booking to.
pageNumber Number NO Page number.
pageSize Number NO Number of elements per page.
sort String NO Sorting criteria.

Sort field value for refunds

You can sort the following fields:

To sort in descending order by the refund creation date, enter a value: refundDate,DESC.

Response body

Response object containing refund data

Field name Type Required Limit Description
data Array YES max. 100 elements List with elements of the Refund type.
pagination Pagination YES Metadata of the returned page.

A Refund object containing refund details

Field name Type Required Limit Description
refundId String YES max. 40 characters Refund identifier in the Conotoxia Pay system.
externalRefundId String NO max. 64 characters Refund identifier in the Partner system.
status String YES max. 20 characters Refund status. Values according to the life cycle of the refund.
amount Amount YES Refund amount with the currency.
description String YES min. 1 character max. 128 characters Refund description.
partner Partner NO Partner details.
type String YES max. 20 characters Refund type.
createdDate String YES max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of created refund.
cancelledDate String NO max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of cancelled refund.
bookedDate String NO max. 128 characters Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of booked refund.

The type field can take the following values:

Value Description
PARTIAL Partial refund
FULL Full refund

Partner object containing partner information

Field name Type Required Limit Description
commission Commission NO Fees incurred by the Partner.

Amount object including refund amount and refund currency

Field name Type Required Limit Description
value Number YES Amount. Max. 19 characters with support for 2 places after the decimal separator (a dot (.) is used as the decimal separator). The number of places after the decimal separator depends on the currency and is given in the List of supported currencies.
currency String YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.

Commission object including information about refund fees charged

Field name Type Required Limit Description
fee Fee YES Fee amount with the currency.

Fee object containing the refund fee value

Field name Type Required Limit Description
value Number YES Amount. Max. 19 characters with support for 2 places after the decimal separator (a dot (.) is used as the decimal separator). The number of places after the decimal separator depends on the currency and is given in the List of supported currencies.
currency String YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.

Pagination object containing metadata of the returned page with refund data

Field name Type Required Description
first Boolean YES Defines whether the returned data are on the first page.
last Boolean YES Defines whether the returned data are on the last page.
currentPageNumber Number YES Defines the number of the returned page.
currentPageElementsCount Number YES Defines the number of elements on the returned page.
pageSize Number YES Defines the page size.
totalPages Number YES Defines the number of available pages.
totalElements Number YES Defines the number of available elements.
pageLimitExceeded Boolean YES Defines whether the page limit has been reached.

API errors

The GET /refunds method can only return technical errors.

Refund notifications

Object sent to the notificationUrl address provided by the Partner:

{
    "refundId": "REF4589632145896",
    "paymentId": "PAY78349563479853",
    "externalPaymentId": "121/06/2018",
    "code": "COMPLETED",
    "type": "REFUND"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJyZWZ1bmRJZCI6IlJFRjQ1ODk2MzIxNDU4OTYiLCJwYXltZW50SWQiOiJQQVk3ODM0OTU2MzQ3OTg1MyIsImV4dGVybmFsUGF5bWVudElkIjoiMTIxLzA2LzIwMTgiLCJjb2RlIjoiQ09NUExFVEVEIiwidHlwZSI6IlJFRlVORCJ9.Mv-U08X_UOtLzt6V5jrPDJWXXYH--H9K3jdjCg9gTAyqg3gDqAJtpe2J0DxvqjtY-qV4HjR94nmcAuVyeVTQMvD4jiBYERNkPH4kUVsZ7bGy9hkvUbFTb9ijD62ZYLQHwXERqUpcEHEX_v_RttvBjrBJ0rTbHoyv-0CMjE3pUl9Oy8tFY2btwcXDWjeQ3PUuBOefscf8-n12LR7BkDU_Alzv_ZI7L6cUMbRby5vkz-Lpi5-aQ7J1YMWthTkxSQc0lLfxBT6GatOiFx1rnH7CyKvDlrH_sCd_P9ggs-3JfqscIBMozvqkaWCgW9nAzfeLJKOylHYU51KYTc8H65nXtQ

Request headers:

Content-Type: application/json

Content-Type: application/jose+json

After ordering a refund by the Partner, an asynchronous refund process is carried out. As part of the process, notifications of status changes are sent to the notificationUrl address provided by the Partner when creating the refund or when configuring the point of sale. Notifications are sent by POST method and may be delivered to the Partner's system in a random order. This is due to the fact that there may be delays between the Conotoxia Pay system and the Partner's system or the system may be unavailable at the time of sending the notification. If the Partner receives one of the notifications ending the refund process, he should not react to other notifications that will be delivered to his system for a given refund.

Below is a description of the message parameters, which is sent to the Partner.

RefundStatus object

Field name Type Required Limit Description
refundId String YES max. 40 characters Refund identifier in the Conotoxia Pay system.
externalRefundId String NO max. 64 characters Refund identifier in the Partner system.
paymentId String YES max. 40 characters Related payment identifier in the Conotoxia Pay system.
externalPaymentId String YES max. 64 characters Related payment identifier in the Partner system.
code String YES max. 14 characters Refund status.
type String YES max. 7 characters Notification type. Value for refund REFUND.
maxRefundAchieved Boolean NO Whether it is possible to create next refund for the same payment.
additionalParameters Object NO max. 1024 characters Additional parameters defined in create refund request.

The code field can take values from the table below (corresponding to refund statuses):

Status Description
NEW The refund has been created.
PROCESSING The refund is processed.
PENDING The refund is awaiting cash.
COMPLETED The refund has been successfully completed.
CANCELLED The refund has been cancelled.

API errors - technical

Description of errors returned by Conotoxia Pay API for all shared resources.

400 Bad Request

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkJhZCBSZXF1ZXN0Iiwic3RhdHVzIjo0MDAsImRldGFpbCI6IlVuZXhwZWN0ZWQgY2hhcmFjdGVyICgnZicgKGNvZGUgMTAyKSk6IHdhcyBleHBlY3RpbmcgY29tbWEgdG8gc2VwYXJhdGUgT2JqZWN0IGVudHJpZXMifQ.Ou8rJviQ9T2Ebj9Q7Wwza0T4G6EIFBRbWCIuEX8bBjVwW8OL_hvqYYC_4lbAMkp2Si6rlzp373Pj4wlkxxX0hkub91wsMDDUHDkEysOXJY9jOGoUOgHmZTP7JrvGdEZcN8DtUulTn55s_rNxSO66-IKYoOOcFwEAL_0zJ4aDb8mXdcY_gmgLyVnq4EKJL2lBai88UG63mRayWiiIWR5I-UFvsQ8X0wRSrEzJwzz7zOl-DeKoku5dZTIwqtPOksy4BMJXDFLlcDg5MvIFa40yO1M8Hn8SN2bxMCCgo3NkzXC4RZ3lgAHyyvpLdHsJdfiU1iqz8YhgeV1MuxqaJ-sCEQ

Returned when a request has an incorrect structure.

401 Unauthorized

Response headers:

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

HTTP/1.1 401 Unauthorized
Content-Type: application/jose+json

Response body:

{
    "title": "Unauthorized",
    "status": 401,
}

eyJhbGciOiJSUzI1NiIsImtpZCI6Il8yNzVUd3dYOVhtaVotak1wLTJwNDZ0SUsyZE0tR2xWM3dYTU1GUTM5UUEifQ.ewogICAgInRpdGxlIjogIlVuYXV0aG9yaXplZCIsCiAgICAic3RhdHVzIjogNDAxCn0K.wvj-U9YSpJlo5bG35qnBW6N-EGMYw2kURvibSSJbpl3dtVhHlQCdQQ9vicDUhrhTXrLd39DHg-r1Zyhj6b6WFmQvteci-bRu-kU97K0tiTqbWY2TeK9BD9Zbf5pI0U4bFqBAddK4nm2WGYGwsDBO2qeFKSLcVL5UGHowGwortl7DCsscIBjtsjUq_eNClwXsAPPt9UaFLZSXNf4WIy62LOl3ZCvFx-lBzYaKxC4cCewIznFo33epLJxE35xoFGu_3lcI2u1JFG5PUi7W5RKHmEQhnGwaobRkJ0mdAG76Ut-X8c7WoEuCk7E5MDeEoDf-BcISgVfn-lIyY5eGsZs4nQ

Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.

403 Forbidden

Response headers:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

HTTP/1.1 403 Forbidden
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkZvcmJpZGRlbiIsInN0YXR1cyI6NDAzfQ.Wwp9fE54f3KclIVvGVdU3ZpUGZ4qZtC4PTyLXyAJRdqlDTcyDjIJ1ccGVKLv1YYdd_TZewiVqMR_iKCMeAoKlrFq8qsPH8NRXfJ4LCOopfF9i9zdfLkNXIVJkqm_1H-qsU9AvorPSB1mqNKy4MYfj5k-KWN559yFagBL4P2shwR3Ee0_cDy8A11fbR_8jzs5nU-hWOFR5qME7QG7leEM9ZRuna2ogRShEhXMqbThRnbDLU73uVWPmlj_5hJ8FBDjl_v5KrUBOKDFp2Hdq1t9sjzqvJPzuKYr_J6rWLa3FTlOv6ew4RuvWDgUTCJW_xaQMKSC181OgtSuYcUlH7XISg

Returned when the customer does not have access to requested resource.

405 Method Not Allowed

Response headers:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/problem+json

HTTP/1.1 405 Method Not Allowed
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6Ik1ldGhvZCBOb3QgQWxsb3dlZCIsInN0YXR1cyI6NDA1LCJkZXRhaWwiOiJSZXF1ZXN0IG1ldGhvZCAnUFVUJyBub3Qgc3VwcG9ydGVkIn0.HScFAydfT_EHZwvbkT_izwBUAlb3CCt_X6nhs_XQxkHrbpQL1hDg5JrcxYGsC5O14yXgnwUMxKlc7YO66X1j9CZAbRxL5Hi95NKMJZuh0BM1geweQYGvBbrRrd6GylK-4Me5Nllr-nJkry1h7yPlYrbVo1KBVA6gT88j9yJuWhr7OWfW0-2LbQlHEwYvhr9Df0b6Yr1noqOV7Wb7sO8yvqSi9S5oCqVbsFPqRr8Pz7H41m7qcVKM9sTUlN82F5AFMI-jk6gqu3zcvJPdXcQNmLVn7nVXIItfPfvr0wyGCKHECq--d5bhBjL-1ARUv4rz8A0FgsINqTyz25JqHwQ_YA

Returned when the method called on the resource is different than defined

409 Conflict

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkNvbmZsaWN0Iiwic3RhdHVzIjo0MDksImRldGFpbCI6IkN1cnJlbmN5IGZyb20gcGF5bWVudERhdGEudG90YWxBbW91bnQgaXMgZGlmZmVyZW50IHRoYW4gdGhlIGN1cnJlbmN5IGZyb20gcHJvZHVjdHMifQ.I9UnyltseJc-47VPDzwrRQ-i1rL1Y_y6mNAI7BEOEgkQ2rH8cKGE1oTeNI0wqbVaTCXYiCE95wDVFHJz4UGbwZWthMpHEt6IGcPj-OrxDREDnRgTPfyIRkTLIbud8BSHaQvdpSgJBneGe5BSIRDeu0Mo9h9ATo0b5lltQq_R4bb9zpAni6xQ2oO-XI2blPx2A2OvHr89D96gdMVUa6pWI_HIzixDsUMTXbDwO0DlC6jCLMv81_v4VWZuUMQ9dmiP0PsnodOKLZkxKc03X5Ymnfz6nrMdqZKiWdBK7StwReucW38itcxWsiKyZ3oMYzFKYWUdWQNH3pGoghzBZcbGNg

Returned when business validation errors occur.

415 Unsupported Media Type

Response headers:

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IlVuc3VwcG9ydGVkIE1lZGlhIFR5cGUiLCJzdGF0dXMiOjQxNSwiZGV0YWlsIjoiQ29udGVudCB0eXBlICdhcHBsaWNhdGlvbi94LXd3dy1mb3JtLXVybGVuY29kZWQnIG5vdCBzdXBwb3J0ZWQifQ.Q7ri8IKmShewu9w2jNCZykGyP51lX-DoExwEbrcjwMjXrIwFRhiVNALRMySwULfoTOnIfk9fq7Je5Txuv-ftM-JSJ0Dif_rrRfcLigRUm0XBPzKLAl675uG4pRSvj5ZtJ9g98ti_zLbarSiYTjwouGqgKmsfz_K9ZwdNM8NCnB3X7G9z0CKchYRtFemprULYRYxBVymFr6on9mkeNsPc72q9TeQB0hXVmLTaNVGro_0yae7_avL0AOjKwY5AXrxCBRxuyhcYsSl_i2PJF5mGbitZFoPNidL16eL4xovVA-mMcuOKldEUpFilvAOCHrbCggAr3BQpauZVyiokRqi5Fw

The sent request body is of the wrong type.

500 Internal Server Error

Response headers:

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

HTTP/1.1 500 Internal Server Error
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkludGVybmFsIFNlcnZlciBFcnJvciIsInN0YXR1cyI6NTAwfQ.Lm349V3_rGQ-iW0YnARC6BZxhP8duh2NurOR_fyEtOp4EIc70PGupAr_A81gerc85ixEtS3Ux0DVZPxWIjbA8l9VyUk48fhpLPvC6hYk5b79fZ4YmHtkDdICpP0OT9YKeZhx3Htrhmn7BsP-cFLNudV_shod0GtGHa-ONBx56J4iV37EzQH4atThkusHiRW4p8NzuwRch9I-hnS26aR3KhDmiWQl0xsKDYrPnOu3-45vufpfl4qZ0gPDhsKGgsts9zVI1GONskf5-GJSLYLRstq39dxNGv_ZLRQ3IU1kxQHW4S1CmN8fbchxeA619WCh9NUdZOacu3jTXpBZlICX9w

An unexpected error occured.

503 Service Unavailable

Response headers:

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

HTTP/1.1 503 Service Unavailable
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IlNlcnZpY2UgVW5hdmFpbGFibGUiLCJzdGF0dXMiOjUwM30.C2_7xbFp0VJu141nO0fr5cUHKOipLic6XzY7_7Jqu0G8UkyjdCq4W8spggDsLIycfoDpzeJYuGkuIEJEK6Rh2phPiCBaphDHYmTYJPhy3lTPlxElIPya4Ml8WCr9Hf3-zec5NlOzCZDJRUcysjQOo4eI15LB--0YU2Fo4au7metxuZ83N71j0o-DJha083Em3VnmWNH4QE92983EUYPnEP0Y2jBjI-cEEZHgGe1ADzon7wrY60WIOKvvZ2WlDiWb_-cs6aLtLcNYAs5Fw1IB9L6OlCKuTmWM0OFwpeTvpQUCt1UGT4GGZw2rYBsgxsSvyUJOPdyskrFrIzmK7ypJsA

Service is not available.

API errors - business

Description of errors returned by Conotoxia Pay API, whose type is defined by the type key.

invalid-jws

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Response body:

{
    "type": "invalid-jws",
    "status": 400,
    "title": "Invalid JWS",
    "validation-errors": [
        {
            "message": "Header 'kid' is missing",
            "message-key": "KidHeaderMissing",
            "context-key": "jws"
        }
    ]
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiaW52YWxpZC1qd3MiLCJzdGF0dXMiOjQwMCwidGl0bGUiOiJJbnZhbGlkIEpXUyIsInZhbGlkYXRpb24tZXJyb3JzIjpbeyJtZXNzYWdlIjoiSGVhZGVyICdraWQnIGlzIG1pc3NpbmciLCJtZXNzYWdlLWtleSI6IktpZEhlYWRlck1pc3NpbmciLCJjb250ZXh0LWtleSI6Imp3cyJ9XX0.ZiOPshS9m_DC_ZqKC-PZ-1EdCKcMXTtkuBzhTuCMKRBBLEMZ2B2e5kWxA2b8MLHrGOVeHfbePqFBozf9jLnoP7b0l_zSUrVcaMBvODwQ_jKjBai1GRH6vRDS16NHSFfnup0HTu2mX5RWF21FfFpoO3DDOGx17ngKPSte_5j1O3t-iZGvmZoxG1VDH3WCXmp0dPBmuq23Orsda-1hNcvM2Olz9sFFK7jQDWA9H-Pf0Su1XJrC9QnQCeHojlQZ0MsGAv0lQc59Pl7qUYgNCu3hIT7DwHvdaQwR2DETroEJuV7n4b6SiP5TLHbi94C7kMEwCB-T9WtERTsTojD4id0jPg

Returned when the format of the JWS request is incorrect:

invalid-pem

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiaW52YWxpZC1wZW0iLCJzdGF0dXMiOjQwMCwidGl0bGUiOiJDYW4gbm90IHJlYWQgcHVibGljIGtleSBmcm9tIFBFTSIsImRldGFpbCI6IkNhbiBub3QgcmVhZCBwdWJsaWMga2V5IGZyb20gUEVNIn0.gD_vJFnDZOP3TyWrT7qZcTMlMMq4oExAsglE6gKwjmXdawHTYSatavxBW3Xw6P5w8JPCtyS_JtERg5gLPfrZiu3wfgxC27cLN33kIyfT4HH4OpuNTSpQyhmf7zYksIfXSsUFsFLX_FbFK9-hLbH8iUj6ryJOUj4hXHxSAUPtl45z5yqRyWADC_wQDmYzuoSW_ULzTEBYnQkt63950AODXtJHxDskaMIYFfzKoWIPiSRDdluPfTALua4iN8rKqNL9RSaMHx0UKX3wTJk1qaQDicpVkXvTydpgX5hnXwaPsd38lSSyMh1CR0Vn5aZmLssO21kwKhuyacmHOwU6imljdQ

Returned when the sent public key is incorrect.

invalid-public-key

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiaW52YWxpZC1wdWJsaWMta2V5Iiwic3RhdHVzIjo0MDAsInRpdGxlIjoiSW52YWxpZCBwdWJsaWMga2V5IiwiZGV0YWlsIjoiSW52YWxpZCBwdWJsaWMga2V5In0.SIWrgXX6OuvFsjH-10ON59jO1X6SJrBKzyyJj0Qp_sN4tkHn2kP8PXKvIBJkxwyfAKvTtOinq5PwivEHP8oyVm_JpMUtgkGRHGzU91LGzn-SnbqT5oydzfBwQWgHevvgZ3bGeSo72F2L3Ahaq0UmtID9G-mx8otoW6iU2JArhV-0LfZn1bwzxJydiLie7AFBMi4ekJ6ksewL5RPZRgPEs_BR-sPapbym4eL51vr70n8Vbe3O_PJcEbrYml0yx4BXqdDI_0NDsU7JoV6aekOyoU_9s0PjRqtKqa-Oz5C-wyXwtr-4mIy23AtEZMi8AS0loWnoFpPbX7T4E6PM1PMC2A

Returned when adding a new public key, the key will be incorrect.

sample-text-signature-not-match

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoic2FtcGxlLXRleHQtc2lnbmF0dXJlLW5vdC1tYXRjaCIsInN0YXR1cyI6NDAwLCJ0aXRsZSI6IlNhbXBsZSB0ZXh0IHNpZ25hdHVyZSBub3QgbWF0Y2giLCJkZXRhaWwiOiJTYW1wbGUgZGVjb2RlZCB0ZXh0IG11c3QgaGF2ZSBzaWduZWQgd2l0aCBTSEEtMjU2IHNpZ25hdHVyZSJ9.aBsf1MOmQc4eadXoaBQG7Pj2klmwNUfC1CFbBYc_1-krZOIXhBBff6lLa9ozDEqQeVh1CEnNPQ_ZxQzsfNYK4-wUIiE1F1ar1B29YQdb7YFqw9vAct3t8Tc5SfMO7LrbkpG6gSI1ox6tUFL9g6atwOwZF33kkPME4n5pKyxbBL2fK5hElcOqITJrmJnMxmZAOYPkgoj_dwtuK7PDREKO_E9YdXF8GBibCJnTJFnovXdfLIYfM4NS3pSgWUHFysLZS9Y4RxLJff9rGfXhX0i3KjxbLFhHgn_tBrKfgfCd7ysAb2aTMqAba15ULNPBNjRG8k4B-zpKGbVRRlSF5BFDhg

Returned when adding a new public key, an example message in the encodedText field was signed with a different signature than SHA-256.

validation-error

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoidmFsaWRhdGlvbi1lcnJvciIsInN0YXR1cyI6NDAwLCJ0aXRsZSI6IlJlcXVlc3QgcGFyYW1ldGVycyBhcmUgbm90IHZhbGlkIiwiZGV0YWlsIjoiUHJvcGVydHkgJ2NhdGVnb3J5MScgd2l0aCB2YWx1ZSAnRV9DT01NRVJDRScgaXMgdW5rbm93biBmb3Igb2JqZWN0ICdQYXltZW50RGF0YSciLCJ2YWxpZGF0aW9uLWVycm9ycyI6W3sibWVzc2FnZS1rZXkiOiJ1bmtub3duLXByb3BlcnR5IiwiY29udGV4dC1rZXkiOiJjYXRlZ29yeTEiLCJtZXNzYWdlIjoiVW5zdXBwb3J0ZWQgJ2NhdGVnb3J5MScgcHJvcGVydHkifV19.FR68VXiW-UunA7ttQgb02acaB2Klk1nP6aTTstQ2ojJALbQZac7HcJdzhee0W7s3sUTIE-aUFz2mtaIQVtNX-wXGTZ_fBoORb8MGZiddeQAcq2AnCW1O8KX5R2hZzoj_25HzF3CLHHHOGKBHLPbVw0YIqMoCIXLJuNyP63zvLg8rJNUirnD-_Th_yiH4izEWZwsAlQlMW6AECIYfxjg7KEZHEdirtg5wzUZTFLHMIaO3PiJCcFxDx2kuSzGH7QhUv2YfRttsERmZWTTI-MEfmihyqNe_AWR9Eq6Pd4Pcg1sjwSNcpBkeRATg0P-GC63KoZADSi9e7pv5vJQSGKbpjw

Returned when specified request parameters are incorrect.

payment-not-found

Response headers:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

HTTP/1.1 404 Not Found
Content-Type: application/jose+json

Response body:

{
    "type": "payment-not-found",
    "title": "Payment not found",
    "status": 404,
    "detail": "Payment identified by myGr2rDrbreYhLwTxmZes1J6qTqXcVZsSeMB3elwovvscmnChm token not found"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicGF5bWVudC1ub3QtZm91bmQiLCJ0aXRsZSI6IlBheW1lbnQgbm90IGZvdW5kIiwic3RhdHVzIjo0MDQsImRldGFpbCI6IlBheW1lbnQgaWRlbnRpZmllZCBieSBteUdyMnJEcmJyZVloTHdUeG1aZXMxSjZxVHFYY1Zac1NlTUIzZWx3b3Z2c2NtbkNobSB0b2tlbiBub3QgZm91bmQifQ.TxMbv4nbfWRX5LrWOBCpTU7tHm-r5Hk2nzYL9MONAcPCPfYuO9MTr0dqdmCGy6W0fso7Ka_KFgFUDI5IMD6K_cu0fmQEfHsfXWrMTjENWbDmBS5varbrKtwRpjkHcND--Jegsgo5l6ToHC9beqY-DZn0hVg8dzAPS2y4J0e1UwEtUcAOQsCIM1ASrK-t0oO-j9Oi4K6-a1yEU9m_GmAIVV7hSG2xOmGQUwn6ATdPSRWn83mbnJbOqPESsn4Mqye4IM53i7aKgw5tOKvez3NgCJ20sQHraHAndfqoSc4vpRHqcGEvRcuMnknv2qaXvSvosERPxWocvH_YajqGj5C7CQ

The payment identifier is invalid.

payment-expired

Response headers:

HTTP/1.1 410 Gone
Content-Type: application/problem+json

HTTP/1.1 410 Gone
Content-Type: application/jose+json

Response body:

{
    "type": "payment-expired",
    "title": "Payment expired",
    "status": 410,
    "detail": "Payment with identifier PAY715037422182587 expired"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicGF5bWVudC1leHBpcmVkIiwidGl0bGUiOiJQYXltZW50IGV4cGlyZWQiLCJzdGF0dXMiOjQxMCwiZGV0YWlsIjoiUGF5bWVudCB3aXRoIGlkZW50aWZpZXIgUEFZNzE1MDM3NDIyMTgyNTg3IGV4cGlyZWQifQ.GCuNAcmY907pl4Q1ge629UencSPpTxrw_vDFnqwhhgJo46cuvX6YicEyrq5rtC-OBOvkb3S9ZKjFqerXRTFaMbJPKm6ip-1Xjqjc90xizFSu1hSNuJWSD9JrhqXyrKZWz9QHvHb5mQZW5tDItior_DekOtQzZzBSBEd1b403UG8aHHNbunlbwTM6IoXQbX8o1qXHfRqqqgKGumw1b6zprI1xG2rFD6CUMUAzhu6SGyk_8nx3euKG_EosVr-TQ_m42r9s6F1zL9l9l-TouHqe1Y0PkM1WZqmWnjtZZ7P0KfQf3mm6pNIBEYK_F2370lGNgSJe7RYsIxpRxr03VOy4SA

The payment token has expired or the payment has already been confirmed.

point-of-sale-not-found

Response headers:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

HTTP/1.1 404 Not Found
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicG9pbnQtb2Ytc2FsZS1ub3QtZm91bmQiLCJ0aXRsZSI6IlBvaW50IG9mIHNhbGUgbm90IGZvdW5kIiwic3RhdHVzIjo0MDQsImRldGFpbCI6IlBvaW50IG9mIHNhbGUgd2l0aCBpZGVudGlmaWVyIFBPUzQ1ODk2MzIxNDU4OTY1OCBub3QgZm91bmQifQ.edVVxd62DAqXQp55GKTGQx1hIZQXvUhYBVVe_ADlruRnGKCPUDvu-LN3yit5QCuqauYN82Q4e60hiI3ImUxxIFboI56l4hf4r0hmgMSzljfbvpCHvtdfAAAPuf2NQgRtN8Ftxmnr2I21-OSiGv1pNjl0iT_FkkULws2MJKWZvPcWgFiEXiwPPcK9IIaIEVc-Wi-RnH1vYUzzC-EDXVexDUWOZ9wxon4pwKVj-drUC2jVDYmsUOm60uqFKMacIL_VozqlZni-InD-oZxbB4ZmwZm7qY0FMBjx7lhxv0NsRxvN7SXjqOOCoUKL-ZsL8t6wdBK056ymq13sFzdMtuv0iQ

The point of sale identifier is incorrect.

store-not-found

Response headers:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

HTTP/1.1 404 Not Found
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoic3RvcmUtbm90LWZvdW5kIiwidGl0bGUiOiJTdG9yZSBub3QgZm91bmQiLCJzdGF0dXMiOjQwNCwiZGV0YWlsIjoiU3RvcmUgd2l0aCBpZGVudGlmaWVyIFNUUjQ1ODk2MzEyNTY5ODc0NSBub3QgZm91bmQifQ.OPcCLDrHeWZmNRc5jbY0AW1vOrcuPWN4JHFOkJ_12pydWYlgQV4FWUkmvVIjSlGsIbUm1lcEUm2U0dKRNAYMwJStRLnG-UJkEOCogeHuPavElP0fg0tHbk-hxtxSaqqHndekjwni01aTwYepxG52OyPTJTDuUCVXASZy7LVl2zrzFIhZalnfbHBEDNrcsD0faMShmcSuB78ekIQwRYQpGguO_WhNd0E2gv6Txjh5QnpnE-FxHo4D14pZzF7HR5j1WZOBcaRj9qvPdtLhbbTqHicBfAmFnRC9uHEMjVSiRf3rJuzckvhjjz3lLoaC0XezZye7yP7-Lv2VGFxAU6WuGQ

The identifier of the shop linked to the point of sale is incorrect.

public-key-already-revoked

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "public-key-already-revoked",
    "title": "Public key already revoked",
    "status": 409,
    "detail": "Client public key with kid lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ already revoked"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1hbHJlYWR5LXJldm9rZWQiLCJ0aXRsZSI6IlB1YmxpYyBrZXkgYWxyZWFkeSByZXZva2VkIiwic3RhdHVzIjo0MDksImRldGFpbCI6IkNsaWVudCBwdWJsaWMga2V5IHdpdGgga2lkIGxwU29lblVTc3l4UHRabGtQM3RHTEg5aVBMWm4xTDR6ZjBHOWpVaFgzelEgYWxyZWFkeSByZXZva2VkIn0.b8ynD7Vp2ShxJf6O2LAgat5JhEa-mdk7t0bHxCnWCG2RBkdo2LGPjogKWk850X9RBAHzCISOHgOiRu8zOKJKd5DlblgJeYSWhvpYXnt2H0vNUXkMst10MaWm06K0KUAVHATrK9FR0aloqPqcTSeklLjyGrNu4sRG3G_dJWNYH_s_IUCwUH7fAK050sGwCxyybNHQ0rZ0O3sozxpMZaaF0tYc7nLgr6ZiyDeFIdd9eC6SyFGNcuzEFG1c4G9ZiYjiBwRMAwu75dmyN-cRM2nJvHMNJ16CK8C4fOcPwY2ZXrjutdBejDAjhiRuGcXXFcEA1ydAdX8oOhpJTKGw-21Y-A

Returned when the key used for verification has been revoked.

public-key-is-not-activated

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "public-key-is-not-activated",
    "title": "Public key is not activated",
    "status": 409,
    "detail": "Client public key with kid lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ is not activated"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1pcy1ub3QtYWN0aXZhdGVkIiwidGl0bGUiOiJQdWJsaWMga2V5IGFscmVhZHkgaXMgbm90IGFjdGl2YXRlZCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJDbGllbnQgcHVibGljIGtleSB3aXRoIGtpZCBscFNvZW5VU3N5eFB0WmxrUDN0R0xIOWlQTFpuMUw0emYwRzlqVWhYM3pRIGlzIG5vdCBhY3RpdmF0ZWQifQ.Mb_Naf5LCuvvUpEmCU1nt4sCT9KFnPZcwl3Zq1fnT0Zu0vOOqyOGhAiYA69VxwkhZ170FHA3L6a_56qNx4sNjL9V2oIVs4zLg0HI6jjrqZUWdGEPUgQO3Iq35J1f_afKi4GVaSw3-q0L9eIGyBcumTB1948IR0pNzAGtuR_8ep7wO536lJLJwJod9auS-XEtHba4d0zxiGHy-bqLTZKSOH_xwqWHpUSN3ZI0pD2fiz9HT8rv4_tsE0du-O79ykVdFnG-kWiNowC5ZNBG6wdNRBDAWW2-RHmXVsPaanPEcZ5zhfM9Q7Rw-zDH_21hQ4XSwtf32xu15Y5Ipa03bB_37g

Returned when the key used for verification is not activated.

contract-category-not-supported

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiY29udHJhY3QtY2F0ZWdvcnktbm90LXN1cHBvcnRlZCIsInRpdGxlIjoiQ2F0ZWdvcnkgbm90IHN1cHBvcnRlZCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJQYXJ0bmVyIGNvbnRyYWN0IG5vdCBzdXBwb3J0IEVfQ09NTUVSQ0UgY2F0ZWdvcnkifQ.VlRf2_U17qrfbwmPX2G3c6PvPzrwjChhHbGKl4DTBywtlNJhQnV7WkGGI1KG_uKU8h3m3RAj0pXX7tWSo58Wyv0fCZJEmtRL8mOQTCXfMfFPEVqXIr5krTbHfJIA7cgE0X2ucknvRFBMdtrJC70wcxR_wbAgi4UnDBItgS0YT5vmVfrAgbBDj6_NLJ9vhupZ4G4aav7BwV3MG9sI1g1CIpR2k1x1z9p29T6MO27yUXejKp1vCxACy6kWF1F947uabpDpkgqUnW08hem3cfIoO7ZofIXlyXGKIcQAIhluTm46AgIEgcW9p7GCnN9xLNFgC-91iMQNJ78KZ1RfLvpwyw

The category specified in the payment order is different from that defined in the contract.

payment-method-not-available

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "payment-method-not-available",
    "title": "Payment method is not available",
    "status": 409,
    "detail": "Payment method ANY is not available"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicGF5bWVudC1tZXRob2Qtbm90LWF2YWlsYWJsZSIsInRpdGxlIjoiUGF5bWVudCBtZXRob2QgaXMgbm90IGF2YWlsYWJsZSIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJQYXltZW50IG1ldGhvZCBBTlkgaXMgbm90IGF2YWlsYWJsZSJ9.fckM8zBoxoFQkEV-6tl9U_2WaEwB8J-lEm1JvQUIsIOoianhyFiAdROgpCMNj1J4BP4i1BvgiRbQzPLIk83gZAIh5e5CRazC_ThzzzKDa-cgCRuZiAyJVDGcOiq9z94MJjYW0YPNnZaPvQ0cTw67M5csPtJrG2KUXgCopHXHLcW_C16nFRUm22clr4OXzTX0yUr8qUY3H4FdFI9q6LkzsnugwJzYRkkiBCMM-zrFdYcCTzGLQQjejeUT0QEaVSIAx2-IGyk2f--UGYn4hCp6pbIJDa-NDlwZzDFJK53_foiQk7acnsW3djd1HTjP4nY4SjiYJnG3GJmKtZNCNBIG_Q

The selected payment method is not available.

transaction-below-limit

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "transaction-below-limit",
    "title": "Transaction below limit",
    "status": 409,
    "detail": "The 0.01 EUR transaction is below the 1.00 EUR limit",
    "limitType": "CURRENCY",
    "money": {
        "value": 0.01,
        "currency": "EUR"
    },
    "limit": {
        "value": 1.00,
        "currency": "EUR"
    }
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoidHJhbnNhY3Rpb24tYmVsb3ctbGltaXQiLCJ0aXRsZSI6IlRyYW5zYWN0aW9uIGJlbG93IGxpbWl0Iiwic3RhdHVzIjo0MDksImRldGFpbCI6IlRoZSAwLjAxIEVVUiB0cmFuc2FjdGlvbiBpcyBiZWxvdyB0aGUgMS4wMCBFVVIgbGltaXQiLCJsaW1pdFR5cGUiOiJDVVJSRU5DWSIsIm1vbmV5Ijp7InZhbHVlIjowLjAxLCJjdXJyZW5jeSI6IkVVUiJ9LCJsaW1pdCI6eyJ2YWx1ZSI6MS4wLCJjdXJyZW5jeSI6IkVVUiJ9fQ.YHIf3PxPqdUlrCh68ycOTgaw01q5jbVfIrlHtfQv_dLbQpEYpXZdqTd8PUB5nZYCuFzhU88aC7TW0kdsAdFrRCUMjxAx5Gas2p2YtL4QGONdpUV-bi8jtOvk9zMnzZY5_j-fPZ4pkUYX3vTdFOJh2-S5CB8dYj0M4behdTwABxzwuVDpw2OMUiVXGA4QDfL-GBSOr3arEnCwqcbAhoq_ocszrP1rozALocGy7Q7Z2J8sP-I9DJEe2JDfslUo4R9SMqBNDYmXW_48FVK9XFWi5TliyIFGa-vnzxW6MvLtV-iRtFYsNZpMydkCRJs3Giw42PFvAZN-OpiEKdL2q1hKgg

The transaction amount is below the limit.

Possible limitType field values:

Value Description
CURRENCY The indicated payment amount is below the defined value for a given currency.
COMMISSION For the selected payment method, the fees exceed the transaction amount.

transaction-above-limit

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "transaction-above-limit",
    "title": "Transaction above limit",
    "status": 409,
    "detail": "The 250000.00 EUR transaction exceeded the 200000.00 EUR limit",
    "limitType": "PAYMENT_METHOD",
    "money": {
        "value": 250000.00,
        "currency": "EUR"
    },
    "limit": {
        "value": 200000.00,
        "currency": "EUR"
    }
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoidHJhbnNhY3Rpb24tYWJvdmUtbGltaXQiLCJ0aXRsZSI6IlRyYW5zYWN0aW9uIGFib3ZlIGxpbWl0Iiwic3RhdHVzIjo0MDksImRldGFpbCI6IlRoZSAyNTAwMDAuMDAgRVVSIHRyYW5zYWN0aW9uIGV4Y2VlZGVkIHRoZSAyMDAwMDAuMDAgRVVSIGxpbWl0IiwibGltaXRUeXBlIjoiUEFZTUVOVF9NRVRIT0QiLCJtb25leSI6eyJ2YWx1ZSI6MjUwMDAwLjAsImN1cnJlbmN5IjoiRVVSIn0sImxpbWl0Ijp7InZhbHVlIjoyMDAwMDAuMCwiY3VycmVuY3kiOiJFVVIifX0.dhQxLLsPdU2OLLaeC46wpk2FzG3pcSj1_WOLWqQxrvQqzSYv85k0Vu4u2KVxxuO6cnnDT-J73w1Z9yeocDV2Ic90RvKVlQDG9GGn0cfpoC4LrqWB8OfDXDbFxNyfEWnIx7T_7-qWrS_kF9ZdxkTPHenzU2rFK-L_Gf_ez973BWCPd2ewGtnTgpFldziwGWce54N1so-f6crsR4nY_4z0SztK-Blu9L6sBWLSlNw0HXc_Fu8pCW_ADAadAysuxvRlR2w7c2NdxeLz9qOB2E2T_pB1piEchHs456_q2oKR-lzYEUoBBgNt0Lk4giWSA8tAvBK44BoT3Jn2OOQBy5tELw

The transaction amount is above the limit.

Possible limitType field values:

Value Description
PAYMENT_METHOD The limit applies to the selected payment method.
POINT_OF_SALE The limit applies to the point of sale.

payment-not-booked

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicGF5bWVudC1ub3QtYm9va2VkIiwidGl0bGUiOiJQYXltZW50IG5vdCBib29rZWQiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiUGF5bWVudCBpcyBub3QgYm9va2VkIn0.LqDfgQMgiwvtqYRCw2Da_hBIWo9V1yyOH6Sqg7FnTktBQjFSNuHteB9xTA3f6skspzTQRcKCk1wPSZb-3TgOMOJ6L2B-1Lpzz0pzOkrwSShnHaaRfL60pttYVM_H919I3wm5VVrhTLRZ8GrxWp-lHENNt-QJ4FLXkTADBEjQ02mo10hAsuUkhmp9x6fTJ-dRct2Z3GwGEO16otiNQ-uUpg2CJz3frynoCwy6yLsdagKpQUpW1mD-nmjjDCpO8ngAEgxTJx-htDRUqqY5w86u8dz1XfPGaCivfr2J6gqYAfQYx9zFGqnjWSNNmH5Lxg0XCLFkK72F_cimS7lzex9tpQ

The payment for which the refund is made is not booked.

point-of-sale-forbidden-error-url

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicG9pbnQtb2Ytc2FsZS1mb3JiaWRkZW4tZXJyb3ItdXJsIiwidGl0bGUiOiJGb3JiaWRkZW4gZXJyb3IgdXJsIiwic3RhdHVzIjo0MDksImRldGFpbCI6IkVycm9yIHVybCBpcyBub3QgYWxsb3dlZCBpbiBwb2ludCBvZiBzYWxlIHdpdGggaWRlbnRpZmllciBQT1M0NDQ3ODUxMjU2MzI1NjkifQ.V5tMxdvMW1StIcEx0MK9WWl-mT4AOetKNSAdwuRFnErjrFF5mX1iDsJvSAEogKF_LPO5LIn6ANRzzms1EvmwOqAxyp6BAnln4fI6oYf8Je1sZoooL0cvGYn3PIp_cBbSqr8bRLfnVwsywEwBagb_WCL8_azwJbQF6UUQ8SpA8L-0wAwzlFbrU_27-OA46YPhArc3zm4HDKzWBGVjtffFCCakTSDCqTqiKiEMy6B4-6wLpo_-N7ov8o3hmy6ZWiDI9lNGKgYH2_EluNx08Iv8w_qqfSaGHQJCBJOqXgAWToCTWSMaWKp7XCTn-8_w_IAvmZBQv3XKqNR6sXysF8fKug

The given url used for redirecting the customer has not been defined in the point of sale.

point-of-sale-forbidden-notification-url

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicG9pbnQtb2Ytc2FsZS1mb3JiaWRkZW4tbm90aWZpY2F0aW9uLXVybCIsInRpdGxlIjoiRm9yYmlkZGVuIG5vdGlmaWNhdGlvbiB1cmwiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiTm90aWZpY2F0aW9uIHVybCBpcyBub3QgYWxsb3dlZCBpbiBwb2ludCBvZiBzYWxlIHdpdGggaWRlbnRpZmllciBQT1M0NTg5NjMyMTU2OTc1ODkifQ.W2LwMY38GsUYk1bgwOfaerd3rNk23__NDrLtcOhvw0crs7beC2ZC9uWj7kiKNwfhe87lr8eWpfoDU6Y1Fx9KBqBo5k702Vjo9FbRg4NkssKoefkeFcS0ZVA_OpfOdWS_7aalqfvnzJVgNKuyIme6PfCHVfGjYUNjrablAHSSY366HoQE6wciqbZwKSmqTcXnCV-wmNKhSZxsUbyD8ehKxQQF8wxVB0ahumCN_My9V93_QA5LhBoVOsEjxg2MhS0XMa4YF2586TurPr--Pul9Iv_sLaqkhkYcTimFlcMS59aPsrcgNlBLtHiXZ5TNnQNVDeglfW-F-pnhny51WzL3bw

The given url for receiving notifications has not been defined in the point of sale.

point-of-sale-forbidden-return-url

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicG9pbnQtb2Ytc2FsZS1mb3JiaWRkZW4tcmV0dXJuLXVybCIsInRpdGxlIjoiRm9yYmlkZGVuIHJldHVybiB1cmwiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiUmV0dXJuIHVybCBpcyBub3QgYWxsb3dlZCBpbiBwb2ludCBvZiBzYWxlIHdpdGggaWRlbnRpZmllciBQT1M0NDQ3ODUxMjU2MzI1NjkifQ.VcazGlGDpKZe08L_tb0vR3agEggUm_SrJb2L_JJMvVt0ogL7aAxo74VYFakwrXDeMLorgQf--99kwYL5_VEEn0aPmlf6gDdKCaF7pZ7Kv3RRyVlkglUaOpE4sIca0QaYROJ8oetq1npbPyFclYSRUhsBdy5Ns42L3tARxfQvkzKgntDmsWLwZPcJqrE0-G1Yt3YEtAYbyW2pZWK1SVGbM2xraRoBECb9o4_NLiEez7nTryp1J_iwgihmj0FvTHF7GEjlmn19BWWTV_x8BUSZGHCtEyzdQnJXmPjXOEs7vv_A_SkJ1cZxXk5a6Tp8G6xao52CAf-Xc_4avjIbB88zfg

The given url used for redirecting the customer has not been defined in the point of sale.

point-of-sale-not-active

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicG9pbnQtb2Ytc2FsZS1ub3QtYWN0aXZlIiwidGl0bGUiOiJQb2ludCBvZiBzYWxlIG5vdCBhY3RpdmUiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiUG9pbnQgb2Ygc2FsZSB3aXRoIGlkZW50aWZpZXIgUE9TNDU4OTYzMjE0NTg5NjU4IGlzIG5vdCBhY3RpdmUifQ.D5QoiTItOt_TePiGbq-f0a-30pWm4Fhyr9ZSxWgj60skXri_NxcmP2AbwwHd-YO4i8LQGyzqrKUnGrCUlU2tJVfYGJCt_LCvkwa_TwnQ66O4Bsua1AaaIYzqlMxcCOGDusof4BRc6EvIXlQR6MmfbiBYWBlNhH1OipxmmJv0ToWXfvJXhgAHfMuGbbm_wzGYysDJNJpv8kg3KEyrd5cR9ocJpapHMYfAXu-HPLi60XlAQdRjeAoxypZcmFT5USUu26fjrB9rwC23EMeaiJVcaHt655c8xG6io2VB98l8pnRxu_ISbz1YlZMpHxXS_3dLAYSu1xwgI5EWM-2mVBHjXw

The point of sale is inactive.

refund-amount-too-large

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicmVmdW5kLWFtb3VudC10b28tbGFyZ2UiLCJ0aXRsZSI6IlJlZnVuZCBhbW91bnQgdG9vIGxhcmdlIiwic3RhdHVzIjo0MDksImRldGFpbCI6IlJlZnVuZCBhbW91bnQgKG9yIHN1bSBvZiB0aGUgYWxsIHBhcnRpYWwgcmVmdW5kcyBhbW91bnQpIGlzIGhpZ2hlciB0aGFuIHBheW1lbnQgYW1vdW50In0.Y0LeMGM7_gh_SgX6jEW3UhWkKqYAAGXcpaF9IuzSCAjCcSZhyA2AQ88tZ0JJkQMnynENyvQ7AdNE4_TzrJOQC21YnfXHjYzTkGwHT6BoYdTIPWfN6Tzr55cjcXEFfEXNprV0NFGu-C6JjLDRmpdtkfZZgrilhsh5UpSFe5JsXcBWIAv1qGLKC3vBNETW4DQmOuNIxzJ5h4C6Q4bxQKV2RbVtOIT8OoB11AAu2CExBiHURDx-JJOscAyHBQdprEiyAU7sZDaQk-n5coCxXY8fjn6J1j_F3qP__AZ4Bl8UmOjfw8JDhtrpAUvqj1PqL78wLPv5NryOUdzERBtImq4jaA

The refund amount exceeds the payment amount. In the case of partial refunds, the sum of all partial refunds exceeds the amount of payment.

refund-incorrect-currency-code

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicmVmdW5kLWluY29ycmVjdC1jdXJyZW5jeS1jb2RlIiwidGl0bGUiOiJJbmNvcnJlY3QgcmVmdW5kIGN1cnJlbmN5IGNvZGUiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiUmVmdW5kIGN1cnJlbmN5IGNvZGUgbm90IG1hdGNoIHdpdGggcGF5bWVudCBjdXJyZW5jeSBjb2RlIn0.CnZIXPicq85DcmHtXFFzAqkmdw1bg6CmRVHTrkD5ui4mrs82ncjchy4p5CALffpFLFfetMhddAcp6gpnxsWmPjyRTRAHoCk4-_PbZwdE6Nw1nH4lyeFqBHtx0XrA4HVnPHn3EyEIexJ74b2vq-vwJAHI2rODu_IMA9Wegn7efYhnyZtBCCflviLgimv1I8j5J2vomyHjHiOms4GEcV78zKndS3qnG_xBSklPfYcY7rv4zbnHtuZP4l1nL9FZ0DFIMu9oSwJEZRUimrHtP4gFTrJ2_Js0apUqLUTNPXw4tIfdlyFF4fxqjjuJOfzv6omq2Putp13o4Xn-BKaXT-SuuQ

The currency of the refund is different from the currency in which the payment was made.

max-refunds-reached

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "max-refunds-reached",
    "title": "The maximum number of refunds for payment has been reached",
    "status": 409,
    "detail": "The maximum number of refunds for payment with identifier PAY445458962445154 has been reached"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoibWF4LXJlZnVuZHMtcmVhY2hlZCIsInRpdGxlIjoiVGhlIG1heGltdW0gbnVtYmVyIG9mIHJlZnVuZHMgZm9yIHBheW1lbnQgaGFzIGJlZW4gcmVhY2hlZCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJUaGUgbWF4aW11bSBudW1iZXIgb2YgcmVmdW5kcyBmb3IgcGF5bWVudCB3aXRoIGlkZW50aWZpZXIgUEFZNDQ1NDU4OTYyNDQ1MTU0IGhhcyBiZWVuIHJlYWNoZWQifQ.CG5b7j1H1NtjZTmJ17IEyzLBnHaePOUKiaTdwfZUYqIrhLObogufRc6Pz8xXh0VACZp4CLSsxneRaEPsCgc9eyjKHp-u-rh9FbSBrMM7QUd6uyS7-AUvuD_FDTSAt3Xd_JBFo0pEUJ4AqeQ7CZDoTOo_nYZT76CY56Q2iHl5gv49HnpdyBr_oq6aAHavqXArF7nst9P9k1ZqZGJJTwkGJ6Hz1FN2xGM8BWiDqwjBik4cSIahMigdA1zfpgrCL0jDPlzNfIvlqeAY1AVXIkCiu4DdueuUegTXSf-HP3VePhJ9nnUJB7QZAUpGUxB_Jq1XHUnWsrW8hQi6ju-nuEvKIg

The maximum number of refunds for payment has been reached.

other-refunds-not-completed

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "other-refunds-not-completed",
    "title": "Not all refunds are completed for payment",
    "status": 409,
    "detail": "Not all refunds are completed for payment with identifier PAY382793112712843"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoib3RoZXItcmVmdW5kcy1ub3QtY29tcGxldGVkIiwidGl0bGUiOiJOb3QgYWxsIHJlZnVuZHMgYXJlIGNvbXBsZXRlZCBmb3IgcGF5bWVudCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJOb3QgYWxsIHJlZnVuZHMgYXJlIGNvbXBsZXRlZCBmb3IgcGF5bWVudCB3aXRoIGlkZW50aWZpZXIgUEFZMzgyNzkzMTEyNzEyODQzIn0.TC6S889u1aD8EHvMQxuMfp6_7ZuU1YfSeB5zdamuH91EHUmLdkohjHa6CYxxtFDAyTrjsuujg9Uxm-2oFuDqoTw4DyfBEMUtb0Znf9qlfSHuXJ_J6M92De6PoiEOdsRz22hR4K70l1R9dY_iZHbtFLhkL38NFJL5E3EmhrTvoapVG1QizuYgYOVXNXk1j6AHoYdXgvdPDl581qhJmFxnQkkKTcfQSoMjxuvREzbgXz5reAkWkQAUHQuIMOHUrhsk0WyV8tOy27DbSQ1-sK0FAZNuSe4fFZACWmbz1zFMRTy83Uuxl64OAluZXea04FG3thCwEpw0llPAXF-UmpUhYA

Other refunds are not completed for given payment.

sample-text-verification-failed

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoic2FtcGxlLXRleHQtdmVyaWZpY2F0aW9uLWZhaWxlZCIsInRpdGxlIjoiU2FtcGxlIHRleHQgdmVyaWZpY2F0aW9uIGZhaWxlZCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJTaWduZWQgdGV4dCBmcm9tIGVuY29kZWRUZXh0IG5vdCBlcXVhbHMgdG8gdW5zaWduZWQgdGV4dCBmcm9tIGRlY29kZWRUZXh0In0.bC1YhfaC5dukeaCFlsB-2SdllMsiOOkMCCjDpfauLthRu3RS-Ri_Lv0EH0D8dcE_Jr9Kaz9yUZlyTvs_Tbqy8clFRQLFvHB0TpOed4zt96ViY27Q9BLMmJS5HrlLSoAh4KG3I3ZkOKDQhyW1GJgFg98TKRox3bC9-xTpBedLkFOuVEbZsvQ7H2L5P3NU8nCbcvhguKCykcGkB_Misl5h7G_yrXk_vOZOKZSvFumUP-qjpBvSatXB7Sr7y-ca68RBu2smlPv8iDYwD61uPrrZZ5LOZvqUjJQEOBEzzCq4A2jTbQEZPeOVPvz4hdqYbCYlJysh5xNK2AnMZk2fzJ-bqw

Returned when the signed message in the encodedText field does not match the value given in decodedText.

public-key-has-wrong-length

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1oYXMtd3JvbmctbGVuZ3RoIiwidGl0bGUiOiJQdWJsaWMga2V5IGhhcyB3cm9uZyBieXRlcyBsZW5ndGgiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiQ2xpZW50IHB1YmxpYyBrZXkgbXVzdCBoYXZlIGEgbWluaW11bSBvZiAywqAwNDggYnl0ZXMifQ.Vn0oLx-dZFMNfAKuyPXNNOo8gy2L8_gYkb1TkBYitHkcvS_jnFBuOEbq7LX-ah16NDSKQVO_rm5TVNzAMUqqe5fusek2zV_R8rDccDHuHWlk217BVWvBr9C6_W4VjNqjtOExpf8r7W5ycnvMLomKwIb1h-2cJTzjpB2nMW-PGSgMot-N2lnlu5EuXMmZ0jZ2d2sDoAcI9y6yeRPPt6cmtZ-a_PxJ2LNG_BL1av8Sht8qR9o46j4cHInIVabN5CdehaD7YDqRGT6GdAMVE4vme1ZOoE4xqBIHpszFXoDwFITLByOWY84D1QWfqKDSDaKlF_i0dfF1f2G3uDnE8fCBUA

Returned when the added public key is under 2048 bytes.

public-key-already-exist

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "public-key-already-exist",
    "title": "Public key already exist",
    "status": 409,
    "detail": "Client public key with kid lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ already exist",
    "kid": "lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1hbHJlYWR5LWV4aXN0IiwidGl0bGUiOiJQdWJsaWMga2V5IGFscmVhZHkgZXhpc3QiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiQ2xpZW50IHB1YmxpYyBrZXkgd2l0aCBraWQgbHBTb2VuVVNzeXhQdFpsa1AzdEdMSDlpUExabjFMNHpmMEc5alVoWDN6USBhbHJlYWR5IGV4aXN0Iiwia2lkIjoibHBTb2VuVVNzeXhQdFpsa1AzdEdMSDlpUExabjFMNHpmMEc5alVoWDN6USJ9.QxoW3-rftVjDcNOtreF9ttRLUriMat_xJzpRvM3vPf08TZDK5RHdR6idUti18dKzX78hmmHS-PWXRwT9maCREqZBguqJfzFGwyBs5ui5jKi4V_SsX8-irb8EB-EhznyXQ5FidrF75_Vc69u9HythdIrnj3OimAnmALVKs8uDvZ-m-dED3Ua3-lE1sBIWExJ5R7bzNkuvpIRpzkt5vrEfqmnAYjVkL1ceUBCBgiqPqdi38CoIL0YQFUBlESUGYmXggXXYQcETVlftiieS1D1CJvTlIL5TRUTNXmt98-uvQsNcIkpYwyrtwqCrCkJr4TUh8AwX0dHwW7ThGKk8W9MooA

The given public key has already exist.

refund-money-below-minimal-amount

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "refund-money-below-minimal-amount",
    "title": "Refund money below minimal amount",
    "status": 409,
    "detail": "Refund money 0.01 PLN is below 1 PLN minimal amount for PLN currency",
    "limit": {
        "value": "1",
        "currency": "PLN"
    }
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicmVmdW5kLW1vbmV5LWJlbG93LW1pbmltYWwtYW1vdW50IiwidGl0bGUiOiJSZWZ1bmQgbW9uZXkgYmVsb3cgbWluaW1hbCBhbW91bnQiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiUmVmdW5kIG1vbmV5IDAuMDEgUExOIGlzIGJlbG93IDEgUExOIG1pbmltYWwgYW1vdW50IGZvciBQTE4gY3VycmVuY3kiLCJsaW1pdCI6eyJ2YWx1ZSI6IjEiLCJjdXJyZW5jeSI6IlBMTiJ9fQ.YE1dB6RJiXNu0t9gjKKEV4MaizlbSJm3Xo5VnZCOmKw4qy7LKEvmK2ggS21bTknzcUQA3n_jIqVzkoWfK52XXWUlINhWRWcmRnJ2Xukb280WYbg2xusBs1FGpdLAlrQ7nrbDVFZye7Q1Mhh8p_mh4r6-aWVe4vHpuj7lKQzYKAFa-aZ9AEnVw2PRXu1-jsbL4WcGhdnFYcTYLkO1jgg2WHes5zZNyKnPgf7mUVFpjN0rHl_gELzJL0JBjEw0MQw7txDb0qPr6kyfdN4lQfnJzY7vy3nWElTzyXL42n0C74QLV1oaKB0gJi0SZ4tyh4IxvjQjU90FD6Ib3kq0hxGjlQ

The refund value is below the minimum value.

refund-not-allowed

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "refund-not-allowed",
    "title": "Refund cannot be executed for selected payment method",
    "status": 409,
    "detail": "Refund cannot be executed for POLI payment method"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicmVmdW5kLW5vdC1hbGxvd2VkIiwidGl0bGUiOiJSZWZ1bmQgY2Fubm90IGJlIGV4ZWN1dGVkIGZvciBzZWxlY3RlZCBwYXltZW50IG1ldGhvZCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJSZWZ1bmQgY2Fubm90IGJlIGV4ZWN1dGVkIGZvciBQT0xJIHBheW1lbnQgbWV0aG9kIn0.GsJDGxE6ywoU5l9BRdXiIQu3iQC-WlqzEeRCK2WVkM_4FxSQAlt35DkcQhhUC07xt5hoW39Q1jjZx5iXb9TFIWlvqBmyXyru6b-G35zuugmJ7KB2h7rtnwapuPs6jcoHciuzEWDCeCRz75Ln9E217uFSa4RkPjZ2scyEI9YRh3bjORhv3P9CzZ2zrpqhzjRcAdq1x9z1YZrKw-5sPaHKHVLDhw3VewiR89QJ0G90xvkd96aBktupuXaEWr8xblXYozGW2Hon7qnNhapH9oU5FCsuq3DnebUtal75fxRbFxOt9Juq2LTkt2bMCgVHQHXsveWF40UAsaVGm_P0ePJRxA

Refund cannot be ordered for the selected payment method.

currency-unavailable

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Response body:

{
    "type": "currency-unavailable",
    "title": "Currency is unavailable",
    "status": 409,
    "detail": "Currency HRK is unavailable"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiY3VycmVuY3ktdW5hdmFpbGFibGUiLCJ0aXRsZSI6IkN1cnJlbmN5IGlzIHVuYXZhaWxhYmxlIiwic3RhdHVzIjo0MDksImRldGFpbCI6IkN1cnJlbmN5IEhSSyBpcyB1bmF2YWlsYWJsZSJ9.VmM7LCkFQYuLESlnrL1MHkPxkR3ogCKJQmjfVTlnMiv2mbISaAD7qeFeHW3iCxSbmRpMqt-EzAIUuTKWSmEVovI-h7ORv1DD1OWCQEUpIkhcXXkyjZwuZC2o759vpJbHQDhBHkHvWrnVbXR7U86UAmMkxg337gU1rhP9IGhe3DhAhGD4HEe3o9idL9X9qw7yAtP3YpzJ05NNMmkQ8mOmIhXXqEttFiPyeGtagd6rCDKxwq3T5yIIPUMyRBJePzPugbeXdbWySbbK_0bisUF7DeSC0j0m-_dKjBbnFTWrfiGPjDJKVRpqzqi9_ZrYnlIaghNhhNKBjhw6k2SfHuCiSg

The selected currency is unavailable.

Business processes

Payment process

The payment process is presented below. The scenario depicted only contains a positive case, which aims to present the logic of the whole process.

alt text

Preliminary requirements

The customer created, in the Merchant online store, a basket with a list of products to buy.

Scenario

  1. Customer has chosen the payment method provided by Merchant at the store's checkout, and then clicked the "Pay" button (Step 1).
  2. Merchant's server sends a PaymentData message to Conotoxia Pay server (Step 2).
  3. Conotoxia Pay server checks the correctness of the received message and creates a payment order (Step 3).
  4. Conotoxia Pay server sends a PaymentInfo response to Merchant's server (Step 4).
  5. Merchant's server saves the transaction status confirming acceptance of the order in Conotoxia Pay (Step 5.) and redirects customer to the address of approveUrl received in the PaymentInfo response (Step 6).
  6. The customer selects the payment method on the Conotoxia Pay website and clicks "pay" (Step 7).
  7. Conotoxia Pay server accepts the payment, which has been accepted by the customer for processing (Step 8).
  8. Conotoxia Pay server redirects to the Merchant's server - to the returnUrl address given at the time of setting up the payment order (usually to the page with "thanks for the purchase you have made") (Step 9).

After the payment is accepted for processing (Step 8), an asynchronous payment processing process is carried out:

  1. After completing the payment processing, the Conotoxia Pay server sends the PaymentStatus message with information about the transaction status (Step 11) to the Merchant's server at the notificationUrl address.
  2. Merchant's server saves the status of the completed transaction (Step 12) and sends the response code HTTP 200 OK, which means correct receipt of information about the transaction status (Step 13).
  3. Merchant's server accepts the completed payment transaction (Step 14).

Payment process - EPS

The payment process for the selected EPS payment method is presented below, where the Conotoxia Pay payment interface is omitted. The functionality of presenting a list of banks and selecting a bank by the user must be implemented on the Merchant server side. The scenario depicted only contains a positive case, which aims to present the logic of the whole process.

alt text

Payment life cycle

alt text

Refund process

Return of funds to the customer's wallet can be executed in two modes:

Refunds are always carried out in the currency in which the payment was made. For a full refund, the amount and currency are not required, but for a partial refund, the currency must correspond to the currency in which the payment was made.

In the case of partial refunds, the sum of all individual partial refunds may not exceed the total amount of the payment for which the refund is being made.

A refund equal to the payment amount is considered to be a full refund. If there is a partial refund for payment, it is not possible to make a full refund.

The presented scenario only shows a positive case for a full refund, showing the logic of the whole process.

alt text

Preliminary requirements

In the Conotoxia Pay system there is a booked payment for which the refund is to be made.

Scenario

  1. Partner's server sends a RefundData message to the Conotoxia Pay server (Step 1).
  2. Conotoxia Pay server creates a refund (Step 2).
  3. Conotoxia Pay server sends a RefundInfo response to the Partner (Step 3).
  4. Partner's server saves the information about the creation of the refund (Step 4).

Simultaneously with step 4, the refund process is carried out:

  1. After completing the processing of the refund, the Conotoxia Pay server sends a RefundStatus message with information about the refund status to the Partner's server to notificationUrl address (Step 5).
  2. The Partner's server saves the refund information (Step 6) and sends the HTTP 200 OK response code, which indicates that the refund status has been correctly received (Step 7).

Refund life cycle

alt text

PENDING status may occur in situations where the Partner's payment account does not contain enough funds to make a refund. Refunds are queued in such situations and await receipt of funds.

Security

The Conotoxia Pay system uses the following elements which ensure the security of communication with the Partner's system:

Message authenticity

The JSON Web Signature specification defines how messages can be signed. JWS is encoded using base64url and consists of three parts separated by dots (.). The structure of JWS is as follows:

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

Example of a minimum JWS header accepted by Conotoxia Pay:

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

Header

The first part is a header, which contains, among other things, information about the algorithm used to calculate the signature - the parameter "alg". The possible values which can be taken by the parameter "alg" are given in the table below:

Identifier Algorithm
RS256 SHA256withRSA
RS384 SHA384withRSA
RS512 SHA512withRSA

The minimal JWS header, in addition to the parameter "alg", must also contain the parameter "kid" identifying the public key that is used to verify the signature.

Payload

The second part of JWS is the so-called payload, which contains the message being sent. JWS specification does not define the type of sent message (it can be e.g. XML or String), but Conotoxia Pay requires that the message is sent in JSON format (UTF-8 encoding).

Signature

The third part of JWS is a digital signature, which is calculated using the algorithm given in the JWS header for a combined coded header and coded message, separated by a dot (.).

Communication with Conotoxia 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
  }
}

Example of a payment order:

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

data.jws
     eyJraWQiOiJERkRPbEI3RFU2LTBoUllBNVV1NEJiVEctcXJlY3NLdEJIU3kzVGppSXM4IiwiY3R5IjoiYXBwbGljYXRpb24vanNvbiIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.ew0KICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbiIsDQogICJleHRlcm5hbFBheW1lbnRJZCI6ICIzNDJISEg4OExLREo4OTg3Njc2NyIsDQogICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwNCiAgInBvaW50T2ZTYWxlSWQiOiAiUE9TNDU4OTYzMjE1OTY1NDc4NTkiLA0KICAidG90YWxBbW91bnQiOiB7DQogICAgImN1cnJlbmN5IjogIlVTRCIsDQogICAgInZhbHVlIjogMTkuOTkNCiAgfQ0KfQ.J2uDZEZL_hlgLAscv3EMX8lKCPBOf1X3UoUEDGhBF0cKFSAvHaDAAtnyzacL53RWsaHmAfDTRHqqFuF6g6wBRStbWukC1pOqXNEYHTXgfHJ01Sh7JZr7IRuX92ol-OgiP7DK01wDnlZ80_wGnJUpWGQjiQEoUzJhOcFyZ44_jSKh7dwU7SWh9wj5FWmC1A8RlBXLpMf6QWCKlA1njw4r7RXUmbLLbdiA71Oiy1LN_Ezf8srYP5y_QhhtoyXxkLEe75YP5ky6d0UObrKpUVbhvj7lwnqMzZVBfD1aIL5F2s8gUg8nQeCUWPUYIRvDNQkmAFTSbqjD2sCG1ysm8JDspA

Response headers:

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

Response body:

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

All messages sent from the Partner's system to the Conotoxia Pay system must be sent in JWS format. Only in case of adding a public key it is not necessary to sign the message.

Below is an example of JWS (Compact Serialized), which can be sent to Conotoxia Pay:

eyJraWQiOiJERkRPbEI3RFU2LTBoUllBNVV1NEJiVEctcXJlY3NLdEJIU3kzVGppSXM4IiwiY3R5IjoiYXBwbGljYXRpb24vanNvbiIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.ew0KICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbiIsDQogICJleHRlcm5hbFBheW1lbnRJZCI6ICIzNDJISEg4OExLREo4OTg3Njc2NyIsDQogICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwNCiAgInBvaW50T2ZTYWxlSWQiOiAiUE9TNDU4OTYzMjE1OTY1NDc4NTkiLA0KICAidG90YWxBbW91bnQiOiB7DQogICAgImN1cnJlbmN5IjogIlVTRCIsDQogICAgInZhbHVlIjogMTkuOTkNCiAgfQ0KfQ.J2uDZEZL_hlgLAscv3EMX8lKCPBOf1X3UoUEDGhBF0cKFSAvHaDAAtnyzacL53RWsaHmAfDTRHqqFuF6g6wBRStbWukC1pOqXNEYHTXgfHJ01Sh7JZr7IRuX92ol-OgiP7DK01wDnlZ80_wGnJUpWGQjiQEoUzJhOcFyZ44_jSKh7dwU7SWh9wj5FWmC1A8RlBXLpMf6QWCKlA1njw4r7RXUmbLLbdiA71Oiy1LN_Ezf8srYP5y_QhhtoyXxkLEe75YP5ky6d0UObrKpUVbhvj7lwnqMzZVBfD1aIL5F2s8gUg8nQeCUWPUYIRvDNQkmAFTSbqjD2sCG1ysm8JDspA

After decoding JWS, a JWS Header and JWS Payload containing the minimum PaymentData message are received. An asymmetric algorithm RSASSA-PKCS1-V1_5 with SHA-256 (RS256) is used for the signature. In order to verify the signature, a sample public key should be used:

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

To verify the response received from Conotoxia Pay you need to use a public key provided by the API GET /jwks.

Communication with the Partner

Example API response body:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk3MTUwMzc0MjIxODI1ODciLCJhcHByb3ZlVXJsIjoiaHR0cHM6Ly88Q09OT1RPWElBX0FQUFJPVkFMX0hPU1Q-L2FwcHJvdmUiLCJ0b2tlbiI6ImRHQmNFTVFveWZmNk9DUVk1bDFyZWhYQXdnQ0RuRXdodHA1NzNQMUVKeXN3R0JKNzlHIn0.KD3zD9f_xOuhVZXAMt3fyVpYlXx48rHLqNIEwGKAjHyd84_-j7oowPw8IIWZI3qdx33Z5woLMmyetH6SQpJJXjB4em826Ihg7JaZoQ0eAVez9CY0E83x51SpIwUIeKJ5I-m1-VT87dnP8yMwwD0TE212PTRjY3eNTVC3uTtu1vlYyL8fhfa3FvmjLqmCpHEEIHuJSBCsKH95mOhJlM-OgREtNX043RPyiCxl2p88lpMtOjoLYYwAIOYsVqqpylaey8xeY3kuseAIfxiPJzNIz0LJ9NdzDzWTcDUW-fVtNhG6sQXfulEazFd4qYbATimQ7Jf9Ld50LW5qHCsM-fCacA

Response headers

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

JWS Header

{
  "alg": "RS256",
  "typ": "JWT",
  "cty": "application/json",
  "kid": "zC4j4AchdzwKXS_Mqsh4AfwVySuGsFggO_2xv5tuszk"
}

JWS Payload

{
  "paymentId": "PAY715037422182587",
  "approveUrl": "https://<CONOTOXIA_APPROVAL_HOST>/approve",
  "token": "dGBcEMQoyff6OCQY5l1rehXAwgCDnEwhtp573P1EJyswGBJ79G"
}

All messages and answers sent from the Conotoxia Pay system to the Partner's system are sent in JWS format. Examples included in the documentation are provided in the decoded form for simplicity. In order to verify the received message, Conotoxia Pay's public key has to be got and the authenticity of the obtained data has to be confirmed using this key.

Authenticity of URL parameters

Decoded data parameter (JWS Payload section):

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

After redirecting the User to the Partner's website, the Conotoxia Pay system places, within the configured URL, additional parameters defining the User's payment processing status. In order to ensure authenticity, these parameters are signed.

An example URL is presented below:

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

Generating a public key

Linux

Installation of the required software

To generate the public key it is required to use openssl software.
The process of installing this software is described in the following steps:

  1. Open up console
  2. Depending on distribution, install openssl using package manager with given command:

Generating the key

  1. Open up console
  2. To generate key pair enter the following commands:
    openssl genpkey -out "private-key.pem" -algorithm RSA -pkeyopt rsa_keygen_bits:2048
    openssl rsa -in "private-key.pem" -out "public-key.pem" -outform PEM -pubout
  3. The public key is in "public-key.pem" file

macOS

Installation of the required software

To generate the public key it is required to use openssl software.
The process of installing this software is described in the following steps:

  1. Open up Terminal
  2. To install openssl it is required to install a package manager for macOS called homebrew:
    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  3. To install openssl using package manager enter the following command:
    brew install libressl

Generating the key

  1. Open up Terminal
  2. To generate key pair enter the following commands:
    openssl genpkey -out “private-key.pem” -algorithm RSA -pkeyopt rsa_keygen_bits:2048
    openssl rsa -in “private-key.pem” -out “public-key.pem” -outform PEM -pubout
  3. The public key is in "public-key.pem" file

Windows

Installation of the required software

To generate the public key it is required to use openssl software which is part of a libressl software delivered by OpenBSD for Windows.
The process of installing this software is described in the following steps:

  1. Download libressl from official OpenBSD site:
    https://ftp.openbsd.org/pub/OpenBSD/LibreSSL/libressl-2.5.5-windows.zip
  2. Extract libressl-2.5.5-windows.zip archive

Generating the key

  1. Navigate to extracted folder libressl-2.5.5-windows/x86/
  2. Run openssl.exe
  3. To generate key pair enter the following commands:
    genpkey -out “private-key.pem” -algorithm RSA -pkeyopt rsa_keygen_bits:2048
    rsa -in “private-key.pem” -out “public-key.pem” -outform PEM -pubout
  4. The public key is in "public-key.pem" file in the current directory

Private key security

Store the private key in a secure location such as the HSM (Hardware Security Module). If a hardware-based protection method is not available, you should use an operating system secure private key store. Securely storing your private key will reduce the likelihood of its compromise.

Adding public key

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     -d "@public-key.json" \
     "<CONOTOXIA_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-----"
     }

Response headers:

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

Response body:

{
  "kid": "lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ",
  "status": "INACTIVE"
}

To enable secure communication between Conotoxia Pay and the Partner's system, it is important that the Partner provides a public key to verify the messages sent by the system. The public key in PEM format can be added to the Conotoxia Pay system in following methods:

Resource

POST <CONOTOXIA_PAY_HOST>/public_keys See server addresses

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.
Content-Type application/json

Request body

PublicKey object containing data on the public key

Field name Type Required Description
pem String YES Partner’s public key.
sampleData SampleData NO Object containing sample texts for public key verification.

Object SampleData containing sample texts for public key verification

Sample request with optional sampleData field:

curl -X POST \\
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \\
     -H "Content-Type: application/json" \\
     -d "@public-key.json" \\
     "<CONOTOXIA_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=="
        }
     }
Field name Type Required Description
decodedText String YES Sample text sent to verify the accuracy of the public key.
encodedText String YES Sample text from decodedText field signed by private key with SHA-256 signature.

Response body

Field name Type Required Description
kid String YES Partner's public key identifier.
status String TAK Partner's public key status.

The status field can take the following values:

Value Description
ACTIVATED Public key is active.
INACTIVE Public key require activation.
REVOKED Public key has been revoked.

API errors

The POST /public_keys method can return the following business errors:

Getting public keys

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

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

HTTP/1.1 200 Success
Content-Type: application/jose+json

Response body:

{
 "data": [
   {
     "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-----",
     "status": "ACTIVE"
   }
 ],
   "pagination": {
       "first": true,
       "last": true,
       "currentPageNumber": 1,
       "currentPageElementsCount": 2,
       "pageSize": 10,
       "totalPages": 1,
       "totalElements": 2,
       "pageLimitExceeded": false
     }
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJkYXRhIjpbeyJraWQiOiJjaGkwOU42Qm9nXzBJdnRyYWhEaFpSR0Y3a2lIVEFoUWFJbTR4X3dkcFFVIiwicGVtIjoiLS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbk1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBb1BZdzI4anJONzFWb1dIZlNrVFJcbmI0djhPZFlNandaUnMyZGc1dlBaanYweHJ5TkFxSHBIWVA1K1NDcEV6NllSRkd6dUNXaHFrTmdTS21aZ0xCeHZcbkJWSnQ4WXFaT3RibkI0YXMvNFRJMGR5NzNZVW13MDBMWVhMVGNyUzZhbDZPRnRDNFNlaFVSRWdvVkc5VjhIbGZcbng5VDBibk5PVzVSMHozTHZrQytZOGUxR20reHRYK0s1dVgwMG1kNVRJMWprNUdxb0U5RDdjdXY1bUJYNTBJZ2lcbnpNcWJaWXR0dS9nZEEzVFdENkpuY2VNVTJXUEtKRExvd0dONFJuVXRRSlFpQXBmUlFaRFBibEIrOUFLSmtpVHlcbjhONGc5aEFWbUtid0MzY2VoTzF2TUI3dWpPbEpyTkFYamgxck83QjNPSlEwSlhjcGIyVWhyUFovREl1UmRMdlhcbjZRSURBUUFCXG4tLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0iLCJzdGF0dXMiOiJBQ1RJVkUifV0sInBhZ2luYXRpb24iOnsiZmlyc3QiOnRydWUsImxhc3QiOnRydWUsImN1cnJlbnRQYWdlTnVtYmVyIjoxLCJjdXJyZW50UGFnZUVsZW1lbnRzQ291bnQiOjIsInBhZ2VTaXplIjoxMCwidG90YWxQYWdlcyI6MSwidG90YWxFbGVtZW50cyI6MiwicGFnZUxpbWl0RXhjZWVkZWQiOmZhbHNlfX0.AVbO7pKOwd_wDBTuC9TriU4wafUxuXJ1G35REfhbgzSH0HvoIeymGsb5ItdUmFXzLnQqV5OsptawinIErNzx4DW-RUsheijJztenHHxOPlsE3m1LMfzJqg78qVYnzZatWRlNT86u0O-DIvfcdWcL0MGQDpTxs2V8IJCJWIZqEDm-V3WpUcjgMuqhj_jl-GL1TRhnLZjZkW8YwfvLNBXfpcvfyI58Q4mnhaMsmw6ikgjI3ocIhuGW-uXvA2E-gJxmaoN-O3BqG1u2XWKtWOA_sRf6-0P8PTI2JA-AToUjdK9yd-lcufIkyJvFUYf3XmzgV8uoCH11tCM3gd-Vp-_kfg

The added public keys can be verified in the Merchant's panel on the configuration page. Public keys can also be downloaded by calling the GET /v2/public_keys resource described below.

Resource

GET <CONOTOXIA_PAY_HOST>/v2/public_keys See server addresses

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Field name Type Required Description
pageNumber Number NO Page number.
inStatuses String NO List of statuses that have to contain public keys status.
notInStatuses String NO List of statuses that cannot contain public keys status.

Response body

Data object containing the list of added public keys

Field name Type Required Description
data Array YES List of objects of the PublicKey type.
pagination Pagination YES Metadata of the returned page.

PublicKey object containing information about the public key of the Conotoxia Pay

Field name Type Required Description
kid String YES Public key identifier.
pem String YES Public key.
status String YES Public key status.

The status field can take the following values:

Value Description
ACTIVATED Public key is active.
INACTIVE Public key require activation.
REVOKED Public key has been revoked.

Pagination object containing metadata of the returned page with public keys

Field name Type Required Description
first Boolean YES Defines whether the returned data are on the first page.
last Boolean YES Defines whether the returned data are on the last page.
currentPageNumber Number YES Defines the number of the returned page.
currentPageElementsCount Number YES Defines the number of elements on the returned page.
pageSize Number YES Defines the page size.
totalPages Number YES Defines the number of available pages.
totalElements Number YES Defines the number of available elements.
pageLimitExceeded Boolean YES Defines whether the page limit has been reached.

API errors

The GET /v2/public_keys method can only return technical errors.

Getting Conotoxia Pay key

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

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

Response body:

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

To verify messages received from the Conotoxia Pay system it is necessary to have a public key of the Conotoxia Pay system. In order to obtain the key, the GET /jwks resource should be used.

Resource

GET <CONOTOXIA_PAY_HOST>/jwks See server addresses

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Response body

PublicKeys object containing the list of public keys of the Conotoxia Pay system

Field name Type Required Description
keys Array YES List of objects of the PublicKey type.

PublicKey object containing information about the public key of the Conotoxia Pay

Field name Type Required Description
kty String YES Key type.
kid String YES Public key identifier.
use String YES Use of the key.
n String YES Standard PEM module.
e String YES Standard PEM exponent.

API errors

The GET /jwks method can only return technical errors.

List of supported currencies

Currency Currency code Number of digits after the decimal separator Minimum currency units for a transaction
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
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
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
Thailand Baht THB 2 100
Serbian dinar RSD 2 10

Algorithm for sending notifications

Unsuccessful attempts Next attempt in
1 5 seconds
2 - 11 10 seconds
12 - 20 600 seconds
21 - 110 1800 seconds
> 110 No more attempts
cURL unsigned cURL signed