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 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-Type 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" \
     -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" \
     -d "@data.jws" \
     "<CONOTOXIA_PAY_HOST>/payments"

data.jws
     eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJleHRlcm5hbFBheW1lbnRJZCI6IjM0MkhISDg4TEtESjg5ODc2NzY3IiwicG9pbnRPZlNhbGVJZCI6IlBPUzQ1ODk2MzEzNjU0ODk2NTQiLCJjYXRlZ29yeSI6IkVfQ09NTUVSQ0UiLCJ0b3RhbEFtb3VudCI6eyJjdXJyZW5jeSI6IlBMTiIsInZhbHVlIjoiMTkuOTkifSwiZGVzY3JpcHRpb24iOiJQYXltZW50IGRlc2NyaXB0aW9uLiJ9.aXTbO1zslJlumkvHdFPmgGuaFcAQsaXWf55JT-_WAqhZqXb0W6C_vR9sMXflQ6jBEzOFbCKuGhCIHUBe0iKYeGIaqTlnf4rTUZ1K6G2ZOGwyB_T9mpcKE3GP_ArQibMsO7ZQy2GTS0QnKO25qE_zQCEjuLUme4zaUlWVaNe5qL22KGSpkUhUqEfmrXZtNRJEqpciZ3j1Rp-iuKgFWiYB2t5Kag9DHDta0ILPq4biIIsYe-4FqhfAQvI539P4BcB4nukB45vu4amIMECHF0A6AJFpHFhw_aPOkDjej3iiQbxFfIXJQcrsIlK4oS1AZ5MIuHIkTlel4GxBvF7OyzSV4g

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"
}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk3MTUwMzc0MjIxODI1ODciLCJhcHByb3ZlVXJsIjoiaHR0cHM6Ly88Q09OT1RPWElBX0FQUFJPVkFMX0hPU1Q-L2FwcHJvdmUifQ.CgKVyCYw_3Gh99m3cwFiEaQ5KwdWOLCc3V45B25PWlp4vDSkP4cWld21iYocXrJd-g_dKePSeS9MYaR-n139QWfubcHZTQhcZRvGy6-TlKkghQBuAPB_ZYqJwuy18lV8ZE-vrYsmqmp3XPPKTPaxDMmgWIxKBLzTQlXugGHDMOmD67r_Jx2--_-BvtUSdM-aGcNX-L24bHyK-0lvhPdXyKFjHn-kbC_Od82taVUqoTqoIvBDwWyfE5TT1Cqnoj-DArW4o5NONgU_VcRyniiI5oQHik-lNeq35WoDuQcTUbqudgFLv0k9i8kMnKmc2WWmZk_jOPatlyo_MrbHoYRy7w

Enables setting up a payment transaction.

Resource

POST <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.
Content-Type
application/json
or for signed form
application/jose+json
Accept-Language
<language> The header setting the appropriate language for the payment interface on Conotoxia side. Must comply with the specification RFC 7231.

Request body

PaymentData object containing payment data

