Introduction

The documentation contains a description of business processes and REST API methods provided by the Mass Transfers service. The API allows you to easily and safely automate the process of ordering a transfer of funds to recipients in various currencies.

API can be used for:

• create and listing transfer transactions;
• adding and listing recipients of transfers.

How to start?

To integrate with the Conotoxia Mass Transfer system, the Partner needs:

• API client identifier and API client secret needed to obtain an access token to Conotoxia API.
• Identifier of his own public key (kid) added to Conotoxia Mass Transfer system.
• Conotoxia host addresses, which are described in the documentation as CONOTOXIA_OIDC_HOST and CONOTOXIA_HOST. They are available on the configuration page.

Creation of a transfer order

To create a transfer 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 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 transfer). Note that JWS which will be sent to Conotoxia API should have public key identifier (kid) in header section. It will be used to verify requests by the Conotoxia system.
3. Execute request on the POST /money_transfers resource by placing in the request body JWS data and set the correct header according to the information provided in the Communication with Conotoxia 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 API 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

POST <CONOTOXIA_OIDC_HOST>/connect/token

Example Request

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"

Example Response

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

Enables getting the Conotoxia API access token.

Resource

POST <CONOTOXIA_OIDC_HOST>/connect/token

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.
expires_in	string	YES	Token validity time in seconds.
token_type	string	YES	Token type.

Recipients of transfers

Adding recipient

Resource

POST <CONOTOXIA_HOST>/v1/recipients

Example Request

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     "<CONOTOXIA_HOST>/v1/recipients" \
     -d "@data.json"

data.json
     {
        "alias": "Recipient alias",
        "name": "Recipient name",
        "surname": "Recipient surname",
        "isCompany": false,
        "account": {
          "currency": "EUR",
          "accountNumber": "28114010944877648421521774",
          "routingNumber": null,
          "country": "PL",
          "swift": null,
          "bankName": null,
          "bankRegion": null
        },
        "address": {
          "street": "al. Jerozolimskie 1",
          "city": "Warsaw",
          "postalCode": "00-001",
          "country": "PL"
        }
     }

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

data.jws
     eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJhbGlhcyI6ICJSZWNpcGllbnQgYWxpYXMiLAogICJuYW1lIjogIlJlY2lwaWVudCBuYW1lIiwKICAic3VybmFtZSI6ICJSZWNpcGllbnQgc3VybmFtZSIsCiAgImlzQ29tcGFueSI6IGZhbHNlLAogICJhY2NvdW50IjogewogICAgImN1cnJlbmN5IjogIkVVUiIsCiAgICAiYWNjb3VudE51bWJlciI6ICIyODExNDAxMDk0NDg3NzY0ODQyMTUyMTc3NCIsCiAgICAicm91dGluZ051bWJlciI6IG51bGwsCiAgICAiY291bnRyeSI6ICJQTCIsCiAgICAic3dpZnQiOiBudWxsLAogICAgImJhbmtOYW1lIjogbnVsbCwKICAgICJiYW5rUmVnaW9uIjogbnVsbAogIH0sCiAgImFkZHJlc3MiOiB7CiAgICAic3RyZWV0IjogImFsLiBKZXJvem9saW1za2llIDEiLAogICAgImNpdHkiOiAiV2Fyc2F3IiwKICAgICJwb3N0YWxDb2RlIjogIjAwLTAwMSIsCiAgICAiY291bnRyeSI6ICJQTCIKICB9Cn0K.LctrXGtX7S_aZV68I4FST49NjeX0hHwBarBDc_23dedUzuiWQwxDMi66hymP451VBIIQxT4XiDdk8ZgNnsWArl0lSOA_4sgu_x_rUOoZWj8-ZAFRU2NE9fUndIgELKvzdT-Oc9_h--kmYjdPxeoi8005pIpg34TVK3AlaPYJTnAXuaJfwAAl07JVcw4T9g3Ga5DIoNsxx-DRObIWWodxuhodVNYeZo8UX8weJS4Kxk7wfzKXPgSEMlVoeXhOnOWnZ6eznXICUjSP-E_YeaZ-6kVcssO7cRkZ5FUoFVMixIX0KsgZiZQvRmwgPRVyvPPgfbTs-lDF66UESOMtry4Eyg

Response headers:

SCA-Required true
HTTP/1.1 201 Created
Content-Type: application/json

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

Example Response

{
  "sca": {
    "authenticationId": "664c0d2d-81a4-4515-961b-6fb4cec74f48",
    "challengeId": "e2e40280-c624-4a14-9089-59b556382ff5",
    "payload": "{\"name\":\"Recipient alias\",\"creationDate\":\"2021-12-20T11:16:42.000000\"}"
  },
  "links": {
    "scaConfirm": {
      "href": "/sca/authentications/664c0d2d-81a4-4515-961b-6fb4cec74f48/challenges/e2e40280-c624-4a14-9089-59b556382ff5",
      "method": "PUT"
    }
  }
}

    eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJzY2EiOiB7CiAgICAiYXV0aGVudGljYXRpb25JZCI6ICI2NjRjMGQyZC04MWE0LTQ1MTUtOTYxYi02ZmI0Y2VjNzRmNDgiLAogICAgImNoYWxsZW5nZUlkIjogImUyZTQwMjgwLWM2MjQtNGExNC05MDg5LTU5YjU1NjM4MmZmNSIsCiAgICAicGF5bG9hZCI6ICJ7XCJuYW1lXCI6XCJSZWNpcGllbnQgYWxpYXNcIixcImNyZWF0aW9uRGF0ZVwiOlwiMjAyMS0xMi0yMFQxMToxNjo0Mi4wMDAwMDBcIn0iCiAgfSwKICAibGlua3MiOiB7CiAgICAic2NhQ29uZmlybSI6IHsKICAgICAgImhyZWYiOiAiL3NjYS9hdXRoZW50aWNhdGlvbnMvNjY0YzBkMmQtODFhNC00NTE1LTk2MWItNmZiNGNlYzc0ZjQ4L2NoYWxsZW5nZXMvZTJlNDAyODAtYzYyNC00YTE0LTkwODktNTliNTU2MzgyZmY1IiwKICAgICAgIm1ldGhvZCI6ICJQVVQiCiAgICB9CiAgfQp9Cg.mDg_5pb_xR-AOcU4ikEivWkhDnckhCITv9D6CMIFyyjr-7TmCRdmjzXxIVHtEy_POMqW-RaOg8R_2JU8g6TzfzVCKLluOoWuczVRFirN_Nm_CM06t91aYK0uepd73eHtU29Q2ehVnWbRVyNsoBeQtNxIh1pFSa8DRS3Zc29cSxJVsLZFyY9swpYd6hYxSfLptYhx85yjV0Y9GD_U-aCtXrm910mCYG71h6Y0iLsK9z1VsksNVTUPRNNgbrL6xH_LKzci-3rfVFU_luMwjRF-ODrIEFFko8R5ADjtchMoQPvezKml29kh5TtJ4ODy1yCQkSE79dLItCtBwCifC2wJ0A

The REST API method allows you to add recipient to your recipients list. Recipient is required to order money transfer.

If response of adding a recipient contains SCA-Required:true header it means that SCA confirmation is required to add recipient in accordance with the PSD2 regulation. To confirm execute confirm add recipient method.

Resource

POST <CONOTOXIA_HOST>/v1/recipients

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in the Authorization chapter.
Content-Type	application/jose+json	Format of request body data.

Request body

Field name	Type	Required	Description
alias	string	YES	Recipient alias/nickname. Length: from 5 to 25 characters.
name	string	YES	Recipient name or Company name. Length: from 2 to 45 characters.
surname	string	NO	Recipient surname. Length: from 2 to 45 characters.
isCompany	boolean	YES	Whether the recipient is a company or a private person.
account	object	YES	Recipient bank account.
account.accountNumber	string	YES	Bank account number.
account.routingNumber	string	NO	U.S. bank account routing number.
account.currency	string	YES	The currency in which the account is kept. See Currencies dictionary.
account.country	string	YES	Country where the account is kept. ISO 3166-1 alpha-2 country code.
account.swift	string	NO	Swift (BIC) code of bank.
account.bankName	string	NO	Name of the bank where the account was opened. Length: from 2 to 128 characters.
account.bankRegion	string	NO	Region of the bank where the account was opened. Length: from 2 to 128 characters.
address	object	YES	Recipient address.
address.street	string	YES	Street. Length: from 5 to 128 characters.
address.postalCode	string	YES	Postal code. Country specific format.
address.city	string	YES	City. Length: from 3 to 45 characters.
address.country	string	YES	Country. ISO 3166-1 alpha-2 country code.

Response headers

Name	Value	Description
SCA-Required	true	Indicates if Strong Customer Authentication request is required.
HTTP/1.1	201	Response status.
Content-Type	application/json;charset=UTF-8	Response content type.

Response body

Field name	Type	Required	Description
sca	object	YES	SCA data.
sca.authenticationId	string	YES	SCA authentication identifier.
sca.challengeId	string	YES	SCA challenge identifier.
sca.payload	object	YES	Response payload.
sca.payload.name	string	YES	Alias of the added recipient.
sca.payload.creationDate	string	YES	Time when recipient was added. In ISO-8601 format:YYYY-MM-DDThh:mm:ssZ
links	object	YES	Section with links.
links.scaConfirm	object	YES	SCA confirmation link section. To confirm SCA signed payload must be used as request body.
links.scaConfirm.href	string	YES	SCA confirmation address.
links.scaConfirm.method	string	YES	SCA confirmation http method.

Confirm add recipient (SCA)

Resource

PUT <CONOTOXIA_HOST>/sca/authentications/{authenticationId}/challenges/{challenge}

Example Request

curl -X PUT \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     "<CONOTOXIA_HOST>/sca/authentications/{authenticationId}/challenges/{challenge}" \
     -d "@data.json"

data.json
{
  "signedPayload": "eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.eyJuYW1lIjoiUmVjaXBpZW50IGFsaWFzIiwiY3JlYXRpb25EYXRlIjoiMjAyMS0xMi0yMFQxMToxNjo0Mi4wMDAwMDAifQ.aZhMPiDV5SZaV0vZ2cbVS7rdJuRblL6sXI1PfdQXKbG4j_yDscDM61Kr3UiIUA41u9UBX0lucNLyC1howDyfN591eZ0W5jCYzzGH86XH67sSYvqXdAXeXeEBujgJ7WVHUw_1q6tQzXJPkTdxCfcJoZkETCaIP31ZUcoWxYDwyn2nj13yncKJUKXklwlKlneKy4V5P6WkAirdXKEG9PP0VcyeA1KiMxsXFSnEaigyUpVXq17eleZqnOnsSTOm4OyQI9gc6j4NWRBckRKO62KYYXSsBUoABTUHQSwwJOu4ovJ4f1ppOyky6z8_hgADwf26F0Si1pjjXaxbt83NTwpOkQ"
}

Response headers:

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

Example Response

