NAV Navbar
cURL unsigned cURL signed

Introduction

This documentation is intended for Partners who want to integrate with the Conotoxia Currency Cards system. Described integration is based on the REST API and allows ordering currency cards.

How to start?

To integrate with the Conotoxia Currency Cards system, the Partner is required to prepare the following elements:

It all is possible to obtain on configuration page.

Overview

Business processes

Card order

Bellow is described the process of ordering a currency card. It shows only the basic flow of the process.

Flow diagram

card order success diagram

Flow description

  1. Partner sends a request to load order setup.
  2. Conotoxia returns a response with the order setup details.
  3. Partner receives the order setup details.
  4. Partner sends a request to create an order for a card.
  5. Conotoxia creates a card order.
  6. Conotoxia returns a response with the card order details.
  7. Partner receives the card order details.
  8. Partner sends a request to confirm the card order.
  9. Conotoxia receives confirmation of the card order.
  10. Conotoxia creates the card, sets the order to status CARD_CREATED and sends the Partner a Card created notification.
  11. Partner receives the Card created notification.
  12. Contoxia sends the Partner a Card sent notification.
  13. Partner receives the Card sent notification.

Card preorder

Preorder is the process of creating card order for products that are in the preorder phase. The order end in status FINISHED and waits for Conotoxia to start processing preorders.

The card preorder process presented below contains a scenario with only a positive case, which aims to present the logic of the whole process.

card preorder success diagram

Scenario

  1. Partner sends a request for load order setup.
  2. Conotoxia returns a response with the order setup details.
  3. Partner receives the order setup details.
  4. Partner sends a request to create an order for a card.
  5. Conotoxia system creates a card order.
  6. Conotoxia system returns a response with the card order details.
  7. Partner receives the card order details.
  8. Partner sends a request to confirm the card order.
  9. Conotoxia system receives confirmation of the card order.
  10. Conotoxia confirms the card order, sets his status to FINISHED and waits for Conotoxia waits for Conotoxia to start processing preorders.
  11. Conotoxia starts executing collected preorders.
  12. Conotoxia system creates the card, sets the order to status CARD_CREATED and sends the Partner a Card created notification.
  13. Partner receives the Card created notification.
  14. Conotoxia sends the Partner a Card sent notification.
  15. Partner receives the Card sent notification.

Endpoints

Information about the endpoints for card order and card preorder processes. The same endpoints are used for both processes. For more information about processes, see the Business processes section.

Order setup

Resource

POST <CONOTOXIA_HOST>/multicurrency_cards/orders/setup

Example request

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

data.json
     {
       "currency": "PLN",
       "shippingCountry": "PL",
       "phone": {
         "area": "48",
         "number": "123456789"
       },
       "cardTheme": "WHITE"
     }

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

data.jws
    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUifQ.eyJjdXJyZW5jeSI6IlBMTiIsInNoaXBwaW5nQ291bnRyeSI6IlBMIiwicGhvbmUiOnsiYXJlYSI6IjQ4IiwibnVtYmVyIjoiMTIzNDU2Nzg5In0sImNhcmRUaGVtZSI6IldISVRFIn0.wyTt1trICqXB0WCzSM2lpf1_WuQ1Qev4xPaSimHiChEMIPZva_ZyNE-1ATX9EURZ1pcxcSlhbsjWagABdAeccQymYMdN1uLhn3XNDOjn_pCpUO7ftENckca8Y1PgocGPP97lHB4QnxuXaIplRufEQgwfoErTTse_T3xHPOXZKqKZQwRhlPAAyW67mczlsZwDmMlT44njxZDp55DbyIgFPwrplw69j1kWaApeOatB7snU1RNrA0XflWIra9ApcXUa3bQ2FJ4nit8L-hEcl-NMcEU4Nc1zKblfQmo-YC2aW5XvheiFOemAM-1anQ8juWxfMOwHYes8T8b1OxLsXGT0PA

The REST API method allows you to get setup of order.

Resource

POST <CONOTOXIA_HOST>/multicurrency_cards/orders/setup

Request headers

Name Value Required Remarks
Authorization Bearer {access_token} YES See how to generate access token.
Content-Type application/jose+json YES Format of request body data.

Request body

Field name Type Required Description
currency string YES Card order currency. See available currencies.
shippingCountry string YES Card delivery country. See available countries.
phone SimplePhoneData NO Phone is used for notify user about delivery status.
cardTheme string YES Card theme. See available card themes.

Response

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

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

Example response body