Field name Type Required Limit Description
totalAmount Amount YES Payment amount with the currency.
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.
pointOfSaleId String YES 18 characters Point of sale identifier.
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.
notificationUrlParameters Object NO max. 1024 characters Additional parameters, which are sent in URL payment status notifications.
externalPaymentId String YES min. 1 character max. 36 characters Payment identifier on the Partner's side.
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. 21 characters with support for 4 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 znaki Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies.

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
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 and the URL to accept the payment.

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.

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"
        },
        {
            "paymentId": "PAY815576576741391",
            "externalPaymentId": "121/06/2018",
            "status": "COMPLETED"
        }
    ],
    "pagination": {
        "first": true,
        "last": true,
        "currentPageNumber": 1,
        "currentPageElementsCount": 2,
        "pageSize": 10,
        "totalPages": 1,
        "totalElements": 2,
        "pageLimitExceeded": true
    }
}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJkYXRhIjpbeyJwYXltZW50SWQiOiJQQVk3NzIyMzc2OTI1NDgxMTciLCJleHRlcm5hbFBheW1lbnRJZCI6IjEyOC8wNi8yMDE4Iiwic3RhdHVzIjoiUFJPQ0VTU0lORyJ9LHsicGF5bWVudElkIjoiUEFZODE1NTc2NTc2NzQxMzkxIiwiZXh0ZXJuYWxQYXltZW50SWQiOiIxMjEvMDYvMjAxOCIsInN0YXR1cyI6IkNPTVBMRVRFRCJ9XSwicGFnaW5hdGlvbiI6eyJmaXJzdCI6dHJ1ZSwibGFzdCI6dHJ1ZSwiY3VycmVudFBhZ2VOdW1iZXIiOjEsImN1cnJlbnRQYWdlRWxlbWVudHNDb3VudCI6MiwicGFnZVNpemUiOjEwLCJ0b3RhbFBhZ2VzIjoxLCJ0b3RhbEVsZW1lbnRzIjoyLCJwYWdlTGltaXRFeGNlZWRlZCI6dHJ1ZX19.Z6LfVelzrcGQ2TT80N8rdnTs5RGtjFGc0TtmW9pUw8gRk1ZJFUg2z0F5dNZc2g4ZBiUvr3z-PpEEEpqUIcgfcmTZMZDcq2ER_58pIfYhSnIde04Tu-2lvLLP0sadjgTEwLO67lA7nI9nrSlXyeNLhf7Lcksf6-SCdPUigU48fwm32YDaBdOQhVOvDGTtL-8iE3DzD7xqts42HdCKqFudoCey_kd56iLoWdnWKN69fxYR2xq_gLlWN5-uzMtQyEZShWJy8fLfRbJ-RevHb7H2IHXnem0w1_MTQNtpmdCcHFtTLfAxfnW04zKtwBoUcF0DlPnF62sCXm0d4dspsto7_A

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=1&paymentIds=2).
externalPaymentId String NO External payment identifier.
creationDateFrom String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of payment creation from.
creationDateTo 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 max. 36 characters 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. 36 characters Payment identifier in the Partner system.
status String YES max. 14 characters Payment status. Values according to the life cycle of the payment.

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. 36 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
POLI POLi
UNIONPAY UnionPay
INTERAC_ONLINE Interac Online
BLIK BLIK
TRUSTLY Trustly
PAY_BY_LINK Online transfer
GOOGLE_PAY Google Pay
PAYPAL PayPal

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

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.eyJwYXltZW50SWQiOiJQQVk3MTUwMzc0MjIxODI1ODciLCJyZWFzb24iOiJEYW1hZ2VkIGNvdmVyIiwiYW1vdW50Ijp7ImN1cnJlbmN5IjoiUExOIiwidmFsdWUiOiIzNC45OSJ9LCJleHRlcm5hbFJlZnVuZElkIjoiMjM0LzAzLzIwMTYiLCJub3RpZmljYXRpb25VcmwiOiJodHRwOi8vc2hvcC5jb20vbm90aWZpY2F0aW9ucyJ9.BKQtwcAABrfPIKe8GFTdh-mD2e_3J2g9vwHMi9UfMPfdI1UnmEntk80HgQLdrzSAsPS4rowqG82nErGGguBPLYdm1_ahasIimoLAN5S5VUgObSoaOHdmew2Ens-MyXEgdtoH0sVhF3z_Vfq5ZNkOxX6etXiJd5EYc0e22GbPUvYjHJQAioVFQh0O52REK6U225LoeZQ_aj9a6ZqecRxaIihLqu87wWsUrVlJNG971SRSTDRKayoTJ0ftDP9FKrsrPHKCRU0-ZBHSv5J0T-_EPp6Z-UOHW_1tZcHtgPIJBam__4eubMpnClpdmOonhGWzkIUcvf0PzXWut_I5nS08MA

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. 36 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.

Amount object containing refund amount

Field name Type Required Limit Description
value Number YES Amount. Max. 21 characters with support for 4 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 znaki 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"
        },
        {
            "refundId": "REF942484723821414",
            "externalRefundId": "121/06/2018",
            "status": "COMPLETED"
        }
    ],
    "pagination": {
        "first": true,
        "last": true,
        "currentPageNumber": 1,
        "currentPageElementsCount": 2,
        "pageSize": 10,
        "totalPages": 1,
        "totalElements": 2,
        "pageLimitExceeded": true
    }
}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJkYXRhIjpbeyJyZWZ1bmRJZCI6IlJFRjE5Mjg0MzMyNTEzOTU2NyIsImV4dGVybmFsUmVmdW5kSWQiOiIxMjgvMDYvMjAxOCIsInN0YXR1cyI6Ik5FVyJ9LHsicmVmdW5kSWQiOiJSRUY5NDI0ODQ3MjM4MjE0MTQiLCJleHRlcm5hbFJlZnVuZElkIjoiMTIxLzA2LzIwMTgiLCJzdGF0dXMiOiJDT01QTEVURUQifV0sInBhZ2luYXRpb24iOnsiZmlyc3QiOnRydWUsImxhc3QiOnRydWUsImN1cnJlbnRQYWdlTnVtYmVyIjoxLCJjdXJyZW50UGFnZUVsZW1lbnRzQ291bnQiOjIsInBhZ2VTaXplIjoxMCwidG90YWxQYWdlcyI6MSwidG90YWxFbGVtZW50cyI6MiwicGFnZUxpbWl0RXhjZWVkZWQiOnRydWV9fQ.ZBmN9ofnYA-YTmbzYXDUqQPMHPbLAVNiXquWPs5EJBkxvSe6Q4lFKwq9ShvHag3SXYC976eKrpUSV-_tbGpGeHlhUUCGSg4igUNzx5nBM7kiIn95whwkQmWLDQnxIf282Q7aVMXIpAWK18eQpR4DsDnJEugIPphXFr1Eq5E4rS6y7mm5jU2GT7MZkO3UYO-YVxjWvGJkLAyxDo2snbXOlrOWOkzm0PwCYPpl9pYVvCzzANMtiFQVWhTEj7OfwsemimiL7--00wJydsnXcTCNzC6jeFCKH1Dr-HwmGf490rUL7ePpltCFjiKvTHttknYjC3OHoLkPP_Jl_17vIJRKog

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=1&paymentIds=2)
refundIds String NO Refund identifiers (parameter refundIds must be duplicated in the request e.g. /payments?refundIds=1&refundIds=2).
externalRefundId String NO External payment identifier.
creationDateFrom String NO Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) of refund creation from.
creationDateTo 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 max. 36 characters 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. 36 characters Refund identifier in the Partner system.
status String YES max. 20 characters Refund status. Values according to the life cycle of the refund.

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. 36 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. 36 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.

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.

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.

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.

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.

