NAV Navbar

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:

Preliminary requirements

To integrate with the Conotoxia Pay system, the Partner needs:

How to start?

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

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. Add your own public key in PEM format using the POST /public_keys resource.
  3. 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).
  4. 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.
  5. The received response should be decoded and verified in accordance with the information provided in the Communication with the Partner section.
  6. Such a created payment should be transferred to the Customer for approval. 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 client_id and the password 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 "<client_id>:<client_secret>" \
     -d "grant_type=client_credentials&scope=pay_api" \
     "<CINKCIARZ_OIDC_HOST>/connect/token"

Response body:

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

Enables getting the Conotoxia Pay access token.

Resource

POST <CINKCIARZ_OIDC_HOST>/connect/token

Request headers

Name Value Remarks
Authorization client_id: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;charset=UTF-8" \
     -d "@data.json" \
     "<CONOTOXIA_PAY_HOST>/payments"

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

Response headers:

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

Response body:

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

Enables setting up a payment transaction.

Resource

POST <CONOTOXIA_PAY_HOST>/payments

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;charset=UTF-8

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. 256 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. 256 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. 256 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.
merchant Merchant YES Merchant data.
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.
disablePayLater Boolean NO Flag specifying whether the functionality should be activated for pay later.

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.

Merchant object

Field name Type Required Limit Description
name String YES max. 100 characters Merchant name.

Payment category

Defines the method of settlement with a Partner.

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

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;charset=UTF-8

Response body:

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

Gets a list of payments with specified search parameters.

Resource

GET <CONOTOXIA_PAY_HOST>/payments

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.

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

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.

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.
description String NO max. 512 characters Description of the payment status. Can be sent for REJECTED status.

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

Status Description
NEW The payment has been approved by the Customer.
COMPLETED The payment was successfully completed.
CANCELLED The payment has been cancelled by the system.
REJECTED The payment has been rejected by the Customer.

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;charset=UTF-8" \
     -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"
     }

Response headers:

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

Response body:

{
  "id": "REF505142910935123"
}

Allows to create a refund for payment transaction.

Resource

POST <CONOTOXIA_PAY_HOST>/refunds

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;charset=UTF-8

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.
totalAmount 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. 256 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;charset=UTF-8

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

Gets a list of refunds with specified search parameters. Resource

GET <CONOTOXIA_PAY_HOST>/refunds

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.

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",
    "externalRefundId":"121/06/2018",
    "code":"COMPLETED"
}

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.

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.
code String YES max. 14 characters Refund status.

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;charset=UTF-8

Response body:

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

Returned when a request has an incorrect structure.

403 Forbidden

Response headers:

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

Response body:

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

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;charset=UTF-8

Response body:

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

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;charset=UTF-8

Response body:

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

Returned when business validation errors occur.

415 Unsupported Media Type

Response headers:

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

Response body:

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

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;charset=UTF-8

Response body:

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

An unexpected error occured.

503 Service Unavailable

Response headers:

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

Response body:

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

Service is not available.

API errors - business

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

invalid-pem

Response headers:

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

Response body:

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

Returned when the sent public key is incorrect.

invalid-public-key

Response headers:

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

Response body:

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

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;charset=UTF-8

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

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;charset=UTF-8

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

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;charset=UTF-8

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

The point of sale identifier is incorrect.

store-not-found

Response headers:

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

Response body:

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

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

contract-category-not-supported

Response headers:

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

Response body:

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

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

payment-money-below-limit

Response headers:

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

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

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

payment-not-completed

Response headers:

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

Response body:

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

The payment for which the refund is made is incompleted.

point-of-sale-currency-not-supported

Response headers:

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

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

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

point-of-sale-deleted

Response headers:

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

Response body:

{
    "type"  : "point-of-sale-deleted",
    "title" : "Point of sale deleted",
    "status": 409,
    "detail": "Point of sale with identifier POS908701159456470 is deleted"
}

The point of sale has been deleted.

point-of-sale-forbidden-error-url

Response headers:

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

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

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;charset=UTF-8

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

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;charset=UTF-8

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

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;charset=UTF-8

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

The point of sale is inactive.

refund-amount-too-large

Response headers:

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

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

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;charset=UTF-8

Response body:

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

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

sample-text-verification-failed

Response headers:

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

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

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;charset=UTF-8

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

Returned when the added public key is under 2048 bytes.

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’s online shop operated by the Integrator, a basket with a list of products to purchase.

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 request to the Integrator server, and then redirects the Customer to the Integrator server (Step 2).
  3. Integrator server sends a PaymentData message to the Conotoxia Pay server (Step 3).
  4. Conotoxia Pay server checks the correctness of the received message and creates a payment order (Step 4).
  5. Conotoxia Pay server sends a PaymentInfo response to Merchant's server (Step 5).
  6. Integrator's server records the status of the transaction confirming acceptance of the instruction in Conotoxia Pay (Step 6) and redirects the Customer to the address of approveUrl received in the PaymentInfo response (Step 7).
  7. Customer logs in to the Conotoxia Pay service (Step 8), selects the currency account from which payment will be made and clicks "Pay" (Step 9).
  8. Conotoxia Pay server accepts the payment, which has been accepted by the Customer for processing (Step 10).
  9. Conotoxia Pay server redirects to the Integrator's server - to the returnUrl address given at the time of setting up the payment order or configured in the point of sale (Step 12), which redirects the Customer to the Merchant's website (usually to the page with "thanks for the purchase you have made") (Step 13).