{
  "setup": {
    "shippingOptions": [
      {
        "type": "POLISH_POST",
        "standardPrice": {
          "value": 0,
          "currency": "PLN"
        },
        "promotionPrice": null,
        "price": {
          "value": 0,
          "currency": "PLN"
        }
      },
      {
        "type": "INPOST",
        "standardPrice": {
          "value": 13,
          "currency": "PLN"
        },
        "promotionPrice": null,
        "price": {
          "value": 13,
          "currency": "PLN"
        }
      }
    ]
  },
  "preorder": true,
  "formValidations": {
    "phone": {
      "phoneArea": {
        "required": true,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              7
            ],
            "when": null,
            "message": "Phone area should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          },
          {
            "rule": "REGEXP",
            "params": "48",
            "when": {
              "condition": "==",
              "field": "shippingOptionType",
              "value": "INPOST"
            },
            "message": "Phone area should match rule",
            "message-key": "ILLEGAL_CHARACTERS"
          }
        ],
        "options": null,
        "value": null
      },
      "phoneNumber": {
        "required": true,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              15
            ],
            "when": null,
            "message": "Phone number should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          },
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              9,
              9
            ],
            "when": {
              "condition": "==",
              "field": "shippingOptionType",
              "value": "INPOST"
            },
            "message": "Phone number should have exactly {min} numbers",
            "message-key": "ILLEGAL_LENGTH"
          }
        ],
        "options": null,
        "value": null
      }
    },
    "address": {
      "street": {
        "required": true,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              100
            ],
            "when": null,
            "message": "Address street should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          },
          {
            "rule": "REGEXP",
            "params": "^[\\u0041-\\u005A\\u0061-\\u007A\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u00FF\\u0100-\\u017F\\u0180-\\u024F\\u1E02-\\u1EF3\\u0259-\\u0292\\u0030-\\u0039\\ \\/\\-\\.\\_\\,]+$",
            "when": null,
            "message": "Address street should contain valid characters only",
            "message-key": "ILLEGAL_CHARACTERS"
          }
        ],
        "options": null,
        "value": null
      },
      "postalCode": {
        "required": true,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              15
            ],
            "when": null,
            "message": "Address postal code should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          },
          {
            "rule": "REGEXP",
            "params": "^[0-9]{2}-[0-9]{3}$",
            "when": {
              "condition": "==",
              "field": "address.country",
              "value": "PL"
            },
            "message": "Address postal code should match rule",
            "message-key": "ILLEGAL_CHARACTERS"
          },
          {
            "rule": "REGEXP",
            "params": "^[0-9a-zA-Z/-/ ]+$",
            "when": {
              "condition": "!=",
              "field": "address.country",
              "value": "PL"
            },
            "message": "Address postal code should contain valid characters only",
            "message-key": "ILLEGAL_CHARACTERS"
          }
        ],
        "options": null,
        "value": null
      },
      "city": {
        "required": true,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              100
            ],
            "when": null,
            "message": "Address city should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          },
          {
            "rule": "REGEXP",
            "params": "^[\\u0041-\\u005A\\u0061-\\u007A\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u00FF\\u0100-\\u017F\\u0180-\\u024F\\u1E02-\\u1EF3\\u0259-\\u0292\\u0030-\\u0039\\ \\/\\-\\.\\_\\,]+$",
            "when": null,
            "message": "Address city should contain valid characters only",
            "message-key": "ILLEGAL_CHARACTERS"
          }
        ],
        "options": null,
        "value": null
      },
      "voivodeship": {
        "required": false,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              100
            ],
            "when": null,
            "message": "Address voivodeship should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          }
        ],
        "options": null,
        "value": null
      },
      "country": {
        "required": true,
        "editable": true,
        "type": "LIST",
        "constraints": [
          {
            "rule": "IN_LIST",
            "params": null,
            "when": null,
            "message": "Address country should match option",
            "message-key": "UNSUPPORTED_PROPERTY"
          }
        ],
        "options": {
          "DE": "DE",
          "PL": "PL"
        },
        "value": null
      },
      "companyName": {
        "required": false,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              50
            ],
            "when": null,
            "message": "Address company name should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          },
          {
            "rule": "REGEXP",
            "params": "^[\\u0041-\\u005A\\u0061-\\u007A\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u00FF\\u0100-\\u017F\\u0180-\\u024F\\u1E02-\\u1EF3\\u0259-\\u0292\\u0030-\\u0039\\ \\/\\-\\.\\_\\,]+$",
            "when": null,
            "message": "Address company name should contain valid characters only",
            "message-key": "ILLEGAL_CHARACTERS"
          }
        ],
        "options": null,
        "value": null
      }
    },
    "location": {
      "address": {
        "street": {
          "required": false,
          "editable": true,
          "type": "STRING",
          "constraints": [
            {
              "rule": "LENGTH_BETWEEN",
              "params": [
                1,
                1000
              ],
              "when": {
                "condition": "==",
                "field": "shippingOptionType",
                "value": "INPOST"
              },
              "message": "Parcel locker street should have length between {min} and {max}",
              "message-key": "ILLEGAL_LENGTH"
            }
          ],
          "options": null,
          "value": null
        },
        "postalCode": {
          "required": false,
          "editable": true,
          "type": "STRING",
          "constraints": [
            {
              "rule": "LENGTH_BETWEEN",
              "params": [
                1,
                15
              ],
              "when": {
                "condition": "==",
                "field": "shippingOptionType",
                "value": "INPOST"
              },
              "message": "Parcel locker postal code should have length between {min} and {max}",
              "message-key": "ILLEGAL_LENGTH"
            }
          ],
          "options": null,
          "value": null
        },
        "city": {
          "required": false,
          "editable": true,
          "type": "STRING",
          "constraints": [
            {
              "rule": "LENGTH_BETWEEN",
              "params": [
                1,
                1000
              ],
              "when": {
                "condition": "==",
                "field": "shippingOptionType",
                "value": "INPOST"
              },
              "message": "Parcel locker city should have length between {min} and {max}",
              "message-key": "ILLEGAL_LENGTH"
            }
          ],
          "options": null,
          "value": null
        },
        "voivodeship": null,
        "country": null,
        "companyName": null
      },
      "code": {
        "required": false,
        "editable": true,
        "type": "STRING",
        "constraints": [
          {
            "rule": "LENGTH_BETWEEN",
            "params": [
              1,
              15
            ],
            "when": {
              "condition": "==",
              "field": "shippingOptionType",
              "value": "INPOST"
            },
            "message": "Parcel locker code should have length between {min} and {max}",
            "message-key": "ILLEGAL_LENGTH"
          },
          {
            "rule": "REGEXP",
            "params": "^[0-9A-Z-]+$",
            "when": {
              "condition": "==",
              "field": "shippingOptionType",
              "value": "INPOST"
            },
            "message": "Parcel locker code should contain valid characters only",
            "message-key": "ILLEGAL_CHARACTERS"
          }
        ],
        "options": null,
        "value": null
      }
    },
    "countryOfResidence": {
      "required": true,
      "editable": true,
      "type": "LIST",
      "constraints": [
        {
          "rule": "IN_LIST",
          "params": null,
          "when": null,
          "message": "Country of residence should match option",
          "message-key": "UNSUPPORTED_PROPERTY"
        }
      ],
      "options": {
        "DE": "DE",
        "PL": "PL"
      },
      "value": null
    },
    "shippingOptionType": {
      "required": true,
      "editable": true,
      "type": "LIST",
      "constraints": [
        {
          "rule": "IN_LIST",
          "params": null,
          "when": null,
          "message": "Shipping option type should match option",
          "message-key": "UNSUPPORTED_PROPERTY"
        }
      ],
      "options": {
        "FEDEX": "FEDEX",
        "POLISH_POST": "POLISH_POST",
        "INPOST": "INPOST",
        "DPD": "DPD",
        "DHL": "DHL"
      },
      "value": null
    },
    "cardTheme": {
      "required": true,
      "editable": true,
      "type": "LIST",
      "constraints": [
        {
          "rule": "IN_LIST",
          "params": null,
          "when": null,
          "message": "Card theme should match option",
          "message-key": "UNSUPPORTED_PROPERTY"
        }
      ],
      "options": {
        "WHITE": "WHITE",
        "BLACK": "BLACK"
      },
      "value": null
    },
    "email": {
      "required": true,
      "editable": true,
      "type": "STRING",
      "constraints": [
        {
          "rule": "LENGTH_BETWEEN",
          "params": [
            1,
            256
          ],
          "when": null,
          "message": "Email should have length between {min} and {max}",
          "message-key": "ILLEGAL_LENGTH"
        }
      ],
      "options": null,
      "value": null
    },
    "firstName": {
      "required": true,
      "editable": true,
      "type": "STRING",
      "constraints": [
        {
          "rule": "LENGTH_BETWEEN",
          "params": [
            1,
            128
          ],
          "when": null,
          "message": "First name should have length between {min} and {max}",
          "message-key": "ILLEGAL_LENGTH"
        },
        {
          "rule": "REGEXP",
          "params": "^[\\u0041-\\u005A\\u0061-\\u007A\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u00FF\\u0100-\\u017F\\u0180-\\u024F\\u1E02-\\u1EF3\\u0259-\\u0292\\ \\,\\.\\'\\-]+$",
          "when": null,
          "message": "First name should contain valid characters only",
          "message-key": "ILLEGAL_CHARACTERS"
        }
      ],
      "options": null,
      "value": null
    },
    "lastName": {
      "required": true,
      "editable": true,
      "type": "STRING",
      "constraints": [
        {
          "rule": "LENGTH_BETWEEN",
          "params": [
            1,
            128
          ],
          "when": null,
          "message": "Last name should have length between {min} and {max}",
          "message-key": "ILLEGAL_LENGTH"
        },
        {
          "rule": "REGEXP",
          "params": "^[\\u0041-\\u005A\\u0061-\\u007A\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u00FF\\u0100-\\u017F\\u0180-\\u024F\\u1E02-\\u1EF3\\u0259-\\u0292\\ \\,\\.\\'\\-]+$",
          "when": null,
          "message": "Last name should contain valid characters only",
          "message-key": "ILLEGAL_CHARACTERS"
        }
      ],
      "options": null,
      "value": null
    },
    "termsAccepted": {
      "required": true,
      "editable": true,
      "type": "LIST",
      "constraints": [
        {
          "rule": "IN_LIST",
          "params": null,
          "when": null,
          "message": "Terms should be accepted",
          "message-key": "UNSUPPORTED_PROPERTY"
        }
      ],
      "options": {
        "true": "true"
      },
      "value": null
    },
    "language": {
      "required": true,
      "editable": true,
      "type": "LIST",
      "constraints": [
        {
          "rule": "IN_LIST",
          "params": null,
          "when": null,
          "message": "Language should match option",
          "message-key": "UNSUPPORTED_PROPERTY"
        }
      ],
      "options": {
        "EN": "EN",
        "PL": "PL"
      },
      "value": null
    },
    "sourceId": {
      "required": false,
      "editable": true,
      "type": "STRING",
      "constraints": [
        {
          "rule": "LENGTH_BETWEEN",
          "params": [
            0,
            36
          ],
          "when": null,
          "message": "Source id should have length between {min} and {max}",
          "message-key": "ILLEGAL_LENGTH"
        },
        {
          "rule": "REGEXP",
          "params": "^[A-Za-z0-9#-]+$",
          "when": null,
          "message": "Source id should contain valid characters only",
          "message-key": "ILLEGAL_CHARACTERS"
        }
      ],
      "options": null,
      "value": null
    }
  }
}