payment-money-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": "payment-money-below-limit",
    "title": "Payment money below limit",
    "status": 409,
    "detail": "Payment money 0.01 EUR is below 1 EUR limit for EUR currency"
}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicGF5bWVudC1tb25leS1iZWxvdy1saW1pdCIsInRpdGxlIjoiUGF5bWVudCBtb25leSBiZWxvdyBsaW1pdCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJQYXltZW50IG1vbmV5IDAuMDEgRVVSIGlzIGJlbG93IDEgRVVSIGxpbWl0IGZvciBFVVIgY3VycmVuY3kifQ.B9JummJuJikYYqOJupAL0joY5AUq2GBqFeiE_1_GmjYAzh4izWszrVqdUbMxZe3hkjKa-LzdSZnLabeSOeAq38-pPOZ0MqMBaKM2h0ruxf-VuA3WBvOuIq6iEQoFvwb49JaPpoNEkN3Ug4OkZ2_G8b22NhsCCw-7Kna7J84YTvo1uK61Y36wMm3kJpYi3zN64ss_l2OFBkrNICgEOUaNFJEYCjdDdZ5VnXm-1t_7aBG1hRflbl-WUOvWfEqujbqnY9T4fcjXKNXSRiWjhVhR0EzR5klgFmwmaRmx8M3JtG7KCeg0FXxlaH1Jl_o1YZ2n_j35ZbH5co9P7BimKfDbeg

The indicated payment amount is below the defined value for a given currency.

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-currency-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": "point-of-sale-currency-not-supported",
    "title": "Currency not supported",
    "status": 409,
    "detail": "Point of sale with identifier POS45896321569859 not support JPY currency"
}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicG9pbnQtb2Ytc2FsZS1jdXJyZW5jeS1ub3Qtc3VwcG9ydGVkIiwidGl0bGUiOiJDdXJyZW5jeSBub3Qgc3VwcG9ydGVkIiwic3RhdHVzIjo0MDksImRldGFpbCI6IlBvaW50IG9mIHNhbGUgd2l0aCBpZGVudGlmaWVyIFBPUzQ1ODk2MzIxNTY5ODU5IG5vdCBzdXBwb3J0IEpQWSBjdXJyZW5jeSJ9.EfQN-MLcLSH1bB23lMY8Fu65BMGXgLxfmVgTrAddwnJ1dEI-HnaHvwyMeEObcSoXhKNmOBM86Czlwthq9ss9bWw5-GMEqYJcwyG0NHjxV9tbMvuecME68NZkIdygxha0iZshRUTIcNv_xfdxkE9tHzRZNcQQhLzYA8x2iJd3Wmysb8shge2dcpFlNdRAZewAcq42lZxk8-yrFsiKpvJoglHQga3qaTr-Mttbyr81rrD-JgTZTWxgYvnMOhjbSQeEe_6wMyFJT-YpAkJd-q1zdhIzFlMAE-RoJaDb3sCWEm73JH5MquzZYLxjBVDRFiibpLmsh0UExZku4CMC9acMMQ

The currency specified in the payment order is different from that defined for the point of sale.

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.

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. Customer logs in to the Conotoxia Pay service (Step 7), selects the currency account from which payment will be made and clicks "Pay" (Step 8).
  7. Conotoxia Pay server accepts the payment, which has been accepted by the Customer for processing (Step 9).
  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 10).