{
  "id": 442539935797
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJpZCI6IDQ0MjUzOTkzNTc5Nwp9Cg.k_0qofmqDadohbeEBictW0d2AUtc_0_OsLI6P56K2BxxvZqBUMplkIKGD0y1qoAVdKlC35whhan9agcrRK5fiC67smTEgc5wBtBlVxZCbzOA3h72Tcs5tG9BE4RmJNV4ZoosSD9Z45HoVxareH-z2ZC3KyaFfml7-KH1GyDh3YbUgu203Makxkq0C0TjXaMH0g18xUaApS5OuYo5IYgD2-LE2Q3aFU4vCOSlxrJo_CdnZB-UikoMgOS0ZyJvb7_d6-TgeSqT1Kdjwt88VxDa5TebUx20w50btL90jDYlPd2DCpW19rnQYDiONFVCEDZwmx4vT2J2emz50RNKkvBL4Q

The REST API method allows you to SCA confirm adding recipient to your recipients list.

To confirm adding a recipient, execute the API method defined in the links.scaConfirm section of the response from the recipient adding method. In the request body the signed content of the sca.payload field of the response from the recipient adding method should be provided.

Resource

PUT <CONOTOXIA_HOST>/sca/authentications/{authenticationId}/challenges/{challenge}

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in the Authorization chapter.
Content-Type	application/json	Format of request body data.

Request body

Field name	Type	Required	Description
signedPayload	string	YES	Signed JWS payload

Response headers

Name	Value	Description
HTTP/1.1	200	Response status.
Content-Type	application/json;charset=UTF-8	Response content type.

Response body

Field name	Type	Required	Description
id	number	YES	Identifier of added recipient.

Retrieve list of recipients

Resource

GET <CONOTOXIA_HOST>/v1/recipients

Example Request

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/v1/recipients"

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/v1/recipients"

Response headers:

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

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

Example Response

{
  "data": [
    {
      "id": "94147255530211",
      "alias": "recipientAlias",
      "name": "recipientName",
      "surname": "recipientSurname",
      "isCompany": false,
      "account": {
        "accountNumber": "75105085299481873473581255",
        "currency": "PLN",
        "bankName": "ING Bank",
        "country": "PL"
      },
      "address": {
        "street": "al. Jerozolimskie 1",
        "postalCode": "00-001",
        "city": "Warszawa",
        "country": "PL"
      }
    }
  ],
  "pagination": {
    "hasNext": false,
    "hasPrevious": false,
    "order": "DEFAULT",
    "pageSize": 50,
    "pageNumber": 1
  }
}

    eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJkYXRhIjogWwogICAgewogICAgICAiaWQiOiAiOTQxNDcyNTU1MzAyMTEiLAogICAgICAiYWxpYXMiOiAicmVjaXBpZW50QWxpYXMiLAogICAgICAibmFtZSI6ICJyZWNpcGllbnROYW1lIiwKICAgICAgInN1cm5hbWUiOiAicmVjaXBpZW50U3VybmFtZSIsCiAgICAgICJpc0NvbXBhbnkiOiBmYWxzZSwKICAgICAgImFjY291bnQiOiB7CiAgICAgICAgImFjY291bnROdW1iZXIiOiAiNzUxMDUwODUyOTk0ODE4NzM0NzM1ODEyNTUiLAogICAgICAgICJjdXJyZW5jeSI6ICJQTE4iLAogICAgICAgICJiYW5rTmFtZSI6ICJJTkcgQmFuayIsCiAgICAgICAgImNvdW50cnkiOiAiUEwiCiAgICAgIH0sCiAgICAgICJhZGRyZXNzIjogewogICAgICAgICJzdHJlZXQiOiAiYWwuIEplcm96b2xpbXNraWUgMSIsCiAgICAgICAgInBvc3RhbENvZGUiOiAiMDAtMDAxIiwKICAgICAgICAiY2l0eSI6ICJXYXJzemF3YSIsCiAgICAgICAgImNvdW50cnkiOiAiUEwiCiAgICAgIH0KICAgIH0KICBdLAogICJwYWdpbmF0aW9uIjogewogICAgImhhc05leHQiOiBmYWxzZSwKICAgICJoYXNQcmV2aW91cyI6IGZhbHNlLAogICAgIm9yZGVyIjogIkRFRkFVTFQiLAogICAgInBhZ2VTaXplIjogNTAsCiAgICAicGFnZU51bWJlciI6IDEKICB9Cn0K.Gjxrc3Tdyakxh4rWYLQOywvuxuoFtR3vF3Qh6KiXr85rvb8CdsndBVlhQmffI519vCaj-RQritFS9cCqEJtZM_yVCcZFbputEoh-8A4h1qObpv9qBRMRzcfzNpTp3OOD7M1RtsQXlOkYMV15JbKRMIYQjUbs0I3FnJFioeHiZyOEgFtpoIZ5sOfyuO0CKwRDRivuCrHbGHnH1vN5Q8XaePh9qnwGE1Bt8mEVp9zt2K7LqsyO8nLVTq-_zwSpofXMGNhAmHBl9jCpiiqFvIaSSQ-wv621vGSJJAetD7SBF3vBFWQl9mJ78zWZnR16cUfoK8uIpuc7SgfvVRYVN0h1Ow

Get a list of recipients filtered according to given parameters

Resource

GET <CONOTOXIA_HOST>/v1/recipients

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization documentation.

Query parameters

Field name	Type	Required	Description
currency	string	NO	Currency code of recipient account. See Currencies dictionary.
accountNumber	string	NO	Recipient account number. Consists of: account.country + account.routingNumber + account.accountNumber. Excluding whitespace characters.
pageNumber	number	NO	Page number.
pageSize	number	NO	Number of elements on single page response.

Response

Data array containing the list of recipients

Field name	Type	Required	Description
data	array	YES	List of objects of the Recipient type.
pagination	object	YES	Information of response pagination Pagination

Recipient object containing recipient details

Field name	Type	Required	Description
id	string	YES	Recipient identifier.
alias	string	YES	Recipient alias/nickname. Max 25 characters.
name	string	YES	Recipient name or Company name. Max 45 characters.
surname	string	NO	Recipient surname. Max 45 characters.
isCompany	boolean	YES	Whether the recipient is a company or a private person.
account	object	YES	Bank account.
account.accountNumber	string	YES	Bank account number.
account.routingNumber	string	NO	U.S. bank account routing number.
account.currency	string	YES	Currency code of debited funds. See Currencies dictionary.
account.bankName	string	YES	Name of the bank where the account was opened. Max 128 characters.
account.country	string	YES	Country. ISO 3166-1 alpha-2 country code.
account.swift	string	YES	Swift (BIC) code of bank.
address	object	YES	Recipient address.
address.street	string	YES	Street. Max 128 characters.
address.postalCode	string	YES	Postal code. Max 45 characters.
address.city	string	YES	City. Max 45 characters.
address.country	string	YES	Country. ISO 3166-1 alpha-2 country code.

Pagination object containing metadata of the returned recipient data page

Field name	Type	Required	Description
pagination.hasPrevious	boolean	YES	Information that the previous page exists.
pagination.hasNext	boolean	YES	Information that the next page exists.
pagination.pageNumber	number	YES	Number of elements on page. Integer.
pagination.pageSize	number	YES	Page size. Integer.

Mass transfers

Create a transfer

Resource

POST <CONOTOXIA_HOST>/v1/money_transfers

Example Request

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/v1/money_transfers" \
     -H "Content-Type: application/json" \
     -d "@data.json"

data.json
     {
        "externalId": "your_external_id",
          "from": {
            "type": "WALLET",
            "amount": {
              "currency": "USD",
              "value": 0
            }
        },
        "to": {
          "amount": {
            "currency": "EUR",
            "value": 100
          },
          "recipient": {
            "type": "IBAN",
            "id": "1234567890",
            "message": "Transfer message to recipient"
          }
        }
     }

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

data.jws
    eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJleHRlcm5hbElkIjogInlvdXJfZXh0ZXJuYWxfaWQiLAogICJmcm9tIjogewogICAgInR5cGUiOiAiV0FMTEVUIiwKICAgICJhbW91bnQiOiB7CiAgICAgICJjdXJyZW5jeSI6ICJVU0QiLAogICAgICAidmFsdWUiOiAwCiAgICB9CiAgfSwKICAidG8iOiB7CiAgICAiYW1vdW50IjogewogICAgICAiY3VycmVuY3kiOiAiRVVSIiwKICAgICAgInZhbHVlIjogMTAwCiAgICB9LAogICAgInJlY2lwaWVudCI6IHsKICAgICAgInR5cGUiOiAiSUJBTiIsCiAgICAgICJpZCI6ICIxMjM0NTY3ODkwIiwKICAgICAgIm1lc3NhZ2UiOiAiVHJhbnNmZXIgbWVzc2FnZSB0byByZWNpcGllbnQiCiAgICB9CiAgfQp9Cg.B54ZENVK-53yhxpaKasrQhRr85q0rcrB6gJefffB6M_aHp5rAojNr5VFf3oo7mNW1ZvYXXYwKVXNoEldYGS_sw--wzIhAvMyNiChWsApeMvLc5NGnhryio8ykBl59bCw1eH-X7JW4nT6la_fzEZj9ZOikenJroCHdQtUT1acOAOHITyBootXOhD9qmIhgKMpYXqYMkSZ9lZsRu0K_xfavw9qL4WpSvMulI-oLXJfevTVZtHwlFSFwMu1Wsz6YgR5fAYTYyy6h7s3LdqpouPckfJ1f-dyBH17C8C0uILI9ucO1elN2R4aoqDKMedHP5b-RH3Auh2ozIHVi23D8G_wAA

Response headers:

SCA-Required true
HTTP/1.1 201 Created
Content-Type: application/json

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

Example Response

{
  "sca": {
    "authenticationId": "ae22e27f-978e-48c6-ad98-19dab2bfe480",
    "challengeId": "f1226a1d-fe57-4adc-8354-a726faf96adb",
    "payload": "{\"publicId\":\"MTR2280284246901885\",\"remitAmount\":{\"value\":99.8,\"currency\":\"PLN\"},\"exchange\":{\"rate\":4.5241,\"rateInverted\":0.221038,\"scaling\":1},\"creationDate\":\"2022-11-22T17:05:08.645041Z\",\"recipientType\":\"IBAN\",\"recipientName\":\"Adam Nowak\",\"recipientData\":\"PL36109024026573812275388887\"}"
  },
  "links": {
    "scaConfirm": {
      "href": "/sca/authentications/ae22e27f-978e-48c6-ad98-19dab2bfe480/challenges/f1226a1d-fe57-4adc-8354-a726faf96adb",
      "method": "PUT"
    }
  }
}

    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJzY2EiOnsiYXV0aGVudGljYXRpb25JZCI6ImFlMjJlMjdmLTk3OGUtNDhjNi1hZDk4LTE5ZGFiMmJmZTQ4MCIsImNoYWxsZW5nZUlkIjoiZjEyMjZhMWQtZmU1Ny00YWRjLTgzNTQtYTcyNmZhZjk2YWRiIiwicGF5bG9hZCI6IntcInB1YmxpY0lkXCI6XCJNVFIyMjgwMjg0MjQ2OTAxODg1XCIsXCJyZW1pdEFtb3VudFwiOntcInZhbHVlXCI6OTkuOCxcImN1cnJlbmN5XCI6XCJQTE5cIn0sXCJleGNoYW5nZVwiOntcInJhdGVcIjo0LjUyNDEsXCJyYXRlSW52ZXJ0ZWRcIjowLjIyMTAzOCxcInNjYWxpbmdcIjoxfSxcImNyZWF0aW9uRGF0ZVwiOlwiMjAyMi0xMS0yMlQxNzowNTowOC42NDUwNDFaXCIsXCJyZWNpcGllbnRUeXBlXCI6XCJJQkFOXCIsXCJyZWNpcGllbnROYW1lXCI6XCJBZGFtIE5vd2FrXCIsXCJyZWNpcGllbnREYXRhXCI6XCJQTDM2MTA5MDI0MDI2NTczODEyMjc1Mzg4ODg3XCJ9In0sImxpbmtzIjp7InNjYUNvbmZpcm0iOnsiaHJlZiI6Ii9zY2EvYXV0aGVudGljYXRpb25zL2FlMjJlMjdmLTk3OGUtNDhjNi1hZDk4LTE5ZGFiMmJmZTQ4MC9jaGFsbGVuZ2VzL2YxMjI2YTFkLWZlNTctNGFkYy04MzU0LWE3MjZmYWY5NmFkYiIsIm1ldGhvZCI6IlBVVCJ9fX0.ZNM6poiBQf-qlGyfFEiKP0xKqEXJRrhYnFv8kSQNcgZMxbP6rceNm3ApqXLLJwQ7rF5YEeKtdui74Qn3LJvU3IYITwrPwp1daAK5G4l_lZio80hWwpSlQLCmtMzbzuzR8xj73b3OoQEhlw9ZVaXjsVtBT3qclaJeGObZ_ycMpgzBN6wTRLpIjaZPlHemk75mZSJqaigTB4CBL3tmlRVH25Lajpj7yWupfrofN-GOEfrM9ftXWsQid5Jf0hWDHJiU0VrCvnDBepIuZELxGTu08Wvwj_OYp6pPl4wiWYsUs8Yq_-MuB_O2SV1dRLT0-vFyh6aGaCnslmsREYj0VVlacA

The REST API method allows you to order a transfer from a currency wallet to a defined recipient's bank account. During the transfer, the currency exchange may be automatically performed at the current exchange rate.

Resource

POST <CONOTOXIA_HOST>/v1/money_transfers

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in the Authorization chapter.
Content-Type	application/jose+json	Format of request body data.

Request body

Field name	Type	Required	Description
externalId	string	YES	The ID of the transaction that you provide. Unique per request. Length: from 10 to 50 characters.
purpose	string	NO	Purpose of sending transfer. Required when sending funds to a bank account registered in the US. Length: 1 to 200 alphanumeric characters.
from	object	YES	Define from where the funds for the transfer will be withdrawn.
from.type	string	YES	Set “WALLET” to collect funds for transfer from your currency wallet.
from.amount	object	YES	Define funds you want to withdraw.
from.amount.currency	string	YES	Define the funds currency you want to withdraw. Currency uppercase ISO 4217 code. Supported currency codes are described in Currencies dictionary.
from.amount.value	number	YES	Define the amount of funds which will be withdrawn from your currency wallet to make a transfer. This field should be used interchangeably with the field “value” from section “to”. 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 Currencies dictionary.
to	object	YES	Define the destination of a transfer.
to.amount	object	YES	Define how much funds want to transfer to the recipient.
to.amount.currency	string	YES	Define the funds currency you want to transfer to the recipient. Currency uppercase ISO 4217 code. Supported currency codes are described in Currencies dictionary.
to.amount.value	number	YES	Define the amount of funds which will be transferred to the recipient. This field should be used interchangeably with the field “value” from section “from”. 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 Currencies dictionary.
to.recipient	object	YES	Define recipient of transfer.
to.recipient.type	string	YES	Define “IBAN” to send a transfer to the recipient bank account.
to.recipient.id	string	YES	Define recipient ID to which you want to send the transfer.
to.recipient.message	string	NO	Define transfer message to recipient. Length: - when "to.amount.currency" == 'CNY' then 5 to 66 characters. - for others currencies 5 to 75 characters.
to.recipient.natureOfPayment	string	NO	Required only when sending funds in CNY currency. Supported values described in Nature of payment dictionaries.

Response headers

Name	Value	Description
SCA-Required	true	Indicates if Strong Customer Authentication request is required.
HTTP/1.1	201	Response status.
Content-Type	application/jose+json;charset=UTF-8	Response content type.

Response body

Field name	Type	Required	Description
sca	object	YES	SCA data.
sca.authenticationId	string	YES	SCA authentication identifier.
sca.challengeId	string	YES	SCA challenge identifier.
sca.payload	object	YES	Response payload.
sca.payload.publicId	string	YES	Transfer identifier. Max 30 characters.
sca.payload.creationDate	string	YES	Time when transfer was created. In ISO-8601 format:YYYY-MM-DDThh:mm:ssZ
sca.payload.recipientType	string	YES	Type of recipient, defined in request field to.recipient.type. Max 31 characters.
sca.payload.recipientName	string	YES	Name of recipient. Max 128 characters.
sca.payload.recipientData	string	YES	Recipient account number. Max 128 characters.
sca.payload.remitAmount	object	YES	Transferred funds.
sca.payload.remitAmount.currency	string	YES	Currency code of transferred funds. See Currencies dictionary.
sca.payload.remitAmount.value	number	YES	Amount of transferred funds. 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 Currencies dictionary.
sca.payload.exchange	object	YES	Transferred funds.
sca.payload.exchange.rate	number	YES	Currency exchange rate
sca.payload.exchange.rateInverted	number	YES	Inverted rate (scaling/rate)
sca.payload.exchange.scaling	number	YES	Currency exchange scaling
links	object	YES	Section with links.
links.scaConfirm	object	YES	SCA confirmation link section. To confirm SCA signed payload must be used as request body.
links.scaConfirm.href	string	YES	SCA confirmation address.
links.scaConfirm.method	string	YES	SCA confirmation http method.

Confirm create transfer (SCA)

Resource

PUT <CONOTOXIA_HOST>/sca/authentications/{authenticationId}/challenges/{challenge}

Example Request

curl -X PUT \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     "<CONOTOXIA_HOST>/sca/authentications/{authenticationId}/challenges/{challenge}" \
     -d "@data.json"

data.json
{
  "signedPayload": "eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.eyJwdWJsaWNJZCI6Ik1UUjIyODAyODQyNDY5MDE4ODUiLCJyZW1pdEFtb3VudCI6eyJ2YWx1ZSI6OTkuOCwiY3VycmVuY3kiOiJQTE4ifSwiZXhjaGFuZ2UiOnsicmF0ZSI6NC41MjQxLCJyYXRlSW52ZXJ0ZWQiOjAuMjIxMDM4LCJzY2FsaW5nIjoxfSwiY3JlYXRpb25EYXRlIjoiMjAyMi0xMS0yMlQxNzowNTowOC42NDUwNDFaIiwicmVjaXBpZW50VHlwZSI6IklCQU4iLCJyZWNpcGllbnROYW1lIjoiQWRhbSBOb3dhayIsInJlY2lwaWVudERhdGEiOiJQTDM2MTA5MDI0MDI2NTczODEyMjc1Mzg4ODg3In0.kJ6c12SYbvR-xyy0m4AgUGaHxtfgawqIT2o1XqIz90uCnLtd68jyjcjoiyDMqklIiOV8G5dHrBPatUDUsE0Vaz7b9FQqVpFbEsmMFpzNm3ffRYBoi_ws5caxiGxIXaOFLFZMYtTFCjGLCS7NzZmG4eA5001TJkfSOGgj0VQ5xj_zVWazhO05SqwZ9cyQ1JsRR22VXbukSPRYsyfBJlAMJyrStKCIhov5dO1QYGLavxqauPNSYyOmfjUBz1dBTb91sr8ndLoV4x9UV8R4eVc0rUzG9wlCCrQrbZygi7eljQ-DLhM79tTHQUsIgzLlmWBjTgmOBWaOu9bjoPa9HN7kig"
}

Response headers:

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

Example Response

{
  "id": "MTR1981827189489179"
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJpZCI6ICJNVFIxOTgxODI3MTg5NDg5MTc5Igp9Cg.PzOkigNLsamWSMTk6CrNjFARWeMGFsw0Jsd1AkzQ73PVJXvXcejtJVtYURSADQY1VfBtmF6yw_5ibIdOnwxgfRsFqPQBjhEbJxPmamf8jDezqLhsRwJ7LMpNwPcjHrTiS5jDIKz2AfcGVWsX7dwEa9QNXd7URJIBqWNyRfEfMPNAMkLl-0HmoxOodjC6oSYr5oO_SFKLkASIlrFpwBufA7KEtuEmr6Ypithe_gN9-Q51P7UGfNcV6MgUZ_nzt8uzyY1FcSNo4JisQYuu9tfnpcwz7xNup2c18X0Z5p9Tyje_UC1QdyHK68_sLPJsFwmFwuRRNOQkICussfqVrJHFWQ

The REST API method allows you to SCA confirm created transfer.

To confirm create transfer, execute the API method defined in the links.scaConfirm section of the response from the create transfer method. In the confirm request body the signed content of the sca.payload field from the response of the create transfer method should be provided.

Resource

PUT <CONOTOXIA_HOST>/sca/authentications/{authenticationId}/challenges/{challenge}

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in the Authorization chapter.
Content-Type	application/json	Format of request body data.

Request body

Field name	Type	Required	Description
signedPayload	string	YES	Signed JWS payload

Response headers

Name	Value	Description
HTTP/1.1	200	Response status.
Content-Type	application/json;charset=UTF-8	Response content type.

Response body

Field name	Type	Required	Description
id	string	YES	Identifier of added money transfer.

Getting status of transfer

Resource

GET <CONOTOXIA_HOST>/v1/money_transfers/{id}/status

Example Request

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/v1/money_transfers/{id}/status"

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/v1/money_transfers/{id}/status"

Response headers:

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

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

Example Response

{
  "status": "PROCESSING"
}

    eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJzdGF0dXMiOiAiUFJPQ0VTU0lORyIKfQo.rEua8mZIb5Dq8eKBGtXojOaeQI8nOLvii4XRa3zbSavdnZOpLWAHSt14np1BjuGmrqhW_BP1YhwikMw4_MRYQihInrw3elINQtXWHOKpFAj_Rm5CTEaY9LXb1U5xlPFAnHAK7kkF2RLzFTYzQ8_6hvgGDvuGgZMnQ5yIQCgfFDdth4ZJnitFrtZR8ll63tvbtEKFFWSNKqdGRnICKtXAaPLJegTjwhuXhF9iLf-EK_78KNFfsI7xhnuaWyWRU4zrhFw5Q78UxZ3_x8x0SSXrv-iAZi_9yzGOEsUbQh0f20PHJYwHycmqato8ndEgiUCvrNWtSavk7kbAmkoe9NaaZg

Resource

GET <CONOTOXIA_HOST>/v1/money_transfers/{id}/status

id - Identifier or external identifier of transfer

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization documentation.

Response

Field name	Type	Required	Description
status	string	YES	Status of transfer transaction. Described in the Dictionaries chapter.

Getting list of transfers

Resource

GET <CONOTOXIA_HOST>/v1/money_transfers

Example Request

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/v1/money_transfers"

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/v1/money_transfers"

Response headers:

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

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

Example Response

{
  "data": [
    {
      "id": "MTR123456789012345",
      "externalId": "your_external_id",
      "from": {
        "type": "WALLET",
        "debitAmount": {
          "value": 116.29,
          "currency": "USD"
        },
        "feeAmount": {
          "value": 0.23,
          "currency": "USD"
        }
      },
      "exchange": {
        "rate": 0.8616,
        "scaling": 1
      },
      "to": {
        "amount": {
          "value": 100.00,
          "currency": "EUR"
        },
        "recipient": {
          "type": "IBAN",
          "id": "1234567890",
          "accountNumber": "PL36109024026573812275388887",
          "name": "John Kowalski",
          "message": "Message to recipient",
          "address": {
            "street": "Sienkiewicza 9",
            "postalCode": "00-001",
            "city": "Warszawa",
            "country": "PL"
          }
        }
      },
      "status": "COMPLETED",
      "registerDate": "2020-09-21T13:20:11Z",
      "realizationDate": "2020-09-21T14:25:00Z"
    }
  ],
  "pagination": {
    "hasPrevious": false,
    "hasNext": false,
    "pageNumber": 1,
    "pageSize": 10
  }
}

    eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJkYXRhIjogWwogICAgewogICAgICAiaWQiOiAiTVRSMTIzNDU2Nzg5MDEyMzQ1IiwKICAgICAgImV4dGVybmFsSWQiOiAieW91cl9leHRlcm5hbF9pZCIsCiAgICAgICJmcm9tIjogewogICAgICAgICJ0eXBlIjogIldBTExFVCIsCiAgICAgICAgImRlYml0QW1vdW50IjogewogICAgICAgICAgInZhbHVlIjogMTE2LjI5LAogICAgICAgICAgImN1cnJlbmN5IjogIlVTRCIKICAgICAgICB9LAogICAgICAgICJmZWVBbW91bnQiOiB7CiAgICAgICAgICAidmFsdWUiOiAwLjIzLAogICAgICAgICAgImN1cnJlbmN5IjogIlVTRCIKICAgICAgICB9CiAgICAgIH0sCiAgICAgICJleGNoYW5nZSI6IHsKICAgICAgICAicmF0ZSI6IDAuODYxNiwKICAgICAgICAic2NhbGluZyI6IDEKICAgICAgfSwKICAgICAgInRvIjogewogICAgICAgICJhbW91bnQiOiB7CiAgICAgICAgICAidmFsdWUiOiAxMDAuMDAsCiAgICAgICAgICAiY3VycmVuY3kiOiAiRVVSIgogICAgICAgIH0sCiAgICAgICAgInJlY2lwaWVudCI6IHsKICAgICAgICAgICJ0eXBlIjogIklCQU4iLAogICAgICAgICAgImlkIjogIjEyMzQ1Njc4OTAiLAogICAgICAgICAgImFjY291bnROdW1iZXIiOiAiUEwzNjEwOTAyNDAyNjU3MzgxMjI3NTM4ODg4NyIsCiAgICAgICAgICAibmFtZSI6ICJKb2huIEtvd2Fsc2tpIiwKICAgICAgICAgICJtZXNzYWdlIjogIk1lc3NhZ2UgdG8gcmVjaXBpZW50IiwKICAgICAgICAgICJhZGRyZXNzIjogewogICAgICAgICAgICAic3RyZWV0IjogIlNpZW5raWV3aWN6YSA5IiwKICAgICAgICAgICAgInBvc3RhbENvZGUiOiAiMDAtMDAxIiwKICAgICAgICAgICAgImNpdHkiOiAiV2Fyc3phd2EiLAogICAgICAgICAgICAiY291bnRyeSI6ICJQTCIKICAgICAgICAgIH0KICAgICAgICB9CiAgICAgIH0sCiAgICAgICJzdGF0dXMiOiAiQ09NUExFVEVEIiwKICAgICAgInJlZ2lzdGVyRGF0ZSI6ICIyMDIwLTA5LTIxVDEzOjIwOjExWiIsCiAgICAgICJyZWFsaXphdGlvbkRhdGUiOiAiMjAyMC0wOS0yMVQxNDoyNTowMFoiCiAgICB9CiAgXSwKICAicGFnaW5hdGlvbiI6IHsKICAgICJoYXNQcmV2aW91cyI6IGZhbHNlLAogICAgImhhc05leHQiOiBmYWxzZSwKICAgICJwYWdlTnVtYmVyIjogMSwKICAgICJwYWdlU2l6ZSI6IDEwCiAgfQp9Cg.l6kHQEL-3taa1-Cp7Xi9RkqTS6CkNllnF7R3s0K3fVHovdknUtyN0pnz3f-y-Sip5eb4iTwKxKZjTeh-4xPEY3uv66GjLZgkMfIOFMuM4W6otOQhTen4CdQdDRrqzbg0X8JFgA071ZVz7sWVokfZ-1Pdeig7AiA9Ydv9IFCRJVhnkdBvI8djGAAMz_aInZPl0Y_RX5-S5i8xQko5BUj0cAwVTb1uOx868Mi3W2StvE6K0HRC0_PTnfNAK9EJg16nj5zMoLfXIjhAF1VjMECgXcUtYyWTTYr1W9oJwXST9h3MeYZOP5MDE4I2J_sD-eTesqzG4P-3j6sKJCgihGctVQ

Resource

GET <CONOTOXIA_HOST>/v1/money_transfers

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization documentation.

Query parameters

Field name	Type	Required	Description
id	string	NO	List of transfer IDs.
externalId	string	NO	Unique external transfer ID. Max 50 characters.
registerDateFrom	string	NO	Time of register transfer (from). In ISO-8601 format: YYYY-MM-DDThh:mm:ssZ
registerDateTo	string	NO	Time of register transfer (to). In ISO-8601 format: YYYY-MM-DDThh:mm:ssZ
realizationDateFrom	string	NO	Time of transfer realization (from). In ISO-8601 format: YYYY-MM-DDThh:mm:ssZ
realizationDateTo	string	NO	Time of transfer realization (to). In ISO-8601 format: YYYY-MM-DDThh:mm:ssZ
pageNumber	number	NO	Page number. Integer.
pageSize	number	NO	Number of elements on single page response. Integer.

Response

data array containing the list of transfers

Field name	Type	Required	Description
data	array	YES	List of objects of the Transfer type.
pagination	object	YES	Information of response pagination Pagination

Transfer object containing transfer details

Field name	Type	Required	Description
id	string	YES	Transfer identifier. Max 30 characters.
externalId	string	YES	Transfer identifier defined by you. Max 50 characters.
status	string	YES	Status of transfer. Described in the Dictionaries chapter.
registerDate	string	YES	Time when transfer was registered. In ISO-8601 format: YYYY-MM-DDThh:mm:ssZ
realizationDate	string	NO	Time when transfer was realized. In ISO-8601 format: YYYY-MM-DDThh:mm:ssZ
from	object	YES	Information about source of transfer.
from.type	string	YES	Information from where the funds for the transfer were obtained. Max 31 characters.
from.debitAmount	object	YES	Funds debited for transfer.
from.debitAmount.currency	string	YES	Currency code of debited funds. See Currencies dictionary.
from.debitAmount.value	number	YES	Amount of debited funds. 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 Currencies dictionary.
from.feeAmount	object	NO	Fee charged for transfer.
from.feeAmount.currency	string	YES	Currency code of charged fee. See Currencies dictionary.
from.feeAmount.value	number	YES	Amount of charged fee. 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 Currencies dictionary.
exchange	object	NO	Exchange rate data.
exchange.rate	number	YES	Rate of currency exchange. Decimal with support for 4 places after the decimal separator (a dot (.) is used as the decimal separator).
exchange.scaling	number	YES	Rate scaling (1 or 100) of currency exchange.
to	object	YES	Information about destination of transfer.
to.amount	object	YES	Transferred funds.
to.amount.currency	string	YES	Currency code of transferred funds. See Currencies dictionary.
to.amount.value	number	YES	Amount of transferred funds. 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 Currencies dictionary.
to.recipient	object	YES	Recipient data.
to.recipient.type	string	YES	Type of recipient. Max 31 characters.
to.recipient.id	string	YES	Identifier of recipient. Max 50 characters.
to.recipient.accountNumber	string	YES	Recipient account number. Max 128 characters.
to.recipient.name	string	YES	Name of recipient. Max 128 characters.
to.recipient.message	string	NO	Message to recipient. Max 256 characters.
to.recipient.address	object	YES	Recipient address.
to.recipient.address.street	string	YES	Street. Max 128 characters.
to.recipient.address.postalCode	string	YES	Postal code. Max 45 characters.
to.recipient.address.city	string	YES	City. Max 45 characters.
to.recipient.address.country	string	YES	Country. ISO 3166-1 alpha-2 country code.

Pagination object containing metadata of the returned transfer data page

Field name	Type	Required	Description
pagination.hasPrevious	boolean	YES	Information that the previous page exists.
pagination.hasNext	boolean	YES	Information that the next page exists.
pagination.pageNumber	number	YES	Number of elements on page. Integer.
pagination.pageSize	number	YES	Page size. Integer.

Dictionaries

Status

No.	Status	Description
1.	NEW	The transaction is waiting for SCA confirm.
2.	PENDING	The transaction is waiting for the payment of funds to cover the transaction.
3.	PROCESSING	The transaction is in progress.
4.	WITHDRAWAL_ORDERED	The funds from the transaction are paid to the recipient.
5.	COMPLETED	The transaction was completed.
6.	CANCELLING	The transaction is being canceled.
7.	CANCELLED	The transaction has been canceled.
8.	REFUNDING	The funds from the transaction have been refunded by the recipient's bank.
9.	REFUNDED	After the funds were returned from the bank, they were credited to the sender's currency wallet.

Currency

No.	Currency	Currency code	Fraction digits	Minimal amount transfer to IBAN
1.	United Arab Emirates Dirham	AED	2	10
2.	Australia Dollar	AUD	2	10
3.	Bulgaria Lev	BGN	2	10
4.	Canada Dollar	CAD	2	10
5.	Switzerland Franc	CHF	2	10
6.	China Yuan Renminbi	CNY	2	10
7.	Czech Republic Koruna	CZK	2	100
8.	Denmark Krone	DKK	2	100
9.	Euro	EUR	2	10
10.	United Kingdom Pound	GBP	2	10
11.	Hong Kong Dollar	HKD	2	10
12.	Hungary Forint	HUF	0	1000
13.	Israeli New Sheqel	ILS	2	10
14.	Japan Yen	JPY	0	1000
15.	Mexican Peso	MXN	2	10
16.	Norway Krone	NOK	2	100
17.	New Zealand Dollar	NZD	2	10
18.	Poland Zloty	PLN	2	1
19.	Romania New Leu	RON	2	10
20.	Serbian Dinar	RSD	2	100
21.	Russia Ruble	RUB	2	100
22.	Sweden Krona	SEK	2	100
23.	Singapore Dollar	SGD	2	10
24.	Thailand Bat	THB	2	100
25.	Turkey Lira	TRY	2	10
26.	United States Dollar	USD	2	10
27.	South Africa Rand	ZAR	2	10

Nature of payment

No.	Status	Description
1.	CCTFDR	Cross Border Capital Transfer
2.	CGODDR	Goods Trade
3.	CSTRDR	Service Trade
4.	COCADR	Others Current Account Transactions

API errors - technical

Description of errors returned by Conotoxia 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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJCYWQgUmVxdWVzdCIsCiAgInN0YXR1cyI6IDQwMCwKICAiZGV0YWlsIjogIlVuZXhwZWN0ZWQgY2hhcmFjdGVyICgnZicgKGNvZGUgMTAyKSk6IHdhcyBleHBlY3RpbmcgY29tbWEgdG8gc2VwYXJhdGUgT2JqZWN0IGVudHJpZXMiCn0K.aqKQ7MYMrV_EduhtErA131uAszFsyU5IQsMX9ixuKKXAx1LuyvhU51rTOr0nio0Wk1Dk8w2pztyJuKt_qWyr3XcDmZtuRbS0yrbmkUyzh-nKToA93YtWhwiASoGcafIDkHqGM3gr3DmhybfzFNW-5kpfNa0W7yE8TXx3HxZLclfp10yKfOdF0OvNwJ7OEWZ-oPbhj0Zer9bbxM_qtEQui9kKQnt0cKuGlzv75jY4J4_7jD6ASanBb718cfi0zCLT3yPRWjAfmF7Fw3S9zRUeyve8DobDs6aysp-CjqZ6QrlYfYz1KLQteJtzAYb9adjAZdFCw58_1z4cHvjKLlt71w

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJVbmF1dGhvcml6ZWQiLAogICJzdGF0dXMiOiA0MDEsCn0K.h8aLGDXvIOL0POM0zHsM91FNtN7vU_ZZxAq0s8be7EnAVFHDZLt0qLsBdsVY-R6S7qf_sCBSse9sKMnhRo1EDlXN1_cfU758GH_rZTfgXAdQmiDOt2d1gxD95VO4ZcJ9nW0_efn7O1nY4MRHw-MxNXMtoZ-ls8JpzTMYcARyQ4IAlruSJiM2n06n16MEfD_zyAKzAEzNNOHN2nai1RLiTZKHdCk9H1nCI4tjjq35ZrhP2EaDNhzbAQSTVudncKbbJXriJUs_PpJHN5K_sSupFTFVoWEQvfor2sBsbtLyPyFUG63eqYID2ewkmJyxnHW1JzdhvrEeceyeOYil8GnRbQ

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJGb3JiaWRkZW4iLAogICJzdGF0dXMiOiA0MDMKfQo.kFe80Z8J31U-9vi3g1XFW1DRuY1fKXq-jFSCdwA8CsfCa1bvgL-dhgFP0_042_ngSnPtBvpUdVBd1AN87moe6hDFj0xmUkutvjWuDjwvJE6QYVQnuuFvGRJttyoi909kOOoKHDbZo9H6GdYd-B5btw4odPwtdQFadNm8TCW_YwEqaW4BX4tgNZ4pAzG_NGXwxTazTxoJ4sQSutHff9fu7MCzpx8Zh9gB6vfaK61YWOR1gTfstvF5_LNQ1f3d_VGx3rybO9Q0mz5hOsSxtrDTAT9von4kTBCTXy297GUQ_u7y-ZLHRvMa7v2bUZPg320-NdhOGnGtqR_U2YlD4e9ySw

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJNZXRob2QgTm90IEFsbG93ZWQiLAogICJzdGF0dXMiOiA0MDUsCiAgImRldGFpbCI6ICJSZXF1ZXN0IG1ldGhvZCAnUFVUJyBub3Qgc3VwcG9ydGVkIgp9Cg.UoepUd1CRzsk5MYCnXFO1Szp2qQSsGMJsctNwCP-oSCcnqK5fFLdFcl4I0oCB_cDM2jxtxk_aMIplqurrZewbWZkurNtuAu410HZa9XqzSyXXwS8_BWT92ZNxh0j4sU9tM0I0D4zGeOiTco0RW2R-uxghu_RdED64ffz55QiaGxgnJ51EUaBqrTk1HBDJqFD76vF7FV7AUTnXvPLIKw0hr3RQK7PLkSHPnYzLgTpmngJE1iW_7hZq4Fx5EHCWPE0t03LpzqfgXcucazv_WX1SWTx7CIaR_abK_rTQB36y8vIret6RBA76l3nu2KJc1UMyMloeTJTHkwREGIOGAi5Rw

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

Example Response

{
    "title": "Conflict",
    "status": 409,
    "detail": "Currency from to.amount is different than the currency of defined recipient account"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJDb25mbGljdCIsCiAgInN0YXR1cyI6IDQwOSwKICAiZGV0YWlsIjogIkN1cnJlbmN5IGZyb20gdG8uYW1vdW50IGlzIGRpZmZlcmVudCB0aGFuIHRoZSBjdXJyZW5jeSBvZiBkZWZpbmVkIHJlY2lwaWVudCBhY2NvdW50Igp9Cg.Eqf1YkztooDUSQCH1tJEv7rXsK8xoTj8IV-v7ZmxqhwAylMCBbR2_IU9QnR6nO8KVvyOTaPbPDZWdMMpBj7M1UZRjRyCtI9Rl4wnXNqbjmg0xIObL00MFEGzQrf8xCVLA8NWD5eVeEsKPw98HEfucvOKIAVbAAcLR9XT1KvTnWICfi4WQWyfJ8F-UrcOcLy8UacwGLtBqUJYftIWraExHf6r4X8bOlih1NvvYL9kYFPUeaT9w70UtLw7jlVqdAU6YZNQo0qtkW5ia1tN0WIxKNti3Av7eXpishGxNsaPWQxsgtqN4KKcTy2-MyjQRynh89eVGbjQ7PgacAIav7hSWw

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJVbnN1cHBvcnRlZCBNZWRpYSBUeXBlIiwKICAic3RhdHVzIjogNDE1LAogICJkZXRhaWwiOiAiQ29udGVudCB0eXBlICdhcHBsaWNhdGlvbi94LXd3dy1mb3JtLXVybGVuY29kZWQnIG5vdCBzdXBwb3J0ZWQiCn0K.M1u8nmjVjInC4fhzhhS_iOeXvT_G-lRm2fAcbQTTMIfx8z9CHYulK6C06NSoCweqAsW7RPuTj2KhZof-TEg4e3p1pG__aHJd2aMmpLIcWSUXFlZBmqT86j6qvoReuxmq3bO35LFL_4w1ebJ7I7Rz9mI96Zm7h3VfrzaGtYkbRO1PtBstvMp-5BFmLVhSnqgtijCmVF24Kz54DGpcTOUPSxoUPqJXVddXXBwufCRWx0LYWZ-kZkjsomcazcHelxxVjltwlrlqF-QewFcoFb9Agdf92bEU7Zahbgdj4vFcFDwU83E2TffGuzqEsws4RGAo9bdcLfjd_-eSeOAexeh9Ig

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJJbnRlcm5hbCBTZXJ2ZXIgRXJyb3IiLAogICJzdGF0dXMiOiA1MDAKfQo.e1kg08PJWBRc0r4skb_bRDIzhSVbZypHF0gT7V8-WjmCHpTpuJG1Nss6td1zcIHsq3Cf4v1W0Pe8FIC-evb8ubOFiZf3m8zpk1zF5_v809dLu7QAhe8P2xeLCB5mntGAPVbwN7b6B4vtISy7L0aThpzBQV6zKZC6NNX__JyfKnSafSqh-oSIJWlcQaawv-ORsSjtCDIchBkvZrqVwdnqj5Ea07r9kUWtP8FD_EAopDSA2_YQDhvuOJ-XCdYao0D6wCbhHFwDlCPlQsi0rFLovHl6YiJdfT1UX745CtIsAFUCK4G2Rn_onKE9_EZFtHVPkp9ACbNOMHjuEHJ-ILYDNw

An unexpected error occurred.

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJTZXJ2aWNlIFVuYXZhaWxhYmxlIiwKICAic3RhdHVzIjogNTAzCn0K.piivBKphgtTsFMjAEVIwFqO25R0lDwXSogRcWDpGL9QU5T43FlMX4s06D456fDzGNjdFhThy5w1XkgUXwOpL3kS1L3Z58KXcULte_EF7_gIs7l34Q37Ed6Ie5LuzKHScHswWV9HWfoie3xwf9c_Xe_gxoVWX8S7vXkUA8Ejwkd_da7xiXz5sD_PDGPf2lKHiFXTc4IVFNouSkjNEKhmjp6aytEPSj-gj3NAKjL9zviMe9e_dorkyp8QGcIhsAOU4Gw2frP4ydPsZE6HAseK5o8t56Y9Z8OQbOuMwdJsWyiWCHKknOgCID5arXVxfbjeo71voTnX90TxZ2CGiHcrIQQ

Service is not available.

API errors - business

Description of errors returned by Conotoxia 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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImludmFsaWQtandzIiwKICAic3RhdHVzIjogNDAwLAogICJ0aXRsZSI6ICJJbnZhbGlkIEpXUyIsCiAgInZhbGlkYXRpb24tZXJyb3JzIjogWwogICAgewogICAgICAibWVzc2FnZSI6ICJIZWFkZXIgJ2tpZCcgaXMgbWlzc2luZyIsCiAgICAgICJtZXNzYWdlLWtleSI6ICJLaWRIZWFkZXJNaXNzaW5nIiwKICAgICAgImNvbnRleHQta2V5IjogImp3cyIKICAgIH0KICBdCn0K.lKX99YN0Z3uzdisA2ZR3RCCAZzLT-AFlJvh4722PfGkxBk7HTNFN1pQQftLqGTUzJrJPWKE8dPkybULQ8ed3f-AZUAm-vsdvjLH6mdTPmAGV_xBaw_H564f4xt-EsEeRuggykqqEVwm-OuuRp4uC9wDN26p9-MAGVmvBljZH63E7V3o02M2XMGe3t1NUJJqkLyfCEEdxhLNLPjjKWWZNbY9DhLGW7Z31a51E6dUKb6ugIIm2INCDF5UCQl2XtIfbi5HpUbVTj1hoxveYO0hebbspIPhUeRHCh2O9N1BA_doNtk7zp_a2k59p98Wm-JJnfBsgILsLmCW640y5eX3wbA

Returned when the format of the JWS request is incorrect:

• header kid is missing (message-key: KidHeaderMissing),
• header alg is missing (message-key: AlgHeaderMissing),
• header alg contains unsupported algorithm (message-key: UnsupportedAlgorithm).

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImludmFsaWQtcGVtIiwKICAic3RhdHVzIjogNDAwLAogICJ0aXRsZSI6ICJDYW4gbm90IHJlYWQgcHVibGljIGtleSBmcm9tIFBFTSIsCiAgImRldGFpbCI6ICJDYW4gbm90IHJlYWQgcHVibGljIGtleSBmcm9tIFBFTSIKfQo.EVkuM9ARnwFLxQI8D4sTN0RTBM3j0cjW0Tkj5tPX8R3N7_Xd2TwPrsTdw_1-E-kcDb8d7UN0mUUVa-l7FGdwvNKp1W8HHsxSLBKfRZGzIQH0iwrFfi_IKLGA2c1lgNO6g0EMFX-CuK-Q9_0g2kPl4tY6pp5Ffs56cH-RVftJzfCAG-CfeVNMOEj9jf1d1127T-yfdzVVVP6utigLKSOgsCYbRzI8m0bEt6R6BZVsYxhuGF571VuAMi-cnOJ8ScxRkqRcNUAM4UskGO5WvZYRqVepVQSa9cYuPaTxvLyyQtdWh1egmgsVbPrYWBFTfb5Kwh898gdnzSV9DTEsaSZ0MQ

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImludmFsaWQtcHVibGljLWtleSIsCiAgInN0YXR1cyI6IDQwMCwKICAidGl0bGUiOiAiSW52YWxpZCBwdWJsaWMga2V5IiwKICAiZGV0YWlsIjogIkludmFsaWQgcHVibGljIGtleSIKfQo.C2LdPezNwMytnd5LcpFEfPraqA9V-0GJPnnEIvltynTq2dzDeE37jyTbd85nxeH-EmpYU1Hm2JYhmyHZ_yRLMe9qhuocfPvsjNVVnbEuZ2dBcTG8aQ2v_02aUOApkO71WZ9rAhkGEQb2yW1wNAEf1c0lHomCaTZ7SX_6YcASRVoRLsrBPXj_fOcuc-9lQ7JAftFm51YjVN7QurwNov1iMVw_zf_ihoWSkGvhKF86_p5Biih5HAl6iMwN4K68m3ezRTZ1TEBmUpvwXn141t6f0SN9KKcNURuXAiyHf-pt2OSF9fZLJdRNJBKU5XuGCpEsmZHyXBPmPYOwku2sE_thnQ

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogInNhbXBsZS10ZXh0LXNpZ25hdHVyZS1ub3QtbWF0Y2giLAogICJzdGF0dXMiOiA0MDAsCiAgInRpdGxlIjogIlNhbXBsZSB0ZXh0IHNpZ25hdHVyZSBub3QgbWF0Y2giLAogICJkZXRhaWwiOiAiU2FtcGxlIGRlY29kZWQgdGV4dCBtdXN0IGhhdmUgc2lnbmVkIHdpdGggU0hBLTI1NiBzaWduYXR1cmUiCn0K.cWbBEnJlFHPH0NtGIICSOQBa0d2zSuWUu5Cf6BPdY_RHp0rczKnNH_vqUBBjSmVRdDytV7fysqSEgrd94tinjD3-LPVLwQrK8XpRjrWyqMy-sT6V1KEydqRbhGQj9my3C5OIcsl2Daxb6wCmfrtfjCtLFnYYYrwjobtdrCwWRkbH1GhAruST7Zw1LYF8KGRSPyLjSjXpQc7hkAmm1FNFOw_FewJxw3yxdSBavzGZoJlTXylox7qfzap6nXlTHBor-sLAfz-QZE1pjQcrEXIIs_vaD5Me8OE869gNG3xIfhLgPN8mS5N8jbSCLJS9ZWoFuQQwb6kBlS4OsxhQxrNJpg

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

Example Response

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

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogInZhbGlkYXRpb24tZXJyb3IiLAogICJzdGF0dXMiOiA0MDAsCiAgInRpdGxlIjogIlJlcXVlc3QgcGFyYW1ldGVycyBhcmUgbm90IHZhbGlkIiwKICAiZGV0YWlsIjogIlByb3BlcnR5ICdjYXRlZ29yeTEnIHdpdGggdmFsdWUgJ0VfQ09NTUVSQ0UnIGlzIHVua25vd24gZm9yIG9iamVjdCAnUGF5bWVudERhdGEnIiwKICAidmFsaWRhdGlvbi1lcnJvcnMiOiBbCiAgICB7CiAgICAgICJtZXNzYWdlLWtleSI6ICJ1bmtub3duLXByb3BlcnR5IiwKICAgICAgImNvbnRleHQta2V5IjogImNhdGVnb3J5MSIsCiAgICAgICJtZXNzYWdlIjogIlVuc3VwcG9ydGVkICdjYXRlZ29yeTEnIHByb3BlcnR5IgogICAgfQogIF0KfQo.dyf5y4QKdXJ05K5dUomxI5jZwMCmI5LCQcOxclECsXLMCvIyAXVvg0fdvCxQDWGwzTtAdvc-F9ixDo10T5PLcBiJDhS3wHeYUqcNIBY7Prx0q4ejnEoPLwBXG_nl2eU_KPrbTUymHr-GVr_34gLLKOdyBg-7knIhHyiqiicuovHmlyvYyKJ8F7a5QYxQTNki_XZRW_4bF__20AFJrccKHYYmzeIWh17GthNJ12MP6uz48dxxpKCqT-vFpq-HUl7ht4fKrJJggX6dM7H356att6XXyJAPztUratgO3jJurJCs5-d_sOYupq7VJ3aTb26qrseNIGXKjszNtBI9yGfgfg

Returned when specified request parameters are incorrect.

sender-defined-limit-exceeded

Response headers:

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

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

Example Response

{
    "type": "sender-defined-limit-exceeded",
    "title": "The user has a transaction limit",
    "status": 400
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogInNlbmRlci1kZWZpbmVkLWxpbWl0LWV4Y2VlZGVkIiwKICAidGl0bGUiOiAiVGhlIHVzZXIgaGFzIGEgdHJhbnNhY3Rpb24gbGltaXQiLAogICJzdGF0dXMiOiA0MDAKfQo.Yrlo4mNt4EKOXgBv0CJkc6vHaTPdj5LCOnCEKjeZCEFUUzd_QQRcslKv7C3lpu9LLom1fbZ4CBYQPSrmKiW9G0dvF_T7SjgZ0MLD8CMdqhAuHFR58bDPUu9EL0ss09Ny9e96iYA21x8_P9ZMAAHMiuxFBrXegBXFVXF3AzsEO5kOZ6UWjPa0_RuhgwGyZztB8J9lE-8Yx0pMMtoNzUdaToVpBBgIH9O8QQCyLykcblLdnO5p5hUOAehe1gKmGcHTWL4GexA1JscUSx53jxAAyeRSM3_FT1a4VRUClvowZxpxdPVwhMiUGT6A9YfHF2DrMzvjtfuqkJ5sERYnF44LeQ

Your transaction limit was exceeded. Log in to your profile and change it or disable.

insufficient-funds

Response headers:

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

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

Example Response

{
    "type": "insufficient-funds",
    "title": "Insufficient funds in the wallet",
    "status": 400
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImluc3VmZmljaWVudC1mdW5kcyIsCiAgInRpdGxlIjogIkluc3VmZmljaWVudCBmdW5kcyBpbiB0aGUgd2FsbGV0IiwKICAic3RhdHVzIjogNDAwCn0K.dRIwTIF9nilMpYKHGaWrPmtzuhBIEsWZQaEUPafQHJbZaDTA1q9_p_1pTC1kt_hT83e13BB79mKLCOTeqYK-BZdLI8xd_vzvKhNXRkTJsp10ShUkvN5kbW0Jb1pE5azHlAPU8HVBSYDKrYuUzBq7aW6Cnshcf0ThAO_aC9VTmlHaMXvSwziERCP_-_U_RKZzDMo_niQh6leONNyQXwfdyDoxuWiUnshgbZAOa1ZuOfcpi5rJXhGinMQgOSVYR-K1KOo3z_TsZUNiEiYZ7DOtna0ZNb8A_nWT6D0xUcX6gDiR0-KlPAKqnm4Yg0Pu4ICZ7SjYoa75a7NWxKd5edtBSw

You have insufficient funds in your currency wallet to realize the transaction.

recipient-already-exists

Response headers:

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

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

Example Response

{
  "type": "recipient-already-exists",
  "status": 400,
  "title": "Recipient with defined account number already exists",
  "recipientId": "442539935797"
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogInJlY2lwaWVudC1hbHJlYWR5LWV4aXN0cyIsCiAgInN0YXR1cyI6IDQwMCwKICAidGl0bGUiOiAiUmVjaXBpZW50IHdpdGggZGVmaW5lZCBhY2NvdW50IG51bWJlciBhbHJlYWR5IGV4aXN0cyIsCiAgInJlY2lwaWVudElkIjogIjQ0MjUzOTkzNTc5NyIKfQo.F78RvmLHQnldSDhsAunJsbBJliNKSt_oEetxkvmWojIUb207qTiAwWij8Con2qI4DTTgHPsB7ThoC1kzdWsr9J7DgPZCzjJ4dR4AAnFAvMo9WtVKrfl1oeo2SGrYQ8Xdq6NuNM-ymuS5KXZEdx9_ZoSC1TLRo-k_zrKS0G_bBY4idFY059BE2Chv_L9uz4oZw0tqAoLixj5p4YnsquhbZZ7lJjQdM9aSvLlb8VFCozJ0G45ktzmYU7Jgw2EESpNNx6VZuuq6vP_XvgyDKHMVmg6d8CXq_u4yP8HmtltslX5DvxWcaVedjBMH9c00kz6oYy2fQEpWXXfJpi6AO9Mn7Q

Returned when recipient with specified account number already exists on recipient list.

unsupported-currency

Response headers:

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

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

Example Response

{
  "type": "unsupported-currency",
  "title": "Unsupported currency.",
  "status": 400,
  "validation-errors": [
    {
      "message": "The given currency pair is unsupported: HRK/EUR",
      "params": {
        "value": "HRK/EUR"
      },
      "message-key": "unsupported-currency-pair"
    }
  ]
}
}

{
  "type": "unsupported-currency",
  "title": "Unsupported currency.",
  "status": 400,
  "validation-errors": [
    {
      "message": "The given currency is unsupported: HRK",
      "params": {
        "value": "HRK"
      },
      "message-key": "unsupported-currency"
    }
  ]
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoidW5zdXBwb3J0ZWQtY3VycmVuY3kiLCJ0aXRsZSI6IlVuc3VwcG9ydGVkIGN1cnJlbmN5LiIsInN0YXR1cyI6NDAwLCJ2YWxpZGF0aW9uLWVycm9ycyI6W3sibWVzc2FnZSI6IlRoZSBnaXZlbiBjdXJyZW5jeSBpcyB1bnN1cHBvcnRlZDogSFJLIiwicGFyYW1zIjp7InZhbHVlIjoiSFJLIn0sIm1lc3NhZ2Uta2V5IjoidW5zdXBwb3J0ZWQtY3VycmVuY3kifV19.PzKe6uKuU4CzNZAqwqowwc1s8PGrvD0461mjLPixm05mOAJV2q9DFr2j2DUcxjfV0HaRSJfgUiuDCXI4eNXYf1gSh8hmYQzue11wGs8wdolPSWeZISp839otZXfJzKZx5anLZxvviqz5sHLBjKYpMgsz-x-vbgtpOYjgjgqErTvBJWZ4vSERaOKtMHpRup6PiTlX4lVI5cEpCBuzmlnfxeoac4N-tD_gmHVal7TXpdprRpeZL1gKR7cokVhwFsgQ4BPOmd6OZJt7xA9KoOIHMLg-Ynu3dpU5sOg7X53k_0L5Lamx5G_H0YwQIiFm1GhO8f7Ps-KZgw5H59q_u8aliA

Returned when currency pair or currency is disabled.

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

Example Response

{
    "type": "remit-not-found",
    "title": "Remit not found",
    "status": 404,
    "detail": "Remit with identifier MTR123456789012345 not found"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogInJlbWl0LW5vdC1mb3VuZCIsCiAgInRpdGxlIjogIlJlbWl0IG5vdCBmb3VuZCIsCiAgInN0YXR1cyI6IDQwNCwKICAiZGV0YWlsIjogIlJlbWl0IHdpdGggaWRlbnRpZmllciBNVFIxMjM0NTY3ODkwMTIzNDUgbm90IGZvdW5kIgp9Cg.h9HM3Z7VKxQX0RKQDEmJg75PoiaMafbOvKrgxX0-8lI31Uw8j0D47LKyVUWsffG-goFxavkQ-9EH9Ck9SowGobc7WUj9qJFm6aKsdYArWVqIj1q64l9F30Cjb2X7qTOEdhjp696z6iuWG2510MEyY5Y7NdxRMO4ASRz0vetmkDnYyi1hXYxSbPt0htCeGwLu4zge41HZUWoUblEdVZrxzYMIwtOeBRvri17dQMEKWNCfT7Mo2r8oems9t19yB9QrpMO2zCWnGjAHfyyPNI51kYjGrNibWqenXpbjCe7Jp3ZDlzdopKbF5E-WbqgVI3hkTI4VW7ccq0wbkHp2xj_Acw

The transaction identifier is incorrect.

defined-recipient-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

Example Response

{
    "type": "defined-recipient-not-found",
    "title": "Defined recipient not found",
    "status": 404,
    "detail": "Defined recipient with identifier 1234567890 not found. Recipient type: IBAN"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImRlZmluZWQtcmVjaXBpZW50LW5vdC1mb3VuZCIsCiAgInRpdGxlIjogIkRlZmluZWQgcmVjaXBpZW50IG5vdCBmb3VuZCIsCiAgInN0YXR1cyI6IDQwNCwKICAiZGV0YWlsIjogIkRlZmluZWQgcmVjaXBpZW50IHdpdGggaWRlbnRpZmllciAxMjM0NTY3ODkwIG5vdCBmb3VuZC4gUmVjaXBpZW50IHR5cGU6IElCQU4iCn0K.M8WfvqtvkujguBdLHegYN9TbBsgfxDGKecAKYtDm3oL7W72trmTzV5j5a_2wSWawk25F_w4vSo3c8rZheH2wmNynB5xrmL6k2RI2yl80MtwKYoGxW8bDlEBD4HwXbueGvC_Z5A5S9Qdk4kiyWgZeNGm75sGw3QuXkG6eGWgJuw6r_pj2POFOy8BiSSf7UDwIQigIyRbri9lgkklxGDAgu_bW5dSuq8e7A0mHO0UnG4Uy6r5fRAdWn-x3RbET-CiAkupheSH8PweGLkFcaOwRp1y8I3hVjpX5aycB5qY9IsSxq24IUwPCAnCi9PAOsJnGH3HhCXal4apvCbEWM2s6Xg

The recipient identifier is incorrect.

incorrect-defined-recipient

Response headers:

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

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

Example Response

{
    "type": "incorrect-defined-recipient",
    "title": "Currency of defined IBAN recipient is not valid",
    "status": 409,
    "detail": "Currency of defined IBAN recipient with identifier 123456789012345 is not valid"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImluY29ycmVjdC1kZWZpbmVkLXJlY2lwaWVudCIsCiAgInRpdGxlIjogIkN1cnJlbmN5IG9mIGRlZmluZWQgSUJBTiByZWNpcGllbnQgaXMgbm90IHZhbGlkIiwKICAic3RhdHVzIjogNDA5LAogICJkZXRhaWwiOiAiQ3VycmVuY3kgb2YgZGVmaW5lZCBJQkFOIHJlY2lwaWVudCB3aXRoIGlkZW50aWZpZXIgMTIzNDU2Nzg5MDEyMzQ1IGlzIG5vdCB2YWxpZCIKfQo.Q7BMCNEnM64lLrqElE1_4UHH5TcaozsaCgkvRRezo0vwOBZWmliv_wscrSKHo7Mxy2GshJfhOcROnoXZzMGWHi10jfK6WEV2HlBSMuYZKANl9udalWosmL_6CjaRZhJpk-C8fH9GMjQBo4k4aKbVm3RaZG8fSTn1acXdDGr6Ak_isa2ETYJZ_hIiJF1thHKOw-2eeDoZHViRUEcKopUQPKVlq_GIeE-B11PQjdtSjACSpRPh_szfO7yWSvY3CGA5z1xGJoGXHg74U-DdV3vySDXrGXf6SwQ6eumRNlqbnXn-voPXe1V64wb4G8XyrvqEZzyBm4ejGyPGDxvm-o1r7Q

The recipient is incorrect.

incorrect-remit-identifier

Response headers:

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

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

Example Response

{
    "type": "incorrect-remit-identifier",
    "title": "Identifier is incorrect",
    "status": 400,
    "detail": "Text 123456789012345 is not valid remit identifier"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImluY29ycmVjdC1yZW1pdC1pZGVudGlmaWVyIiwKICAidGl0bGUiOiAiSWRlbnRpZmllciBpcyBpbmNvcnJlY3QiLAogICJzdGF0dXMiOiA0MDAsCiAgImRldGFpbCI6ICJUZXh0IDEyMzQ1Njc4OTAxMjM0NSBpcyBub3QgdmFsaWQgcmVtaXQgaWRlbnRpZmllciIKfQo.ZcdvrlS4AiRV_QIFejRn5RkG0dCwHfeYJgLKJXuQicghTUYZDDNM-vBq9NkAIJF0iHHkIkjoaC9M7Mga10fT5cHNjbOu2V5rZmw3sbtbI5O-OeYTnSCKseUZHG5ctQKtLvoayWw96GJLFVglz48PYm01phcJzacMV5TUw976Wb_r3NFAyG_rYKLyBvLIh99nTuRxlIs_zPeK-t1BMEVcyy0pryzQH6z5YHVg_fBpEDulJZ9gJ_pUyfYeyhh99_L3BBVwlMDeBkhmjMKlspiO9G-jkIYpmgHEZPZFpKDIt3LHGxma5Scfl63rFctEHjCUkFO3nzwHwCM9NNX6YMrL1w

The transfer identifier is incorrect.

regulation-not-accepted

Response headers:

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

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

Example Response

{
    "type": "regulation-not-accepted",
    "title": "Regulation not accepted",
    "status": 409,
    "detail": "Regulation not accepted by user with identifier 1234567890"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogInJlZ3VsYXRpb24tbm90LWFjY2VwdGVkIiwKICAidGl0bGUiOiAiUmVndWxhdGlvbiBub3QgYWNjZXB0ZWQiLAogICJzdGF0dXMiOiA0MDksCiAgImRldGFpbCI6ICJSZWd1bGF0aW9uIG5vdCBhY2NlcHRlZCBieSB1c2VyIHdpdGggaWRlbnRpZmllciAxMjM0NTY3ODkwIgp9Cg.iNJy6pqTu1jr36B2M8PBQQi-sq9pYYBgOO5GHvWztRQCaBRExV3qLhcnVHksm9Qib6lUYmATnXPj_avhgUBfiA0FrazA7hxx2tputnVuBUbzAyeBG3xqJyL6Z8Yct0KKnhqqIWG73kGnQR2hRSDN-qESIJUpksCSp-usqpNib8H5PaMQ5ZVMrDe2-0yC0oJM1aUG06ZpRzPMZVfpVvJ1scehzc2X3UUyAhocOpvK-PKZwj_c7CX_LogtR3fVBuyjQrsf0_idiwYtPVPRmMJiUL4BYa37QcEEofO088INb6wt0QDxLCD71J3ehIeksvOgma6BtY1KVjEi8RNL3cRMyw

The regulation of service was not accepted.

profile-problem

Response headers:

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

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

Example Response

{
    "type": "profile-problem",
    "title": "Problem with the profile",
    "status": 409
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogInByb2ZpbGUtcHJvYmxlbSIsCiAgInRpdGxlIjogIlByb2JsZW0gd2l0aCB0aGUgcHJvZmlsZSIsCiAgInN0YXR1cyI6IDQwOQp9Cg.VJJoTP7uYIIjw2CtXnU2wmhiyZkIHUVE1P28QrOW-imKh2FT1bt1g0bHDDMhnYXCqI5vYFj7_jStQg7NYp0bAldAdWbp9hgawceLzr90UeyEAY8LT0HSNBEt6gOPwn74c8Nij1-wjsJ_MUK5cbczS3XKAJ6gg8sI_2XEbE-bYgAM8dXB430wRiC7hzq5-8ho_5C_NLCyvFWx0hQ7_WoMv3cp2RXTzx9Hbu46xXyo6otTOfR1B8RdAhFjN7xLfFBl1uMvo8guf9S6jgclD_T3iFFoCJfd2zisR1AuJnLD78-GsIPUIkpO9F9ViXHMOn9nebsNrOfggXQ5wwAlmq82UA

Your user profile has a problem. Log in to your profile and check details.

authentication-already-resolved

Response headers:

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

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

Example Response

{
  "type": "authentication-already-resolved",
  "title": "Authentication is already resolved",
  "status": 409,
  "detail": "Authentication with identifier 9a2b6a27-e99f-44a2-a380-e36f970793c2 is already resolved",
  "message": "This action has already been confirmed."
}}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogImF1dGhlbnRpY2F0aW9uLWFscmVhZHktcmVzb2x2ZWQiLAogICJ0aXRsZSI6ICJBdXRoZW50aWNhdGlvbiBpcyBhbHJlYWR5IHJlc29sdmVkIiwKICAic3RhdHVzIjogNDA5LAogICJkZXRhaWwiOiAiQXV0aGVudGljYXRpb24gd2l0aCBpZGVudGlmaWVyIDlhMmI2YTI3LWU5OWYtNDRhMi1hMzgwLWUzNmY5NzA3OTNjMiBpcyBhbHJlYWR5IHJlc29sdmVkIiwKICAibWVzc2FnZSI6ICJUaGlzIGFjdGlvbiBoYXMgYWxyZWFkeSBiZWVuIGNvbmZpcm1lZC4iCn0K.s1dm28yuYuMVwZ0bmtp05jt0G-oPSquLzRENbRyoqhtM9rt88vIkvhTejpDvWz3Ih2jjG-3GTFQDToza9BU1rmSUoDph_6OaM_UVC_FDCvY5ub5DsMWQ3kx1ISet-JR2SrTc6RLmXndg2ZgnRHxlmfrI7nSGvs219jkqeHoymGfvGaczRs90LOf9IPgjPBXc4qWoftuxZ6ZeeGaWpeBWMxdl_X2wa3FEDUl-2Rv7-FwPeXKZ8fFU5E7HtHDJ92hajyH8VwQNFnFypMuybFwIf4zNnD-ql1Iyw0699DuwynLEeNemNkkYXWRgktB1b0G4uHLoJ4JJ7dHTZyuYzfOnhA

The regulation of service was not accepted.

challenge-expired

Response headers:

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

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

Example Response

{
  "type": "challenge-expired",
  "title": "Challenge was expired",
  "status": 409,
  "detail": "Challenge of type JWS was expired",
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogImNoYWxsZW5nZS1leHBpcmVkIiwKICAidGl0bGUiOiAiQ2hhbGxlbmdlIHdhcyBleHBpcmVkIiwKICAic3RhdHVzIjogNDA5LAogICJkZXRhaWwiOiAiQ2hhbGxlbmdlIG9mIHR5cGUgSldTIHdhcyBleHBpcmVkIiwKfQo.JpW-OKZUbPr_6LEk-4i6NL6MS0FL8rQ3Pk2zXgezTdb8qMeXjFiImrJx4Xuwk5OZKs8X5OnRbGuSSHbBNc1VlsYWXI3-o6YsfQGbHUY0rWOtouZ3Mv0riVckchuKQyyugsXw0DAKyVmxtnGp4SVUD64MnHXfejnVWTz01iXt8Em_J2wrS0Qs3LgeBPernGBMr6eDhOGOHYq4GiCYeS18CS2__R_YF3Tw4HL6jGXGYKlZTjXFdU4GzxBWnL4Py0OW06TC4167G6uTB33btL-12FzjviKoxkjA6brzylralMZkkxL1Jm6chn39Yd3l1d-6wmTfJyJL3UMWmlMsDru-6w

The time to approve the transaction has expired

incorrect-payload

Response headers:

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

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

Example Response

{
    "type": "incorrect-payload",
    "title": "Incorrect authentication payload",
    "status": 409,
    "detail": "Provided authentication payload is incorrect",
    "lastAttempt": false
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogImluY29ycmVjdC1wYXlsb2FkIiwKICAidGl0bGUiOiAiSW5jb3JyZWN0IGF1dGhlbnRpY2F0aW9uIHBheWxvYWQiLAogICJzdGF0dXMiOiA0MDksCiAgImRldGFpbCI6ICJQcm92aWRlZCBhdXRoZW50aWNhdGlvbiBwYXlsb2FkIGlzIGluY29ycmVjdCIsCiAgImxhc3RBdHRlbXB0IjogZmFsc2UKfQo.S9fWBFsnXu9e-HmHJEpohO9VPCwitGNIMhO6kxC--IVfUpesrMPAvf5YPnjkJvRe9ASBi-XmbGGpbGA1ZUubeqxqXMndyNhL9eIVQDGgqG7ZJBmhEjIclV6jBpgKrO5pJBMjfr7JygP3O8E_aaoVB-niSODsqhvoXZpR_Q4tMj9v1hwnBUIfdHpBJEhWzfwZ2XYyJOnBQe4_14VkGu97j_R-tHuis-VUON2LxqpC_sKiPC3-sg5dccG45askwDaYn6vXWKcxNh7DeXJVAUlc7i72gKE2NdZ7yhputWg2AB4mu1Hcu3G8I39Tyuw4Rt8gNMGcwwbKnqgVHijajk3uUw

The authentication payload is incorrect.

duplicated-external-id

Response headers:

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

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

Example Response

{
  "type": "duplicated-external-id",
  "title": "Duplicated external identifier",
  "status": 409,
  "detail": "Entity Remit with defined external identifier your_external_id already exists"
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogImR1cGxpY2F0ZWQtZXh0ZXJuYWwtaWQiLAogICJ0aXRsZSI6ICJEdXBsaWNhdGVkIGV4dGVybmFsIGlkZW50aWZpZXIiLAogICJzdGF0dXMiOiA0MDksCiAgImRldGFpbCI6ICJFbnRpdHkgUmVtaXQgd2l0aCBkZWZpbmVkIGV4dGVybmFsIGlkZW50aWZpZXIgeW91cl9leHRlcm5hbF9pZCBhbHJlYWR5IGV4aXN0cyIKfQo.pjHSqe4x3VI1DUSuAXrDcD2Zc13AdExFdotha9vuLgobM3PEI_xgfGtW2RJFfjLY8qVIQt8zNpNUynnRivwDzx_xLXf0Xaf4VLhnHgm35Yc63DBy42hdDDb-b7MmaGVo8nDeGB2eZh0qfd122p9qWJd7w_VofoZTttmaO-l-4TjZVCQaEEMxP8vcTuGP01DKwnJuGLbGj3GdbpmkcA9cHVudTxsVybpaBocIlyFElDLVcJzvufGAMCvhSWWtpOoivZqt5Ay5KqB8PlkWsCyWWaRBekUmAblMrHizoOHzRIIS_08cj43l5BDkj-QsnM9_AKGgOa8txF9Tp64wbhc3yQ

A transaction with the passed external_id value already exists.
The error occurs when you call endpoint create-transfer again and enter the same value of the "external_id" parameter.

user-temporarily-blocked

Response headers:

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

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

Example Response

{
  "type": "user-temporarily-blocked",
  "title": "User is already temporarily blocked",
  "status": 409,
  "detail": "User with identifier 914344587488 is already temporarily blocked",
  "lockTime": 15,
  "lockRemainingTime": 15
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogInVzZXItdGVtcG9yYXJpbHktYmxvY2tlZCIsCiAgInRpdGxlIjogIlVzZXIgaXMgYWxyZWFkeSB0ZW1wb3JhcmlseSBibG9ja2VkIiwKICAic3RhdHVzIjogNDA5LAogICJkZXRhaWwiOiAiVXNlciB3aXRoIGlkZW50aWZpZXIgOTE0MzQ0NTg3NDg4IGlzIGFscmVhZHkgdGVtcG9yYXJpbHkgYmxvY2tlZCIsCiAgImxvY2tUaW1lIjogMTUsCiAgImxvY2tSZW1haW5pbmdUaW1lIjogMTUKfQo.j062adPHbK8d7MFbk3O87TEfZGldjCmRoe305bVJj7A3M8IC0D3uLuRJ4NJz9H13O60OejejiI_6ctgAj9UFljYs9Yc1d_s7JzfcPATdK1fXzpcp53Basx4_O-ME1wrueFzJtPAeqc05hNPFyDK4gIczcvL9rQ5qTJCPH1YzsnpQkXAZc5D8_6Wh4VDj45_dEkKQaBquAOZGMd5YtHFaKwVf_BUrLulYi3_CQuPHJ3GwM2Zfo5UnVJc1QJ8ckXwHZFnyPX3iarf7m3X2oP99hMU4EAUJSdVL8q-zyeGosiZAPTfefs8KUIHC_R2RmMpbtISlTSl5CSnVHprwgZxGCw

In the interest of account safety, we have blocked strong authentication on your user profile. Try again in "lockRemainingTime" time.

user-permanently-blocked

Response headers:

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

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

Example Response

{
  "type": "user-permanently-blocked",
  "title": "User is already permanently blocked",
  "status": 409,
  "detail": "User with identifier 914344587488 is already permanently blocked"
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJ0eXBlIjogInVzZXItcGVybWFuZW50bHktYmxvY2tlZCIsCiAgInRpdGxlIjogIlVzZXIgaXMgYWxyZWFkeSBwZXJtYW5lbnRseSBibG9ja2VkIiwKICAic3RhdHVzIjogNDA5LAogICJkZXRhaWwiOiAiVXNlciB3aXRoIGlkZW50aWZpZXIgOTE0MzQ0NTg3NDg4IGlzIGFscmVhZHkgcGVybWFuZW50bHkgYmxvY2tlZCIKfQo.adz7UFnLG5MMTvB8Xgg0Le7PXwEq_WLAPhqjh_0WpSTyYY37w0cnkzEXQTLmAkRjgnuQ6fYN3CfSqn5nFQcBBffuNoyDxGEo57q5bsaJpCtS_zJBhokiCmwFTBF5bHMScJxRoH_jG2GGAoknwGlAC82OJeEGzxj1aBnjnuhzKpaR3fibV1bX-am3tMB08IBVIqhzbLcfli4we5XTGZt_32-SFEAIBC8bhl3sqmoonksvzDgrZ-Iq4rbC3zWFY9UQXo9cE_z27jGAwqBYOOrrKq8egfJqIIVRpk5cbDIfwyeBZXpV9o5MMY9AQXqQAUFu8Jz4EVnJoLM9PH0V7VXeQg

In the interest of account safety, we have blocked permanently your user profile.

currency-exchange-not-available

Response headers:

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

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

Example Response

{
    "type": "currency-exchange-not-available",
    "title": "Currency exchange is not available",
    "status": 503
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImN1cnJlbmN5LWV4Y2hhbmdlLW5vdC1hdmFpbGFibGUiLAogICJ0aXRsZSI6ICJDdXJyZW5jeSBleGNoYW5nZSBpcyBub3QgYXZhaWxhYmxlIiwKICAic3RhdHVzIjogNTAzCn0K.P4Ke75cC4zIcT0YIXcG1oYCCmuCIastjyZx_EIju3Nmy-RbEFMd3fnP85fjKZxKkTT921rqNn9kuR-NzSel7KBOgviVNA5nfoqDnOpfUqVtJuAvtd3QZqXeWQDKLPA0JgDM6vMsry0p_y6TVwX-y0aveqdADLK6dqjLyR7Gq_mYnMS3ZoK-nwFx9HOEUcQxfSpXnG7XEcBZVs1ol_t6Hl15Duy_8nVeuolKERxs0dmy70D-Ilxz-4H5l_mmjNQBtyhxVOKUhHi9YZSWvAvkrndIbbgfc0Kc9h1MgHL_lI63x_WVHDAkxp64DVVWRDiKKUa0KqkYUUysZDPpPN2ytiA

Currency exchange service is currently not available.

Security

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

• all communication takes place with the use of HTTPS protocol;
• it is required to send an authorization token in the Authorization header in order to use the API (more information in the Authentication section);
• all messages sent from the Partner's system must be signed (more information in the Communication with Conotoxia section);
• all messages sent from the Conotoxia system are signed (more information in the Communication with the Partner section);
• additional data that are attached to the URL parameters are signed by Conotoxia when redirecting to the Partner's website (more information in the chapter Authenticity of URL parameters).

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:

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

JWS Header

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

JWS Payload

{
  "externalId": "your_external_id",
  "from": {
    "type": "WALLET",
    "amount": {
      "currency": "USD",
      "value": 0
    }
  },
  "to": {
    "amount": {
      "currency": "EUR",
      "value": 100
    },
    "recipient": {
      "type": "IBAN",
      "id": "1234567890",
      "message": "Transfer message to recipient"
    }
  }
}

Example of a create transfer:

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

data.jws
     eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJleHRlcm5hbElkIjogIjEwLzAxMDAvNDM0MzM1IiwKICAiZnJvbSI6IHsKICAgICJ0eXBlIjogIldBTExFVCIsCiAgICAiYW1vdW50IjogewogICAgICAiY3VycmVuY3kiOiAiRVVSIiwKICAgICAgInZhbHVlIjogMAogICAgfQogIH0sCiAgInRvIjogewogICAgImFtb3VudCI6IHsKICAgICAgImN1cnJlbmN5IjogIlBMTiIsCiAgICAgICJ2YWx1ZSI6IDEyCiAgICB9LAogICAgInJlY2lwaWVudCI6IHsKICAgICAgInR5cGUiOiAiSUJBTiIsCiAgICAgICJpZCI6ICI1MDAyNDExOTM3MTMiLAogICAgICAibWVzc2FnZSI6ICJJYmFuIHRpdGxlIgogICAgfQogIH0KfQo.PWFPdvoCF1HPPBknXcscL4-E9SaaZF7blawJa36keEZR2NmtrhMoAinYkF4D5M3ot-UHDDlJZ10yFqEWHpbTdtg9UKg8NQ5yHcEm5kjFAfigL3vJzHyvswQVT9kPSgDE3eXtu_N9uG-6qSV8byay9vK_Ylaq1jbkbd7b4Hwglc1SoSAgZbfoJ58z0HWp9aSEcHv4vJde44NA4yR_CqHtO3QMVA6u7GmnehC16MGB57uWT3cbixbXku7AynY4KOFL5kebDN_tZQapd4P853L_djTGhaPi5UwLVJOVk5XnxSTdk4h8_xYwglac_ILD9NLLD3fF94Eg2FVLYQY_DfxUSQ

Response headers:

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

Example Response

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJpZCI6ICJNVFIxMjM0NTY3ODkwMTIzNDUiLAogICJleHRlcm5hbElkIjogInlvdXJfZXh0ZXJuYWxfaWQiLAogICJmcm9tIjogewogICAgInR5cGUiOiAiV0FMTEVUIiwKICAgICJkZWJpdEFtb3VudCI6IHsKICAgICAgInZhbHVlIjogMTE2LjI5LAogICAgICAiY3VycmVuY3kiOiAiVVNEIgogICAgfSwKICAgICJmZWVBbW91bnQiOiB7CiAgICAgICJ2YWx1ZSI6IDAuMjMsCiAgICAgICJjdXJyZW5jeSI6ICJVU0QiCiAgICB9CiAgfSwKICAiZXhjaGFuZ2UiOiB7CiAgICAicmF0ZSI6IDAuODYxNiwKICAgICJzY2FsaW5nIjogMQogIH0sCiAgInRvIjogewogICAgImFtb3VudCI6IHsKICAgICAgInZhbHVlIjogMTAwLjAwLAogICAgICAiY3VycmVuY3kiOiAiRVVSIgogICAgfSwKICAgICJyZWNpcGllbnQiOiB7CiAgICAgICJ0eXBlIjogIklCQU4iLAogICAgICAiaWQiOiAiMTIzNDU2Nzg5MCIsCiAgICAgICJhY2NvdW50TnVtYmVyIjogIlBMMzYxMDkwMjQwMjY1NzM4MTIyNzUzODg4ODciLAogICAgICAibmFtZSI6ICJKb2huIEtvd2Fsc2tpIiwKICAgICAgIm1lc3NhZ2UiOiAiTWVzc2FnZSB0byByZWNpcGllbnQiLAogICAgICAiYWRkcmVzcyI6IHsKICAgICAgICAic3RyZWV0IjogIlNpZW5raWV3aWN6YSA5IiwKICAgICAgICAicG9zdGFsQ29kZSI6ICIwMC0wMDEiLAogICAgICAgICJjaXR5IjogIldhcnN6YXdhIiwKICAgICAgICAiY291bnRyeSI6ICJQTCIKICAgICAgfQogICAgfQogIH0sCiAgInN0YXR1cyI6ICJQUk9DRVNTSU5HIiwKICAicmVnaXN0ZXJEYXRlIjogIjIwMjAtMDktMjFUMTM6MjA6MTFaIgp9Cg.GLSEXXDfpH98dTb21q9pgK2p6E-dsLdnLBGhNCN91tqpgEQLJQahnWj3nsDvQLlxuweUg90ATniB29g1Z7GGQtSqu5Ax8BB3xXPig1dA6ADzW-vhW1fXejvvDV9Tl4rlaiiUp20Q8uSUP9vQ-OaB54k0JmbR7ZXSVcF1hLaBGhs7ROLV0bOkt0YmVY6FJopdDtgtmL63GCE6Ur70GoUn3e9Tl0CfoUF8lTOSVPva-BX-2Sqy_Pk12jn1KBJwMolk7Q7y9hskuNZVUj5pPre2yjY6ZJnF6bjewyZk8C1h80MSAydi4GrIo5Dw2cAkD5YTQVyb0Mh6Bp3Y_YJDQAsk4Q

All messages sent from the Partner's system to the Conotoxia Mass Transfer 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:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJleHRlcm5hbElkIjogInlvdXJfZXh0ZXJuYWxfaWQiLAogICJmcm9tIjogewogICAgInR5cGUiOiAiV0FMTEVUIiwKICAgICJhbW91bnQiOiB7CiAgICAgICJjdXJyZW5jeSI6ICJVU0QiLAogICAgICAidmFsdWUiOiAwCiAgICB9CiAgfSwKICAidG8iOiB7CiAgICAiYW1vdW50IjogewogICAgICAiY3VycmVuY3kiOiAiRVVSIiwKICAgICAgInZhbHVlIjogMTAwCiAgICB9LAogICAgInJlY2lwaWVudCI6IHsKICAgICAgInR5cGUiOiAiSUJBTiIsCiAgICAgICJpZCI6ICIxMjM0NTY3ODkwIiwKICAgICAgIm1lc3NhZ2UiOiAiVHJhbnNmZXIgbWVzc2FnZSB0byByZWNpcGllbnQiCiAgICB9CiAgfQp9Cg.B54ZENVK-53yhxpaKasrQhRr85q0rcrB6gJefffB6M_aHp5rAojNr5VFf3oo7mNW1ZvYXXYwKVXNoEldYGS_sw--wzIhAvMyNiChWsApeMvLc5NGnhryio8ykBl59bCw1eH-X7JW4nT6la_fzEZj9ZOikenJroCHdQtUT1acOAOHITyBootXOhD9qmIhgKMpYXqYMkSZ9lZsRu0K_xfavw9qL4WpSvMulI-oLXJfevTVZtHwlFSFwMu1Wsz6YgR5fAYTYyy6h7s3LdqpouPckfJ1f-dyBH17C8C0uILI9ucO1elN2R4aoqDKMedHP5b-RH3Auh2ozIHVi23D8G_wAA

After decoding JWS, a JWS Header and JWS Payload containing the minimum Transfer 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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvFDG9DP6TT3nfLFCjQu/
JKoE/dur02BZfiWMFrft6I4Vrz7xpd272jE5i409z/JkyA0pk4lSUcGbraxllgs/
us8zNpRPZMsRSDmQtwXKS7SgLrJ+eJGZ0mVWG1ESE4dyLoO3YQgo3JV7xOlCNHyi
35eycwuV6aU2nQ1GDsv8UkMwVt6kZVb/avuFbmoBsOagmMZsYGfyRg0fFMfL/C9f
tBKWX7OZsa0aGSB7Fe5qr55Se3NbvM5bDeRU9HDDUDTM+V4SDj+DVdnKZcPfOcVF
Nig6+M7fWZ397VJA/xtXrbDY1D+gpvukMgB/FXBVfmQuKRv2AwIrA/S3Ib2IwiXD
bwIDAQAB
-----END PUBLIC KEY-----

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

Generating a public key

• Linux
• macOS
• Windows

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:
   

• Distributions based on Debian (Ubuntu, Parrot OS)
  sudo apt install openssl
  

• CentOS
  sudo yum install openssl
  

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

POST <CONOTOXIA_HOST>/public_keys

Example Request

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

Response headers:

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

Example Response

{
  "kid": "lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ"
}

To enable secure communication between Conotoxia 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_HOST>/public_keys

Request headers

Name	Value	Remarks
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization documentation.
Content-Type	application/json	Format of request body data.

Request body

PublicKey object containing data on the public key

Field name	Type	Required	Description
pem	string	YES	Partner’s public key.
sampleData	object	NO	Object containing sample texts for public key verification.
sampleData.decodedText	string	YES	Sample text sent to verify the accuracy of the public key.
sampleData.encodedText	string	YES	Sample text from decodedText field signed by private key with SHA-256 signature.

Response body

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

The status field can take the following values:

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

Getting public keys

GET <CONOTOXIA_HOST>/v2/public_keys

Example Request

curl -X GET </span>
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" </span>
     "<CONOTOXIA_HOST>/v2/public_keys"

Response headers:

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

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

Example Response

{
 "data": [
   {
     "kid": "chi09N6Bog_0IvtrahDhZRGF7kiHTAhQaIm4x_wdpQU",
     "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoPYw28jrN71VoWHfSkTR\nb4v8OdYMjwZRs2dg5vPZjv0xryNAqHpHYP5+SCpEz6YRFGzuCWhqkNgSKmZgLBxv\nBVJt8YqZOtbnB4as/4TI0dy73YUmw00LYXLTcrS6al6OFtC4SehUREgoVG9V8Hlf\nx9T0bnNOW5R0z3LvkC+Y8e1Gm+xtX+K5uX00md5TI1jk5GqoE9D7cuv5mBX50Igi\nzMqbZYttu/gdA3TWD6JnceMU2WPKJDLowGN4RnUtQJQiApfRQZDPblB+9AKJkiTy\n8N4g9hAVmKbwC3cehO1vMB7ujOlJrNAXjh1rO7B3OJQ0JXcpb2UhrPZ/DIuRdLvX\n6QIDAQAB\n-----END PUBLIC KEY-----",
     "status": "INACTIVE"
   }
 ],
 "pagination": {
     "first": true,
     "last": true,
     "currentPageNumber": 1,
     "currentPageElementsCount": 2,
     "pageSize": 10,
     "totalPages": 1,
     "totalElements": 2,
     "pageLimitExceeded": false
   }
}

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

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

Resource

GET <CONOTOXIA_HOST>/v2/public_keys

Request headers

Name	Value	Remarks
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization chapter.

Query parameters

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

Response body

Data object containing the list of added public keys

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

PublicKey object containing information about the public key of the Conotoxia

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

The status field can take the following values:

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

Pagination object containing metadata of the returned page with public keys

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

Getting Conotoxia key

GET <CONOTOXIA_HOST>/jwks

Example Request

curl -X GET </span>
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" </span>
     "<CONOTOXIA_HOST>/jwks"

Response headers:

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

Example Response

{
  "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 system it is necessary to have a public key of the Conotoxia system. In order to obtain the key, the GET /jwks resource should be used.

Resource

GET <CONOTOXIA_HOST>/jwks

Request headers

Name	Value	Remarks
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization documentation.

Response body

PublicKeys object containing the list of public keys of the Conotoxia 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

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.