eyJzZXR1cCI6eyJzaGlwcGluZ09wdGlvbnMiOlt7InR5cGUiOiJQT0xJU0hfUE9TVCIsInN0YW5kYXJkUHJpY2UiOnsidmFsdWUiOjAsImN1cnJlbmN5IjoiUExOIn0sInByb21vdGlvblByaWNlIjpudWxsLCJwcmljZSI6eyJ2YWx1ZSI6MCwiY3VycmVuY3kiOiJQTE4ifX0seyJ0eXBlIjoiSU5QT1NUIiwic3RhbmRhcmRQcmljZSI6eyJ2YWx1ZSI6MTMsImN1cnJlbmN5IjoiUExOIn0sInByb21vdGlvblByaWNlIjpudWxsLCJwcmljZSI6eyJ2YWx1ZSI6MTMsImN1cnJlbmN5IjoiUExOIn19XX0sInByZW9yZGVyIjp0cnVlLCJmb3JtVmFsaWRhdGlvbnMiOnsicGhvbmUiOnsicGhvbmVBcmVhIjp7InJlcXVpcmVkIjp0cnVlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IlNUUklORyIsImNvbnN0cmFpbnRzIjpbeyJydWxlIjoiTEVOR1RIX0JFVFdFRU4iLCJwYXJhbXMiOlsxLDddLCJ3aGVuIjpudWxsLCJtZXNzYWdlIjoiUGhvbmUgYXJlYSBzaG91bGQgaGF2ZSBsZW5ndGggYmV0d2VlbiB7bWlufSBhbmQge21heH0iLCJtZXNzYWdlLWtleSI6IklMTEVHQUxfTEVOR1RIIn0seyJydWxlIjoiUkVHRVhQIiwicGFyYW1zIjoiNDgiLCJ3aGVuIjp7ImNvbmRpdGlvbiI6Ij09IiwiZmllbGQiOiJzaGlwcGluZ09wdGlvblR5cGUiLCJ2YWx1ZSI6IklOUE9TVCJ9LCJtZXNzYWdlIjoiUGhvbmUgYXJlYSBzaG91bGQgbWF0Y2ggcnVsZSIsIm1lc3NhZ2Uta2V5IjoiSUxMRUdBTF9DSEFSQUNURVJTIn1dLCJvcHRpb25zIjpudWxsLCJ2YWx1ZSI6bnVsbH0sInBob25lTnVtYmVyIjp7InJlcXVpcmVkIjp0cnVlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IlNUUklORyIsImNvbnN0cmFpbnRzIjpbeyJydWxlIjoiTEVOR1RIX0JFVFdFRU4iLCJwYXJhbXMiOlsxLDE1XSwid2hlbiI6bnVsbCwibWVzc2FnZSI6IlBob25lIG51bWJlciBzaG91bGQgaGF2ZSBsZW5ndGggYmV0d2VlbiB7bWlufSBhbmQge21heH0iLCJtZXNzYWdlLWtleSI6IklMTEVHQUxfTEVOR1RIIn0seyJydWxlIjoiTEVOR1RIX0JFVFdFRU4iLCJwYXJhbXMiOls5LDldLCJ3aGVuIjp7ImNvbmRpdGlvbiI6Ij09IiwiZmllbGQiOiJzaGlwcGluZ09wdGlvblR5cGUiLCJ2YWx1ZSI6IklOUE9TVCJ9LCJtZXNzYWdlIjoiUGhvbmUgbnVtYmVyIHNob3VsZCBoYXZlIGV4YWN0bHkge21pbn0gbnVtYmVycyIsIm1lc3NhZ2Uta2V5IjoiSUxMRUdBTF9MRU5HVEgifV0sIm9wdGlvbnMiOm51bGwsInZhbHVlIjpudWxsfX0sImFkZHJlc3MiOnsic3RyZWV0Ijp7InJlcXVpcmVkIjp0cnVlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IlNUUklORyIsImNvbnN0cmFpbnRzIjpbeyJydWxlIjoiTEVOR1RIX0JFVFdFRU4iLCJwYXJhbXMiOlsxLDEwMF0sIndoZW4iOm51bGwsIm1lc3NhZ2UiOiJBZGRyZXNzIHN0cmVldCBzaG91bGQgaGF2ZSBsZW5ndGggYmV0d2VlbiB7bWlufSBhbmQge21heH0iLCJtZXNzYWdlLWtleSI6IklMTEVHQUxfTEVOR1RIIn0seyJydWxlIjoiUkVHRVhQIiwicGFyYW1zIjoiXltcXHUwMDQxLVxcdTAwNUFcXHUwMDYxLVxcdTAwN0FcXHUwMEMwLVxcdTAwRDZcXHUwMEQ4LVxcdTAwRjZcXHUwMEY4LVxcdTAwRkZcXHUwMTAwLVxcdTAxN0ZcXHUwMTgwLVxcdTAyNEZcXHUxRTAyLVxcdTFFRjNcXHUwMjU5LVxcdTAyOTJcXHUwMDMwLVxcdTAwMzlcXCBcXC9cXC1cXC5cXF9cXCxdKyQiLCJ3aGVuIjpudWxsLCJtZXNzYWdlIjoiQWRkcmVzcyBzdHJlZXQgc2hvdWxkIGNvbnRhaW4gdmFsaWQgY2hhcmFjdGVycyBvbmx5IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0NIQVJBQ1RFUlMifV0sIm9wdGlvbnMiOm51bGwsInZhbHVlIjpudWxsfSwicG9zdGFsQ29kZSI6eyJyZXF1aXJlZCI6dHJ1ZSwiZWRpdGFibGUiOnRydWUsInR5cGUiOiJTVFJJTkciLCJjb25zdHJhaW50cyI6W3sicnVsZSI6IkxFTkdUSF9CRVRXRUVOIiwicGFyYW1zIjpbMSwxNV0sIndoZW4iOm51bGwsIm1lc3NhZ2UiOiJBZGRyZXNzIHBvc3RhbCBjb2RlIHNob3VsZCBoYXZlIGxlbmd0aCBiZXR3ZWVuIHttaW59IGFuZCB7bWF4fSIsIm1lc3NhZ2Uta2V5IjoiSUxMRUdBTF9MRU5HVEgifSx7InJ1bGUiOiJSRUdFWFAiLCJwYXJhbXMiOiJeWzAtOV17Mn0tWzAtOV17M30kIiwid2hlbiI6eyJjb25kaXRpb24iOiI9PSIsImZpZWxkIjoiYWRkcmVzcy5jb3VudHJ5IiwidmFsdWUiOiJQTCJ9LCJtZXNzYWdlIjoiQWRkcmVzcyBwb3N0YWwgY29kZSBzaG91bGQgbWF0Y2ggcnVsZSIsIm1lc3NhZ2Uta2V5IjoiSUxMRUdBTF9DSEFSQUNURVJTIn0seyJydWxlIjoiUkVHRVhQIiwicGFyYW1zIjoiXlswLTlhLXpBLVovLS8gXSskIiwid2hlbiI6eyJjb25kaXRpb24iOiIhPSIsImZpZWxkIjoiYWRkcmVzcy5jb3VudHJ5IiwidmFsdWUiOiJQTCJ9LCJtZXNzYWdlIjoiQWRkcmVzcyBwb3N0YWwgY29kZSBzaG91bGQgY29udGFpbiB2YWxpZCBjaGFyYWN0ZXJzIG9ubHkiLCJtZXNzYWdlLWtleSI6IklMTEVHQUxfQ0hBUkFDVEVSUyJ9XSwib3B0aW9ucyI6bnVsbCwidmFsdWUiOm51bGx9LCJjaXR5Ijp7InJlcXVpcmVkIjp0cnVlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IlNUUklORyIsImNvbnN0cmFpbnRzIjpbeyJydWxlIjoiTEVOR1RIX0JFVFdFRU4iLCJwYXJhbXMiOlsxLDEwMF0sIndoZW4iOm51bGwsIm1lc3NhZ2UiOiJBZGRyZXNzIGNpdHkgc2hvdWxkIGhhdmUgbGVuZ3RoIGJldHdlZW4ge21pbn0gYW5kIHttYXh9IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0xFTkdUSCJ9LHsicnVsZSI6IlJFR0VYUCIsInBhcmFtcyI6Il5bXFx1MDA0MS1cXHUwMDVBXFx1MDA2MS1cXHUwMDdBXFx1MDBDMC1cXHUwMEQ2XFx1MDBEOC1cXHUwMEY2XFx1MDBGOC1cXHUwMEZGXFx1MDEwMC1cXHUwMTdGXFx1MDE4MC1cXHUwMjRGXFx1MUUwMi1cXHUxRUYzXFx1MDI1OS1cXHUwMjkyXFx1MDAzMC1cXHUwMDM5XFwgXFwvXFwtXFwuXFxfXFwsXSskIiwid2hlbiI6bnVsbCwibWVzc2FnZSI6IkFkZHJlc3MgY2l0eSBzaG91bGQgY29udGFpbiB2YWxpZCBjaGFyYWN0ZXJzIG9ubHkiLCJtZXNzYWdlLWtleSI6IklMTEVHQUxfQ0hBUkFDVEVSUyJ9XSwib3B0aW9ucyI6bnVsbCwidmFsdWUiOm51bGx9LCJ2b2l2b2Rlc2hpcCI6eyJyZXF1aXJlZCI6ZmFsc2UsImVkaXRhYmxlIjp0cnVlLCJ0eXBlIjoiU1RSSU5HIiwiY29uc3RyYWludHMiOlt7InJ1bGUiOiJMRU5HVEhfQkVUV0VFTiIsInBhcmFtcyI6WzEsMTAwXSwid2hlbiI6bnVsbCwibWVzc2FnZSI6IkFkZHJlc3Mgdm9pdm9kZXNoaXAgc2hvdWxkIGhhdmUgbGVuZ3RoIGJldHdlZW4ge21pbn0gYW5kIHttYXh9IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0xFTkdUSCJ9XSwib3B0aW9ucyI6bnVsbCwidmFsdWUiOm51bGx9LCJjb3VudHJ5Ijp7InJlcXVpcmVkIjp0cnVlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IkxJU1QiLCJjb25zdHJhaW50cyI6W3sicnVsZSI6IklOX0xJU1QiLCJwYXJhbXMiOm51bGwsIndoZW4iOm51bGwsIm1lc3NhZ2UiOiJBZGRyZXNzIGNvdW50cnkgc2hvdWxkIG1hdGNoIG9wdGlvbiIsIm1lc3NhZ2Uta2V5IjoiVU5TVVBQT1JURURfUFJPUEVSVFkifV0sIm9wdGlvbnMiOnsiUFIiOiJQUiIsIlBTIjoiUFMiLCJQVCI6IlBUIiwiUFciOiJQVyIsIlBZIjoiUFkiLCJRQSI6IlFBIiwiQUQiOiJBRCIsIkFFIjoiQUUiLCJBRiI6IkFGIiwiQUciOiJBRyIsIkFMIjoiQUwiLCJBTSI6IkFNIiwiQU4iOiJBTiIsIkFPIjoiQU8iLCJBUiI6IkFSIiwiQVMiOiJBUyIsIkFUIjoiQVQiLCJSRSI6IlJFIiwiQVUiOiJBVSIsIkFXIjoiQVciLCJBWiI6IkFaIiwiUk8iOiJSTyIsIkJBIjoiQkEiLCJCQiI6IkJCIiwiUlMiOiJSUyIsIkJEIjoiQkQiLCJCRSI6IkJFIiwiQkYiOiJCRiIsIkJHIjoiQkciLCJSVyI6IlJXIiwiQkgiOiJCSCIsIkJJIjoiQkkiLCJCSiI6IkJKIiwiQk0iOiJCTSIsIkJOIjoiQk4iLCJCTyI6IkJPIiwiU0EiOiJTQSIsIlNCIjoiU0IiLCJCUiI6IkJSIiwiU0MiOiJTQyIsIkJTIjoiQlMiLCJTRCI6IlNEIiwiQlQiOiJCVCIsIlNFIjoiU0UiLCJTRyI6IlNHIiwiQlciOiJCVyIsIlNJIjoiU0kiLCJCWiI6IkJaIiwiU0siOiJTSyIsIlNMIjoiU0wiLCJTTSI6IlNNIiwiU04iOiJTTiIsIlNPIjoiU08iLCJDQSI6IkNBIiwiU1IiOiJTUiIsIkNEIjoiQ0QiLCJTVCI6IlNUIiwiQ0YiOiJDRiIsIlNWIjoiU1YiLCJDRyI6IkNHIiwiQ0giOiJDSCIsIlNZIjoiU1kiLCJDSSI6IkNJIiwiU1oiOiJTWiIsIkNLIjoiQ0siLCJDTCI6IkNMIiwiQ00iOiJDTSIsIkNOIjoiQ04iLCJDTyI6IkNPIiwiQ1IiOiJDUiIsIlRDIjoiVEMiLCJURCI6IlREIiwiQ1UiOiJDVSIsIkNWIjoiQ1YiLCJURyI6IlRHIiwiVEgiOiJUSCIsIkNZIjoiQ1kiLCJUSiI6IlRKIiwiQ1oiOiJDWiIsIlRMIjoiVEwiLCJUTSI6IlRNIiwiVE4iOiJUTiIsIlRPIjoiVE8iLCJUUiI6IlRSIiwiVFQiOiJUVCIsIkRFIjoiREUiLCJUViI6IlRWIiwiVFciOiJUVyIsIkRKIjoiREoiLCJUWiI6IlRaIiwiREsiOiJESyIsIkRNIjoiRE0iLCJETyI6IkRPIiwiVUciOiJVRyIsIkRaIjoiRFoiLCJFQyI6IkVDIiwiVVMiOiJVUyIsIkVFIjoiRUUiLCJFRyI6IkVHIiwiVVkiOiJVWSIsIlVaIjoiVVoiLCJWQSI6IlZBIiwiRVIiOiJFUiIsIlZDIjoiVkMiLCJFUyI6IkVTIiwiRVQiOiJFVCIsIlZFIjoiVkUiLCJWRyI6IlZHIiwiVkkiOiJWSSIsIlZOIjoiVk4iLCJWVSI6IlZVIiwiRkkiOiJGSSIsIkZKIjoiRkoiLCJGTSI6IkZNIiwiRk8iOiJGTyIsIkZSIjoiRlIiLCJXRiI6IldGIiwiR0EiOiJHQSIsIkdCIjoiR0IiLCJXUyI6IldTIiwiR0QiOiJHRCIsIkdFIjoiR0UiLCJHRiI6IkdGIiwiR0ciOiJHRyIsIkdIIjoiR0giLCJHSSI6IkdJIiwiR0wiOiJHTCIsIkdNIjoiR00iLCJHTiI6IkdOIiwiR1AiOiJHUCIsIkdRIjoiR1EiLCJHUiI6IkdSIiwiR1QiOiJHVCIsIkdXIjoiR1ciLCJHWSI6IkdZIiwiWEsiOiJYSyIsIkhLIjoiSEsiLCJITiI6IkhOIiwiSFIiOiJIUiIsIkhUIjoiSFQiLCJZRSI6IllFIiwiSFUiOiJIVSIsIklEIjoiSUQiLCJZVCI6IllUIiwiSUUiOiJJRSIsIklMIjoiSUwiLCJJTSI6IklNIiwiSU4iOiJJTiIsIlpBIjoiWkEiLCJJUSI6IklRIiwiSVIiOiJJUiIsIklTIjoiSVMiLCJJVCI6IklUIiwiWk0iOiJaTSIsIkpFIjoiSkUiLCJaVyI6IlpXIiwiSk0iOiJKTSIsIkpPIjoiSk8iLCJKUCI6IkpQIiwiS0UiOiJLRSIsIktHIjoiS0ciLCJLSCI6IktIIiwiS0kiOiJLSSIsIktNIjoiS00iLCJLTiI6IktOIiwiS1AiOiJLUCIsIktSIjoiS1IiLCJLVyI6IktXIiwiS1kiOiJLWSIsIktaIjoiS1oiLCJMQSI6IkxBIiwiTEIiOiJMQiIsIkxDIjoiTEMiLCJMSSI6IkxJIiwiTEsiOiJMSyIsIkxSIjoiTFIiLCJMUyI6IkxTIiwiTFQiOiJMVCIsIkxVIjoiTFUiLCJMViI6IkxWIiwiTFkiOiJMWSIsIk1BIjoiTUEiLCJNQyI6Ik1DIiwiTUQiOiJNRCIsIk1FIjoiTUUiLCJNRyI6Ik1HIiwiTUgiOiJNSCIsIk1LIjoiTUsiLCJNTCI6Ik1MIiwiTU0iOiJNTSIsIk1OIjoiTU4iLCJNTyI6Ik1PIiwiTVAiOiJNUCIsIk1RIjoiTVEiLCJNUiI6Ik1SIiwiTVMiOiJNUyIsIk1UIjoiTVQiLCJNVSI6Ik1VIiwiTVYiOiJNViIsIk1XIjoiTVciLCJNWCI6Ik1YIiwiTVkiOiJNWSIsIk1aIjoiTVoiLCJOQSI6Ik5BIiwiTkMiOiJOQyIsIk5FIjoiTkUiLCJORyI6Ik5HIiwiTkkiOiJOSSIsIk5MIjoiTkwiLCJOTyI6Ik5PIiwiTlAiOiJOUCIsIk5SIjoiTlIiLCJOWiI6Ik5aIiwiT00iOiJPTSIsIlBBIjoiUEEiLCJQRSI6IlBFIiwiUEYiOiJQRiIsIlBHIjoiUEciLCJQSCI6IlBIIiwiUEsiOiJQSyIsIlBMIjoiUEwiLCJQTSI6IlBNIn0sInZhbHVlIjpudWxsfSwiY29tcGFueU5hbWUiOnsicmVxdWlyZWQiOmZhbHNlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IlNUUklORyIsImNvbnN0cmFpbnRzIjpbeyJydWxlIjoiTEVOR1RIX0JFVFdFRU4iLCJwYXJhbXMiOlsxLDUwXSwid2hlbiI6bnVsbCwibWVzc2FnZSI6IkFkZHJlc3MgY29tcGFueSBuYW1lIHNob3VsZCBoYXZlIGxlbmd0aCBiZXR3ZWVuIHttaW59IGFuZCB7bWF4fSIsIm1lc3NhZ2Uta2V5IjoiSUxMRUdBTF9MRU5HVEgifSx7InJ1bGUiOiJSRUdFWFAiLCJwYXJhbXMiOiJeW1xcdTAwNDEtXFx1MDA1QVxcdTAwNjEtXFx1MDA3QVxcdTAwQzAtXFx1MDBENlxcdTAwRDgtXFx1MDBGNlxcdTAwRjgtXFx1MDBGRlxcdTAxMDAtXFx1MDE3RlxcdTAxODAtXFx1MDI0RlxcdTFFMDItXFx1MUVGM1xcdTAyNTktXFx1MDI5MlxcdTAwMzAtXFx1MDAzOVxcIFxcL1xcLVxcLlxcX1xcLF0rJCIsIndoZW4iOm51bGwsIm1lc3NhZ2UiOiJBZGRyZXNzIGNvbXBhbnkgbmFtZSBzaG91bGQgY29udGFpbiB2YWxpZCBjaGFyYWN0ZXJzIG9ubHkiLCJtZXNzYWdlLWtleSI6IklMTEVHQUxfQ0hBUkFDVEVSUyJ9XSwib3B0aW9ucyI6bnVsbCwidmFsdWUiOm51bGx9fSwibG9jYXRpb24iOnsiYWRkcmVzcyI6eyJzdHJlZXQiOnsicmVxdWlyZWQiOmZhbHNlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IlNUUklORyIsImNvbnN0cmFpbnRzIjpbeyJydWxlIjoiTEVOR1RIX0JFVFdFRU4iLCJwYXJhbXMiOlsxLDEwMDBdLCJ3aGVuIjp7ImNvbmRpdGlvbiI6Ij09IiwiZmllbGQiOiJzaGlwcGluZ09wdGlvblR5cGUiLCJ2YWx1ZSI6IklOUE9TVCJ9LCJtZXNzYWdlIjoiUGFyY2VsIGxvY2tlciBzdHJlZXQgc2hvdWxkIGhhdmUgbGVuZ3RoIGJldHdlZW4ge21pbn0gYW5kIHttYXh9IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0xFTkdUSCJ9XSwib3B0aW9ucyI6bnVsbCwidmFsdWUiOm51bGx9LCJwb3N0YWxDb2RlIjp7InJlcXVpcmVkIjpmYWxzZSwiZWRpdGFibGUiOnRydWUsInR5cGUiOiJTVFJJTkciLCJjb25zdHJhaW50cyI6W3sicnVsZSI6IkxFTkdUSF9CRVRXRUVOIiwicGFyYW1zIjpbMSwxNV0sIndoZW4iOnsiY29uZGl0aW9uIjoiPT0iLCJmaWVsZCI6InNoaXBwaW5nT3B0aW9uVHlwZSIsInZhbHVlIjoiSU5QT1NUIn0sIm1lc3NhZ2UiOiJQYXJjZWwgbG9ja2VyIHBvc3RhbCBjb2RlIHNob3VsZCBoYXZlIGxlbmd0aCBiZXR3ZWVuIHttaW59IGFuZCB7bWF4fSIsIm1lc3NhZ2Uta2V5IjoiSUxMRUdBTF9MRU5HVEgifV0sIm9wdGlvbnMiOm51bGwsInZhbHVlIjpudWxsfSwiY2l0eSI6eyJyZXF1aXJlZCI6ZmFsc2UsImVkaXRhYmxlIjp0cnVlLCJ0eXBlIjoiU1RSSU5HIiwiY29uc3RyYWludHMiOlt7InJ1bGUiOiJMRU5HVEhfQkVUV0VFTiIsInBhcmFtcyI6WzEsMTAwMF0sIndoZW4iOnsiY29uZGl0aW9uIjoiPT0iLCJmaWVsZCI6InNoaXBwaW5nT3B0aW9uVHlwZSIsInZhbHVlIjoiSU5QT1NUIn0sIm1lc3NhZ2UiOiJQYXJjZWwgbG9ja2VyIGNpdHkgc2hvdWxkIGhhdmUgbGVuZ3RoIGJldHdlZW4ge21pbn0gYW5kIHttYXh9IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0xFTkdUSCJ9XSwib3B0aW9ucyI6bnVsbCwidmFsdWUiOm51bGx9LCJ2b2l2b2Rlc2hpcCI6bnVsbCwiY291bnRyeSI6bnVsbCwiY29tcGFueU5hbWUiOm51bGx9LCJjb2RlIjp7InJlcXVpcmVkIjpmYWxzZSwiZWRpdGFibGUiOnRydWUsInR5cGUiOiJTVFJJTkciLCJjb25zdHJhaW50cyI6W3sicnVsZSI6IkxFTkdUSF9CRVRXRUVOIiwicGFyYW1zIjpbMSwxNV0sIndoZW4iOnsiY29uZGl0aW9uIjoiPT0iLCJmaWVsZCI6InNoaXBwaW5nT3B0aW9uVHlwZSIsInZhbHVlIjoiSU5QT1NUIn0sIm1lc3NhZ2UiOiJQYXJjZWwgbG9ja2VyIGNvZGUgc2hvdWxkIGhhdmUgbGVuZ3RoIGJldHdlZW4ge21pbn0gYW5kIHttYXh9IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0xFTkdUSCJ9LHsicnVsZSI6IlJFR0VYUCIsInBhcmFtcyI6Il5bMC05QS1aLV0rJCIsIndoZW4iOnsiY29uZGl0aW9uIjoiPT0iLCJmaWVsZCI6InNoaXBwaW5nT3B0aW9uVHlwZSIsInZhbHVlIjoiSU5QT1NUIn0sIm1lc3NhZ2UiOiJQYXJjZWwgbG9ja2VyIGNvZGUgc2hvdWxkIGNvbnRhaW4gdmFsaWQgY2hhcmFjdGVycyBvbmx5IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0NIQVJBQ1RFUlMifV0sIm9wdGlvbnMiOm51bGwsInZhbHVlIjpudWxsfX0sImNvdW50cnlPZlJlc2lkZW5jZSI6eyJyZXF1aXJlZCI6dHJ1ZSwiZWRpdGFibGUiOnRydWUsInR5cGUiOiJMSVNUIiwiY29uc3RyYWludHMiOlt7InJ1bGUiOiJJTl9MSVNUIiwicGFyYW1zIjpudWxsLCJ3aGVuIjpudWxsLCJtZXNzYWdlIjoiQ291bnRyeSBvZiByZXNpZGVuY2Ugc2hvdWxkIG1hdGNoIG9wdGlvbiIsIm1lc3NhZ2Uta2V5IjoiVU5TVVBQT1JURURfUFJPUEVSVFkifV0sIm9wdGlvbnMiOnsiREUiOiJERSIsIlBMIjoiUEwifSwidmFsdWUiOm51bGx9LCJzaGlwcGluZ09wdGlvblR5cGUiOnsicmVxdWlyZWQiOnRydWUsImVkaXRhYmxlIjp0cnVlLCJ0eXBlIjoiTElTVCIsImNvbnN0cmFpbnRzIjpbeyJydWxlIjoiSU5fTElTVCIsInBhcmFtcyI6bnVsbCwid2hlbiI6bnVsbCwibWVzc2FnZSI6IlNoaXBwaW5nIG9wdGlvbiB0eXBlIHNob3VsZCBtYXRjaCBvcHRpb24iLCJtZXNzYWdlLWtleSI6IlVOU1VQUE9SVEVEX1BST1BFUlRZIn1dLCJvcHRpb25zIjp7IkZFREVYIjoiRkVERVgiLCJQT0xJU0hfUE9TVCI6IlBPTElTSF9QT1NUIiwiSU5QT1NUIjoiSU5QT1NUIiwiRFBEIjoiRFBEIiwiREhMIjoiREhMIn0sInZhbHVlIjpudWxsfSwiY2FyZFRoZW1lIjp7InJlcXVpcmVkIjp0cnVlLCJlZGl0YWJsZSI6dHJ1ZSwidHlwZSI6IkxJU1QiLCJjb25zdHJhaW50cyI6W3sicnVsZSI6IklOX0xJU1QiLCJwYXJhbXMiOm51bGwsIndoZW4iOm51bGwsIm1lc3NhZ2UiOiJDYXJkIHRoZW1lIHNob3VsZCBtYXRjaCBvcHRpb24iLCJtZXNzYWdlLWtleSI6IlVOU1VQUE9SVEVEX1BST1BFUlRZIn1dLCJvcHRpb25zIjp7IldISVRFIjoiV0hJVEUiLCJTUElERVJNQU5fV0hJVEUiOiJTUElERVJNQU5fV0hJVEUiLCJCVVNJTkVTU19CTEFDS19DSVJDTEUiOiJCVVNJTkVTU19CTEFDS19DSVJDTEUiLCJCTEFDSyI6IkJMQUNLIiwiU1BJREVSTUFOX1JFRCI6IlNQSURFUk1BTl9SRUQifSwidmFsdWUiOm51bGx9LCJlbWFpbCI6eyJyZXF1aXJlZCI6dHJ1ZSwiZWRpdGFibGUiOnRydWUsInR5cGUiOiJTVFJJTkciLCJjb25zdHJhaW50cyI6W3sicnVsZSI6IkxFTkdUSF9CRVRXRUVOIiwicGFyYW1zIjpbMSwyNTZdLCJ3aGVuIjpudWxsLCJtZXNzYWdlIjoiRW1haWwgc2hvdWxkIGhhdmUgbGVuZ3RoIGJldHdlZW4ge21pbn0gYW5kIHttYXh9IiwibWVzc2FnZS1rZXkiOiJJTExFR0FMX0xFTkdUSCJ9LHsicnVsZSI6IlJFR0VYUCIsInBhcmFtcyI6Il5bXFx3ISMkJSbigJkqK1xcLz0_YHt8fX5eLV0rKD86XFwuW1xcdyEjJCUm4oCZKitcXC89P2B7fH1