Simultaneously with steps 11 and 13, the payment processing process is carried out:

  1. After completing payment processing, the Conotoxia Pay server sends the PaymentStatus message with information about the transaction status to the Integrator's server at notificationUrl address (Step 14).
  2. The Integrator's server records the status of the completed transaction (Step 15) and sends the HTTP 200 OK response code, which indicates correct receipt of information about the transaction status (Step 16).
  3. The Integrator's server sends information about the transaction status to the Merchant's server (Step 17).
  4. Merchant's server accepts the completed payment transaction (Step 18).

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 completed 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 wallet 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": "iQn7M-Eyzw5sde5GwaOu51Xzl8WFXJzNW3pmCBENhhk"
}

JWS Payload

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

Example of a payment order:

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

payload.jws
     eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJpUW43TS1FeXp3NXNkZTVHd2FPdTUxWHpsOFdGWEp6TlczcG1DQkVOaGhrIn0.eyAgImV4dGVybmFsUGF5bWVudElkIjogIjM0MkhISDg4TEtESjg5ODc2NzY3IiwgICJwb2ludE9mU2FsZUlkIjogIlBPUzQ1ODk2MzIxNTk2NTQ3ODU5IiwgICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwgICJ0b3RhbEFtb3VudCI6IHsgICAgImN1cnJlbmN5IjogIlVTRCIsICAgICJ2YWx1ZSI6ICIxOS45OSIgIH0sICAibWVyY2hhbnQiOiB7ICAgICJuYW1lIjogIlNob3AgbmFtZSIgIH0sICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbi4ifQ.CrO1KVHEoaa6kfhtOMNuTJU-GaseYMLVZBAvD1JPOZ6Mmi_CD9TakNq3LTbac49c5KMS7hwmZnW-RKiVIdOKEVslziLrJIU1Aigben547xyU0OxILIf01_eqrk3VPPf3tfgG6GmwkeKQbWS-TnVIeurzEFHERv7lDw9W2a4DxbBZg1UkOQd59Ri9zRkDeANZCV1rYD1aVHIY-1LGHAyQP9BVVaho1VTilCZTOucJ3nSDT1eP9zqhXWY5WQKFimRJn6vdghE7PIS_GMIgtTyPBNMx1fVSN633koFktYApGl-Ioe3AQojMQol4Q3hpTU4zrVV7SS8na5reOYdUS3NKIw

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:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJpUW43TS1FeXp3NXNkZTVHd2FPdTUxWHpsOFdGWEp6TlczcG1DQkVOaGhrIn0.eyAgImV4dGVybmFsUGF5bWVudElkIjogIjM0MkhISDg4TEtESjg5ODc2NzY3IiwgICJwb2ludE9mU2FsZUlkIjogIlBPUzQ1ODk2MzIxNTk2NTQ3ODU5IiwgICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwgICJ0b3RhbEFtb3VudCI6IHsgICAgImN1cnJlbmN5IjogIlVTRCIsICAgICJ2YWx1ZSI6ICIxOS45OSIgIH0sICAibWVyY2hhbnQiOiB7ICAgICJuYW1lIjogIlNob3AgbmFtZSIgIH0sICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbi4ifQ.CrO1KVHEoaa6kfhtOMNuTJU-GaseYMLVZBAvD1JPOZ6Mmi_CD9TakNq3LTbac49c5KMS7hwmZnW-RKiVIdOKEVslziLrJIU1Aigben547xyU0OxILIf01_eqrk3VPPf3tfgG6GmwkeKQbWS-TnVIeurzEFHERv7lDw9W2a4DxbBZg1UkOQd59Ri9zRkDeANZCV1rYD1aVHIY-1LGHAyQP9BVVaho1VTilCZTOucJ3nSDT1eP9zqhXWY5WQKFimRJn6vdghE7PIS_GMIgtTyPBNMx1fVSN633koFktYApGl-Ioe3AQojMQol4Q3hpTU4zrVV7SS8na5reOYdUS3NKIw

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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnIo4OMp7I5ugVgGQquUL
FFdC0m1sL+1e7M1zX8lobKPJpQwApDKaEFTBWjrK5aXvzAsxqKzKzG3yUCSGqa/f
huzdzs3kBlvIFCPwk5dM5uc5v2+2W0SF0/8lF3NBUjK2jz8s3Nyb3cCWCfysRF+1
KhF/4ushqX4spCraIU2GkavZ6ETn/Oyfu1fJnZSuH16fwj2OwGsFnTUHam5yrihn
htxIkp4eUbhBOkjMMwb4XLygD1dlcg61Pbe60dmuwV+ZWQzfoi4QzlZd9kpePEva
bPar+AUItKilx5XvNm86PLGBbcsGIMhtew019UP0MrgF1S2/99ZsF2V76haipaXS
kQIDAQAB
-----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;charset=UTF-8",
  "kid": "zC4j4AchdzwKXS_Mqsh4AfwVySuGsFggO_2xv5tuszk"
}

JWS Payload

{
  "paymentId": "PAY715037422182587",
  "approveUrl": "https://<CONOTOXIA_PAY_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

Adding public key

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -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==" } }

Response headers:

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

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 should be provided in PEM format by calling the POST /public_keys resource.

Resource

POST <CONOTOXIA_PAY_HOST>/public_keys

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;charset=UTF-8

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

Field name Type Required Description
decodedText String NO Sample text sent to verify the accuracy of the public key.
encodedText String NO 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;charset=UTF-8

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

Added public keys may be verified using the GET /public_keys resource.

Resource

GET <CONOTOXIA_PAY_HOST>/public_keys

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;charset=UTF-8

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

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

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