Simultaneously with steps 11 and 12, the 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 12) to the Merchant's server at the notificationUrl address.
  2. Merchant's server saves the status of the completed transaction (Step 13) and sends the response code HTTP 200 OK, which means correct receipt of information about the transaction status (Step 14).
  3. Merchant's server accepts the completed payment transaction (Step 15).

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:

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

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

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

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

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.

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

{
 "publicKeys": [
   {
     "kid": "chi09N6Bog_0IvtrahDhZRGF7kiHTAhQaIm4x_wdpQU",
     "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoPYw28jrN71VoWHfSkTR\nb4v8OdYMjwZRs2dg5vPZjv0xryNAqHpHYP5+SCpEz6YRFGzuCWhqkNgSKmZgLBxv\nBVJt8YqZOtbnB4as/4TI0dy73YUmw00LYXLTcrS6al6OFtC4SehUREgoVG9V8Hlf\nx9T0bnNOW5R0z3LvkC+Y8e1Gm+xtX+K5uX00md5TI1jk5GqoE9D7cuv5mBX50Igi\nzMqbZYttu/gdA3TWD6JnceMU2WPKJDLowGN4RnUtQJQiApfRQZDPblB+9AKJkiTy\n8N4g9hAVmKbwC3cehO1vMB7ujOlJrNAXjh1rO7B3OJQ0JXcpb2UhrPZ/DIuRdLvX\n6QIDAQAB\n-----END PUBLIC KEY-----"
   }
 ]
}
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwdWJsaWNLZXlzIjpbeyJraWQiOiJjaGkwOU42Qm9nXzBJdnRyYWhEaFpSR0Y3a2lIVEFoUWFJbTR4X3dkcFFVIiwicGVtIjoiLS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbk1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBb1BZdzI4anJONzFWb1dIZlNrVFJcbmI0djhPZFlNandaUnMyZGc1dlBaanYweHJ5TkFxSHBIWVA1K1NDcEV6NllSRkd6dUNXaHFrTmdTS21aZ0xCeHZcbkJWSnQ4WXFaT3RibkI0YXMvNFRJMGR5NzNZVW13MDBMWVhMVGNyUzZhbDZPRnRDNFNlaFVSRWdvVkc5VjhIbGZcbng5VDBibk5PVzVSMHozTHZrQytZOGUxR20reHRYK0s1dVgwMG1kNVRJMWprNUdxb0U5RDdjdXY1bUJYNTBJZ2lcbnpNcWJaWXR0dS9nZEEzVFdENkpuY2VNVTJXUEtKRExvd0dONFJuVXRRSlFpQXBmUlFaRFBibEIrOUFLSmtpVHlcbjhONGc5aEFWbUtid0MzY2VoTzF2TUI3dWpPbEpyTkFYamgxck83QjNPSlEwSlhjcGIyVWhyUFovREl1UmRMdlhcbjZRSURBUUFCXG4tLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0ifV19.S6QDamP9oYo-0CumydeSa4qlYYekV8sjNzLlFyDggdzwjRgi7aaGvgk_jeddJqKR74npGPABpKozl-ZY1S9SLHWIj4rh0ffB7y50X01o2DV5NRFOM0jyZ8oFCwk215D5-UfpTc-Np03_8WacfD634crIM4qHBwGZgz6EbQUO9qI1tIOUdbGhi55fWY1lKFn0Y2wIm8LQC1YHy81DssjPw3FBPhKTIgoUv6sRT_4JU2xOSnNac0r3Zwtm6Cu4IDKT7XVjUzE8R31vNvbUvRiLJLV6eiG8-x8w5WFdLDPYmMi_6h3XrZIGwhnYqKBQXaVDola0zSgtlh6OriJwqxrMRQ

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 /public_keys resource described below.

Resource

GET <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.

Response body

PublicKeys object containing the list of added public keys

Field name Type Required Description
publicKeys Array NO List of objects of the PublicKey type.

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.
expiredDate String NO Key expiry date and time according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ.

API errors

The GET /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
Croatia Kuna HRK 2 1
Hungary Forint HUF 0 100
Israeli New Sheqel ILS 2 1
Japan Yen JPY 0 100
Mexico Peso MXN 2 1
Norway Krone NOK 2 10
New Zealand Dollar NZD 2 1
Poland Zloty PLN 2 1
Romania New Leu RON 2 1
Russia Ruble RUB 2 10
Sweden Krona SEK 2 10
Singapore Dollar SGD 2 1
Turkey Lira TRY 2 1
United States Dollar USD 2 1
South Africa Rand ZAR 2 1
Thailand Baht THB 2 100
Serbian dinar RSD 2 10

Algorithm for sending notifications

Unsuccessful attempts Next attempt in
1 10 seconds
2 20 seconds
3 30 seconds
4 - 300 120 seconds
> 300 No more attempts