Response status

Code Name Description
200 OK Order setup prepared.

Response headers

Name Value Description
Content-Type application/jose+json Response content type.

Response body

Field name Type Required Description
setup OrderSetupData YES List of order setup data.
preorder boolean YES Card order is preorder
formValidations FormValidationsData YES List of form validations.

Create order

Resource

POST <CONOTOXIA_HOST>/multicurrency_cards/orders

Example request

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

data.json
     {
       "cardTheme": "WHITE",
       "shippingOptionType": "INPOST",
       "sourceId": "hjeiw6r1",
       "countryOfResidence": "PL",
       "firstName": "John",
       "lastName": "Wayne",
       "address": {
         "street": "Porzeczkowa 7B/4",
         "postalCode": "65-001",
         "city": "Zielona Gora",
         "voivodeship": "Lubuskie",
         "country": "PL",
         "companyName": "Company Ltd."
       },
       "location": {
         "code": "ZG022M",
         "address": {
           "street": "Porzeczkowa 7B/4",
           "postalCode": "65-001",
           "city": "Zielona Gora",
           "voivodeship": "Lubuskie",
           "country": "PL"
         }
       },
       "phone": {
         "area": "48",
         "number": "123456789"
       },
       "email": "[email protected]",
       "termsAccepted": true,
       "language": "PL"
     }

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

data.jws
    eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.eyJjYXJkVGhlbWUiOiJXSElURSIsInNoaXBwaW5nT3B0aW9uVHlwZSI6IklOUE9TVCIsInNvdXJjZUlkIjoiI2hqZWl3NnIxIiwiY291bnRyeU9mUmVzaWRlbmNlIjoiUEwiLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJXYXluZSIsImFkZHJlc3MiOnsic3RyZWV0IjoiUG9yemVjemtvd2EgN0IvNCIsInBvc3RhbENvZGUiOiI2NS0wMDEiLCJjaXR5IjoiWmllbG9uYSBHb3JhIiwidm9pdm9kZXNoaXAiOiJMdWJ1c2tpZSIsImNvdW50cnkiOiJQTCIsImNvbXBhbnlOYW1lIjoiQ29tcGFueSBMdGQuIn0sImxvY2F0aW9uIjp7ImNvZGUiOiJaRzAyMk0iLCJhZGRyZXNzIjp7InN0cmVldCI6IlBvcnplY3prb3dhIDdCLzQiLCJwb3N0YWxDb2RlIjoiNjUtMDAxIiwiY2l0eSI6IlppZWxvbmEgR29yYSIsInZvaXZvZGVzaGlwIjoiTHVidXNraWUiLCJjb3VudHJ5IjoiUEwifX0sInBob25lIjp7ImFyZWEiOiI0OCIsIm51bWJlciI6IjEyMzQ1Njc4OSJ9LCJlbWFpbCI6ImV4YW1wbGVAZXhhbXBsZS5jb20iLCJ0ZXJtc0FjY2VwdGVkIjp0cnVlLCJsYW5ndWFnZSI6IlBMIn0.PkHkgR2v-nzXkoCZYvoePsKszJDU9yYRs4ooP6hs3pXsnKqZkJFDxPjJMqaRXG7pC3ykC21lC0Q-qQSGUHeWKnf6K8PoxxzWdhQGxd1jSD2krDXcuE5_jkXufPx2Sx02Zi79_DZ2M3d_PcJ9Dvd8NMCX4YhZG18oH9MiV-CN4k5xvDWKmb8SwAjr-aWFa5UG3tg-HoKeGMfBDijB-DDISl-r6f4zM35X3ChjgDbFJbaOEVji1Z9qMJI7FkLJ06pggCY3vfC0yad7x_W5uztBqr2Ql5AxziKBCBYE-5sNyWvUwXJ7ZdoE4HN9rbPwkOApbUAxV8jGdRBQ44_TzPuLsQ

The REST API method allows you to create order.

Resource

POST <CONOTOXIA_HOST>/multicurrency_cards/orders

Request headers

Name Value Required Remarks
Authorization Bearer {access_token} YES See how to generate access token.
Content-Type application/jose+json YES Format of request body data.

Request body

Field name Type Required Description
cardTheme string YES Card theme. See available card themes
shippingOptionType string YES Shipping option type. See available shipping option types
sourceId string NO Identifier of order form external system. It can be order id from your on-line shop.
countryOfResidence string YES Card owner country of residence. See available countries.
firstName string YES First name using to deliver card.
lastName string YES Last name using to deliver card.
address AddressData YES Location using to deliver card by courier or polish post.
location LocationData NO Location using to deliver card by INPOST
phone SimplePhoneData YES Phone for communication during delivery.
email string YES Email for communication with buyer.
termsAccepted boolean YES Information about terms acceptance.
language string YES Language. See available languages

Response

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

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

Example response body

{
    "id": "fa8e3a27-2ea7-4835-a129-e31a8797692f",
    "status": "ORDER_CREATED",
    "preorder": true
}

    eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.eyJpZCI6ImZhOGUzYTI3LTJlYTctNDgzNS1hMTI5LWUzMWE4Nzk3NjkyZiIsInN0YXR1cyI6Ik9SREVSX0NSRUFURUQiLCJwcmVvcmRlciI6dHJ1ZX0.wNUL7gl6b1s2MbSue61CtpF4NMyuxKgr2iJrloxGTaa7oPjuWv0zg5rJME_QE9xn9NDB-YhDFoCS0hA7v3ykufb-R9bPCXTr00rKxmLaFqoPcSaUrdHprAo2w7UMnnkkotNvwcsYTfjDhgTv4MbFS3Jy8DlQxtht_eMHtj1194K202ufoFBnqCFoZH2p8peZEanx_qeuiSHGVVcBLVwLhMdavCSqHNwLKzEOlvwnkwexbcwbbP2fhoUIYnuFYrvvUfPK7vMZwhAVlszS3jooJ4B0bp6F8VHtgnav0MxbM8S-G0FrSRAH2g6LNxvuA-A2HtmGCEMDn_cA3J2o1Y6s9Q

Response codes

Code Name Description
201 Created Card order created successfully.

Response headers

Name Value Description
Content-Type application/jose+json Response content type.

Response body

Field name Type Required Description
id string YES Card order identifier.
status string YES Status of process. See available process statuses
preorder boolean YES Inform that resource is for preorder process.

Confirm order

Resource

PUT <CONOTOXIA_HOST>/multicurrency_cards/orders/{cardOrderId}/confirmation

Example request

curl -X PUT \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/multicurrency_cards/orders/fa8e3a27-2ea7-4835-a129-e31a8797692f/confirmation"
     }

The REST API method allows you to confirm order.

Resource

PUT <CONOTOXIA_HOST>/multicurrency_cards/orders/{cardOrderId}/confirmation

Request headers

Name Value Description
Authorization Bearer {access_token} See how to generate access token.

Response:

HTTP/1.1 204 No Content

Response status

Code Name Description
204 No Content Order confirmed

Order status

Resource

GET <CONOTOXIA_HOST>/multicurrency_cards/orders/{cardOrderId}/status

Example request

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/multicurrency_cards/orders/fa8e3a27-2ea7-4835-a129-e31a8797692f"
     }

Response

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

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

Example response body

{
  "cardOrderId": "fa8e3a27-2ea7-4835-a129-e31a8797692f",
  "cardOrderStep": "CARD_CREATED",
  "cardStatus": "INACTIVE",
  "deliveryStatus": "ORDERED",
  "preorder": true
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.eyJjYXJkT3JkZXJJZCI6ImIxZTk4Yzk2LTA2ZDMtNDAwNC1iMTQ4LTcyOWRkMDE3MTNjYyIsImNhcmRPcmRlclN0ZXAiOiJDQVJEX0NSRUFURUQiLCJjYXJkU3RhdHVzIjoiSU5BQ1RJVkUiLCJkZWxpdmVyeVN0YXR1cyI6Ik9SREVSRUQiLCJwcmVvcmRlciI6dHJ1ZX0.EBm9xtJCmvuh5bbhxj04-H3h40UwsExDsh7O3Lx0ttlEaNG-zeqV-dv6HcI-z6YiKQQqJRsL-ZFkIdO3X5AsF54xWbQsgdzAVjpWNAr8vj-SFVqusuaJx0EO_8FXraxmPo3t5fwCIFwzu5bM1YKxItprpDFoZ4KuKWesUGsbemoMnKxS_JfcaEwJezYGKOf5rWU-Dya9KU-fv4Tf-X9at72RmhmOjtWOL5kwzVLtI7oacpJTvw04KnE92vlHpdoDi0R9WiRs91VsMkeuXodpkaTsc-KBSL0W6pXC0dNM7TqlAA4ETraUNklpSLNVvGjPX6nxCKIk-tntszVJ2TOV6g

The REST API method allows you to get status of order.

Resource

GET <CONOTOXIA_HOST>/multicurrency_cards/orders/{cardOrderId}/status

Request headers

Name Value Description
Authorization Bearer {access_token} See how to generate access token.

Response status

Code Name Description
204 No Content Status of the order loaded.

Response headers

Name Value Description
Content-Type application/jose+json Response content type.

Response body

Field name Type Required Description
cardOrderId string YES Card order identifier. Use UUID format.
cardOrderStep string YES Card order step. See available order steps
cardStatus string NO Card status
deliveryStatus string NO Status of delivery
preorder boolean YES Card order is preorder

Cancel order

Resource

DELETE <CONOTOXIA_HOST>/multicurrency_cards/orders/{cardOrderId}

Example request

curl -X DELETE \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<CONOTOXIA_HOST>/multicurrency_cards/orders/fa8e3a27-2ea7-4835-a129-e31a8797692f"
     }

The REST API method allows you to cancel order.

Resource

DELETE <CONOTOXIA_HOST>/multicurrency_cards/orders/{cardOrderId}

Request headers

Name Value Description
Authorization Bearer {access_token} See how to generate access token.

Response

HTTP/1.1 204 No Content

Response status

Code Name Description
204 No Content Order cancelled

Notifications

Notifications are a type of webhooks and are used for communication with the Partner. All notifications listed below will be sent to the notification URL address provided by the Partner at the point of sale configuration. These notifications are transmitted using the POST method and may be delivered to the Partner's system in a random order. This is due to the fact that there may be delays between the Conotoxia Pay system and the Partner's system or the system may be unavailable at the time of sending the notification.

Card created

Object sent to the notificationUrl address provided by the Partner:

{
  "cardName": "VISA **** 5339",
  "orderId": "31ae6200-1bf8-4c55-999f-47e59508bb70",
  "cardId": "7c709600-cff1-4506-8f01-da3a9a0d6fb6"
}

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjYXJkTmFtZSI6IlZJU0EgKioqKiA1MzM5Iiwib3JkZXJJZCI6IjMxYWU2MjAwLTFiZjgtNGM1NS05OTlmLTQ3ZTU5NTA4YmI3MCIsImNhcmRJZCI6IjdjNzA5NjAwLWNmZjEtNDUwNi04ZjAxLWRhM2E5YTBkNmZiNiJ9.qzP5Be4XZxTSVGLmR1VGJ27xW8GmtPlTV5DjNEYUVK0

Request headers:

Content-Type: application/json

Content-Type: application/jose+json

This notification is sent when a card is created in the system after the order has been created and confirmed.

Field name Type Description
cardName string Card name
orderId string Order identifier. Use UUID format.
cardId string Card identifier. Use UUID format.

Card sent

Object sent to the notificationUrl address provided by the Partner:

{
  "shippingOptionType": "DPD",
  "cardName": "VISA **** 5369",
  "orderId": "b982604c-23dd-4c92-9b58-a7ff8906f93c",
  "cardId": "9f847ba7-c972-4462-bad2-07d7e78ba7c6",
  "trackingNumber": null
}

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzaGlwcGluZ09wdGlvblR5cGUiOiJEUEQiLCJjYXJkTmFtZSI6IlZJU0EgKioqKiA1MzY5Iiwib3JkZXJJZCI6ImI5ODI2MDRjLTIzZGQtNGM5Mi05YjU4LWE3ZmY4OTA2ZjkzYyIsImNhcmRJZCI6IjlmODQ3YmE3LWM5NzItNDQ2Mi1iYWQyLTA3ZDdlNzhiYTdjNiIsInRyYWNraW5nTnVtYmVyIjpudWxsfQ.uVyeRTCSwpQYWaxI2rUSopoGdPky2fF247UENiuEXs4

Request headers:

Content-Type: application/json

Content-Type: application/jose+json

This notification is sent after creating a card in the system and sending it using the selected delivery method.

Field name Type Description
shippingOptionType string See available shipping option types
cardName string Card name
orderId string Order identifier. Use UUID format.
cardId string Card identifier. Use UUID format.
trackingNumber string Tracking number

Order canceled

Object sent to the notificationUrl address provided by the Partner:

{
  "orderId": "19b0626e-4b20-44da-bd3f-6e5d5f000f54"
}

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvcmRlcklkIjoiMTliMDYyNmUtNGIyMC00NGRhLWJkM2YtNmU1ZDVmMDAwZjU0In0.l0XnCgTgGddcFif-IsjPyu6B8KwSZMqxXMPXFTq5NRM

Request headers:

Content-Type: application/json

Content-Type: application/jose+json

This notification is sent when an order is canceled by cancel order method.

Field name Type Description
orderId string Order identifier. Use UUID format.

Preorder canceled

Object sent to the notificationUrl address provided by the Partner:

{
  "orderId": "19b0626e-4b20-44da-bd3f-6e5d5f000f54"
}

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvcmRlcklkIjoiMTliMDYyNmUtNGIyMC00NGRhLWJkM2YtNmU1ZDVmMDAwZjU0In0.l0XnCgTgGddcFif-IsjPyu6B8KwSZMqxXMPXFTq5NRM

Request headers:

Content-Type: application/json

Content-Type: application/jose+json

Once the entire preorder for an ordered product is canceled, notifications will be sent for all ordered preorders.

Field name Type Description
orderId string Order identifier. Use UUID format.

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 username 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 body

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

Security

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

Message authenticity

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

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

Example of a minimum JWS header accepted by Conotoxia:

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

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

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

Example response body

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

All messages sent from the Partner's system to the Conotoxia Currency Cards 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.

Communication with the Partner

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

Generating a public key

Linux

Installation of the required software

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

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

Generating the key

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

macOS

Installation of the required software

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

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

Generating the key

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

Windows

Installation of the required software

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

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

Generating the key

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

Adding public key

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

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

Example response body

{
  "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} See how to generate access token.
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 \\
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \\
     "<CONOTOXIA_HOST>/v2/public_keys"

Response

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

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

Example response body

{
 "data": [
   {
     "kid": "chi09N6Bog_0IvtrahDhZRGF7kiHTAhQaIm4x_wdpQU",
     "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoPYw28jrN71VoWHfSkTR\nb4v8OdYMjwZRs2dg5vPZjv0xryNAqHpHYP5+SCpEz6YRFGzuCWhqkNgSKmZgLBxv\nBVJt8YqZOtbnB4as/4TI0dy73YUmw00LYXLTcrS6al6OFtC4SehUREgoVG9V8Hlf\nx9T0bnNOW5R0z3LvkC+Y8e1Gm+xtX+K5uX00md5TI1jk5GqoE9D7cuv5mBX50Igi\nzMqbZYttu/gdA3TWD6JnceMU2WPKJDLowGN4RnUtQJQiApfRQZDPblB+9AKJkiTy\n8N4g9hAVmKbwC3cehO1vMB7ujOlJrNAXjh1rO7B3OJQ0JXcpb2UhrPZ/DIuRdLvX\n6QIDAQAB\n-----END PUBLIC KEY-----",
     "status": "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} See how to generate access token.

Query parameters

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

Response body

Data object containing the list of added public keys

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

PublicKey object containing information about the public key of the Conotoxia

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

Resource

GET <CONOTOXIA_HOST>/jwks

Example request

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

Response

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

Example response body

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

To verify messages received from the Conotoxia 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} See how to generate access token.

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.

Data structures

This section describes additional complex data structures used in the API.

SimplePhoneData

Field name Type Required Description
area string YES Area code.
number string YES Phone number.

AddressData

Field name Type Required Description
street string YES Street name.
postalCode string YES Postal code.
city string YES City.
voivodeship string NO Voivodeship.
country string YES Country code. See available countries.
companyName string NO Company name.

LocationData

This structure keep address with optional parcel locker code for INPOST shipping option.

Field name Type Required Description
code string NO Parcel locker code. Required for INPOST.
address AddressData YES Location address.

OrderSetupData

Field name Type Description
shippingOption ShippingOption Shipping option.

ShippingOption

This structure represents information about available shipping option.

Field name Type Description
type string Shipping option type. See available shipping option types
standardPrice MoneyData Standard price of card.
promotionPrice MoneyData Promotion price of card.

MoneyData

This structure represents money amount with currency.

Field name Type Description
value number Price amount.
currency string Price currency. See available currencies .

Constraint

Field name Type Description
rule string Rule name. See available constraint rules
params array[number] or string Rule params. Min and max number for LENGTH_BETWEEN or regular expression string for REGEXP
when ConstraintCondition Rule when
message string Error message
messageKey string Error message key. See available validation message keys.

ConstraintCondition

Field name Type Description
condition string Field name
value object Field value
field string Field path. e.g address.country

FormValidationsData

List of form validations.

Validation Type Description
phone PhoneFormValidationData Phone validation.
address AddressFormValidationData Address validation.
location LocationFormValidationData Location validation.
countryOfResidence FormValidationData Country of residence validation.
shippingOptionType FormValidationData Shipping option type validation.
cardTheme FormValidationData Card theme validation.
email FormValidationData Email validation.
firstName FormValidationData First name validation.
lastName FormValidationData Last name validation.
termsAccepted FormValidationData Terms acceptance validation.
language FormValidationData Card carrier language validation.
sourceId FormValidationData Source identifier validation.

FormValidationData

All validations contains fields:

Field name Type Description
required boolean Field is required
editable boolean Field is editable
type string Form element type. See available types
constraints array[Constraint] Field value constraints.
options map[string, string] Available values for input what require dictionary value.
value object Field value

PhoneFormValidationData

Field name Type Description
phoneArea FormValidationData Phone area validation.
phoneNumber FormValidationData Phone number validation.

AddressFormValidationData

Field name Type Description
street FormValidationData Street validation.
postalCode FormValidationData Postal code validation.
city FormValidationData City validation.
voivodeship FormValidationData Voivodeship validation.
country FormValidationData Country validation.
companyName FormValidationData Company name validation.

LocationFormValidationData

Field name Type Description
code FormValidationData Parcel locker code validation.
address AddressFormValidationData Address validation.

ProblemData

Field name Type Description
type string Problem type. See business error types
title string Problem title
status number HTTP status code
detail string Problem detail
instance string Problem instance

Dictionaries

Order Step

Status Description
CREATE Order created
FINISHED Order finished
CARD_CREATED Order completed
CANCEL Order canceled

Card Theme

Value Description
WHITE Standard white card theme
BLACK Standard black card theme

Shipping Option Type

Value Description
POLISH_POST Shipping by Polish post.
DPD Shipping by DPD courier.
FEDEX Shipping by FEDEX courier.
DHL Shipping by DHL courier.
INPOST Shipping by INPOST courier. Only for country PL.

Language

Value Description
PL Polish language.
EN English language.

Currency

The fallowing list includes only currencies supported by the card shipping pricing.

Value Description
CHF Switzerland Franc
CZK Czech Republic Koruna
DKK Denmark Krone
EUR Euro
GBP United Kingdom Pound
NOK Norway Krone
PLN Poland Zloty
SEK Sweden Krona
USD United States Dollar

Country

Value Description
AF Afghanistan
AL Albania
DZ Algeria
AS American Samoa
AD Andorra
AO Angola
AG Antigua and Barbuda
AZ Azerbaijan
AR Argentina
AU Australia
AT Austria
BS Bahamas
BH Bahrain
BD Bangladesh
AM Armenia
BB Barbados
BE Belgium
BM Bermuda
BT Bhutan
BO Bolivia Plurinational State of
BA Bosnia and Herzegovina
BW Botswana
BR Brazil
BZ Belize
SB Solomon Islands
VG Virgin Islands British
BN Brunei Darussalam
BG Bulgaria
MM Myanmar
BI Burundi
BY Belarus
KH Cambodia
CM Cameroon
CA Canada
CV Cabo Verde
KY Cayman Islands
CF Central African Republic
LK Sri Lanka
TD Chad
CL Chile
CN China
TW Taiwan, Province of China
CO Colombia
KM Comoros
YT Mayotte
CG Congo
CD Congo, Democratic Republic of the
CK Cook Islands
CR Costa Rica
HR Croatia
CU Cuba
CY Cyprus
CZ Czechia
BJ Benin
DK Denmark
DM Dominica
DO Dominican Republic
EC Ecuador
SV El Salvador
GQ Equatorial Guinea
ET Ethiopia
ER Eritrea
EE Estonia
FO Faroe Islands
FJ Fiji
FI Finland
FR France
GF French Guiana
PF French Polynesia
DJ Djibouti
GA Gabon
GE Georgia
GM Gambia
PS Palestine, State of
DE Germany
GH Ghana
GI Gibraltar
KI Kiribati
GR Greece
GL Greenland
GD Grenada
GP Guadeloupe
GT Guatemala
GN Guinea
GY Guyana
HT Haiti
VA Holy See
HN Honduras
HK Hong Kong
HU Hungary
IS Iceland
IN India
ID Indonesia
IR Iran Islamic Republic of
IQ Iraq
IE Ireland
IL Israel
IT Italy
CI Côte d'Ivoire
JM Jamaica
JP Japan
KZ Kazakhstan
JO Jordan
KE Kenya
KP Korea Democratic People's Republic of
KR Korea, Republic of
KW Kuwait
KG Kyrgyzstan
LA Lao People's Democratic Republic
LB Lebanon
LS Lesotho
LV Latvia
LR Liberia
LY Libya
LI Liechtenstein
LT Lithuania
LU Luxembourg
MO Macao
MG Madagascar
MW Malawi
MY Malaysia
MV Maldives
ML Mali
MT Malta
MQ Martinique
MR Mauritania
MU Mauritius
MX Mexico
MC Monaco
MN Mongolia
MD Moldova, Republic of
ME Montenegro
MS Montserrat
MA Morocco
MZ Mozambique
OM Oman
NA Namibia
NR Nauru
NP Nepal
NL Netherlands
AN Netherlands Antilles
AW Aruba
NC New Caledonia
VU Vanuatu
NZ New Zealand
NI Nicaragua
NE Niger
NG Nigeria
NO Norway
MP Northern Mariana Islands
FM Micronesia Federated States of
MH Marshall Islands
PW Palau
PK Pakistan
PA Panama
PG Papua New Guinea
PY Paraguay
PE Peru
PH Philippines
PL Poland
PT Portugal
GW Guinea-Bissau
TL Timor-Leste
PR Puerto Rico
QA Qatar
RE Réunion
RO Romania
RU Russian Federation
RW Rwanda
KN Saint Kitts and Nevis
LC Saint Lucia
PM Saint Pierre and Miquelon
VC Saint Vincent and the Grenadines
SM San Marino
ST Sao Tome and Principe
SA Saudi Arabia
SN Senegal
RS Serbia
SC Seychelles
SL Sierra Leone
SG Singapore
SK Slovakia
VN Viet Nam
SI Slovenia
SO Somalia
ZA South Africa
ZW Zimbabwe
ES Spain
SD Sudan
SR Suriname
SZ Eswatini
SE Sweden
CH Switzerland
SY Syrian Arab Republic
TJ Tajikistan
TH Thailand
TG Togo
TO Tonga
TT Trinidad and Tobago
AE United Arab Emirates
TN Tunisia
TR Turkey
TM Turkmenistan
TC Turks and Caicos Islands
TV Tuvalu
UG Uganda
UA Ukraine
MK North Macedonia
EG Egypt
GB United Kingdom of Great Britain and Northern Ireland
GG Guernsey
JE Jersey
IM Isle of Man
TZ Tanzania, United Republic of
US United States of America
VI Virgin Islands U.S.
BF Burkina Faso
UY Uruguay
UZ Uzbekistan
VE Venezuela Bolivarian Republic of
WF Wallis and Futuna
WS Samoa
YE Yemen
ZM Zambia
XK Kosovo

Form Element Type

Value Description
STRING Plain text input.
LIST Select value from list.
MULTIPLE_TEXT Select multiple values form list.

Constraint Rule

Value Description
LENGTH_BETWEEN Length of value should be in defined range.
IN_LIST Value must contain in list of accepted values.
REGEXP Value must match regular expression.

Validation Message Key

Value Description
ILLEGAL_CHARACTERS Illegal characters.
ILLEGAL_LENGTH Illegal length.
UNSUPPORTED_PROPERTY Unsupported property.

Process Status

Value Description
ORDER_CREATED Order is placed.

Errors

Errors are represented by ProblemData and returned in response body as signed data (JWS).

System errors

Response

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

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

Example response body

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

List of common system errors returned by Conotoxia API.

Status code Status name Description
400 Bad request Returned when a request has an incorrect structure
401 Unauthorized Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.
403 Forbidden Returned when the Customer does not have access to requested resource.
404 Not found Resource not exists
405 Method not allowed Returned when the method called on the resource is different than defined.
415 Unsupported media type The sent request body is of the wrong type.
500 Internal server error An unexpected error occurred.
503 Service unavailable Service is not available.

Business errors

Response

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

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

Example response body

{
    "type": "card-product-not-found",
    "title": "Card product not found",
    "status": 404,
    "detail": "No available card product with theme 'WHITE' to order by 'MERCHANT' for residence country 'PL'"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.eyJ0eXBlIjoiY2FyZC1wcm9kdWN0LW5vdC1mb3VuZCIsInRpdGxlIjoiQ2FyZCBwcm9kdWN0IG5vdCBmb3VuZCIsInN0YXR1cyI6NDA0LCJkZXRhaWwiOiJObyBhdmFpbGFibGUgY2FyZCBwcm9kdWN0IHdpdGggdGhlbWUgJ1dISVRFJyB0byBvcmRlciBieSAnTUVSQ0hBTlQnIGZvciByZXNpZGVuY2UgY291bnRyeSAnUEwnIn0.HM3p8sXtaF_QqYWSIfuewk4FfMpK6wBXgPZTo1_H3arqmxZUbKC6FSJs_tR1a2p1v-ceCIR_eejYfMaJTy0n5Mlj0y7Vlk5Liz8sDo0Qj-ZJZTPUzatCJoGdsNzapVtZA2P2NBPKLDw0nyVY0KqK2cwdQ5oHhSxv0MYy1SGrnZwnXy1P7jbjc36cMHYronekd_Ty9tiDffJm4sQHSMxzAz6g-hUS5GUPMYbX8a891JbxF4Gmr__FpV7teh_xhjOie_2_aLZtnSEQJAJprC3kq9WhCNO8HoG8PUB9OAZSlE5La4MX-geX8xBuetRT8UbtjW5ciwfLBlBtqEEACM8rSA

List of business errors returned by Conotoxia API.

Error type Status code Description
invalid-jws 400 The JWS signature is invalid.
invalid-pem 400 The JSON structure is invalid.
invalid-public-key 400 The public key is invalid.
sample-text-signature-not-match 400 The signature does not match the text.
validation-error 400 The request body does not meet the validation rules.
card-product-not-found 404 The card product was not found.
card-order-not-found 404 The card order was not found.
authentication-already-resolved 409 The authentication has already been resolved.
challenge-expired 409 The time to approve the transaction has expired
incorrect-payload 409 The authentication payload is incorrect.
regulation-not-accepted 409 The Customer has not accepted the regulations.
profile-problem 409 Your user profile has a problem. Log in to your profile and check details.
card-theme-limit-exhausted 409 Returned when the card theme limit is exhausted for the given theme.
user-temporarily-blocked 409 In the interest of account safety, we have blocked strong authentication on your user profile.
user-permanently-blocked 409 Your user profile has been permanently blocked.
card-order-confirm-not-allowed 409 Order cannot be confirmed in current state.
card-order-cancel-not-allowed 409 Order cannot be cancelled in current state.
cURL unsigned cURL signed