API

Authorization

Cashier uses JWT tokens for authorization. The tokens are signed using the HS256 algorithm, with the Merchant API User Secret serving as the signing key.

The generated JWT token must be sent with every request in the Authorization header using the Bearer scheme.

Example:

Authorization: Bearer <jwt_token>

Token payload parameters:

Name	Type	Size/Format	Description
exp	string	timestamp	Expiration date. Example: 1738771955
user_uuid	string	UUID, Chars (36)	Merchant API User identifier

Example:

To generate your unique token, you can enter your data in JSON format into JWT token online generator like: https://jwt.io/

Please see the table below on how to correctly fill the fields in the token generator.

Field	Value
HEADER:	{ "alg": "HS256", "typ": "JWT" }
PAYLOAD:	{ "user_uuid": "f27cae21-02f3-4215-a5c7-c0746ff9e421", "exp": 1738771955 }
JWT SECRET:	Paste your Merchant API User Secret. Example: 123457890123456789012345678901234567890

Resulting JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3V1aWQiOiJmMjdjYWUyMS0wMmYzLTQyMTUtYTVjNy1jMDc0NmZmOWU0MjEiLCJleHAiOjE3Mzg3NzE5NTV9.2oLsmmmT-hVeoWrU9vMODHrpmJdlibSCJRybcC2XbFY

Payment init endpoint

This endpoint is used to initiate new payments on the Cashier side. A successful response will return a redirect link that your customer should follow to be taken to the Cashier Hosted Payment Page.

URL: {api_url}/business-api/v1/intent/init

HTTP Method: POST

Headers:

• Content-type: application/json
• Authorization: API JWT bearer token.

Request object description:

Name	Type	Size/Format	Mandatory	Description
customer	Object	—	true	Please refer to Customer object (link to customer object description)
notification_url	string	Char (256) Format: only latin chars	true	URL for transaction status notification
origin_transaction_id	string	Char (50)	false	Transaction ID in merchant's system
lang	string	Char (2) Format: ISO 639-1 Code (wiki).	false	One of Deposit Page supported language requested by merchant. Default: en
source	string	Possible values: "WEB", "MOBILE_APP", "MOBILE_WEB"	false	Source from Deposit page is requested
gtm	string	Char (11)	false	GTM Identifier (Google Tag Manager Identifier) to be sent within notification to CRM
variable1	string	Char (256)	false	Custom variable forwarded from Deposit page to Merchant system via Notifications Webhooks
variable2	string	Char (256)	false	Custom variable forwarded from Deposit page to Merchant system via Notifications Webhooks
variable3	string	Char (256)	false	Custom variable forwarded from Deposit page to Merchant system via Notifications Webhooks

Customer object description:

Name	Type	Size/Format	Mandatory	Description
id	string	Char (100)	true	Customer unique identifier from Merchant system
country	string	ISO 2 digits country code: wiki	true	Customer country code
email	string	Char (50). Format: email	true	Customer email
full_phone_number	string	Char (50). Format: international phone number format E.164 (link)	true	Full phone number
first_name	string	Char (50)	true	Customer’s first name
last_name	string	Char (50)	true	Customer’s last name
currency	string	Currency ISO Code: wiki	true	Customer trading account currency
address	string	Char (100)	false	Customer address
city	string	Char (50)	false	Customer city
postal_code	string	Char (20)	false	Customer postal code
is_depositor	boolean	—	false	true - customer has deposits; false - customer doesn't have deposits
affiliate_name	string	Char (100)	false	Customer's affiliate name
balance	string	Char (20)	false	Customer trading account balance in minor units (wiki)
assigned_to_department_tree_path	string	Char (100)	false	Definition of the department/team associated with the transaction
trading_account_id	string	Char (50)	false	Trading Account unique identifier of the Customer from Merchant system
documents	Array[]		false	Array of Document objects

Document object description:

Name	Type	Size/Format	Mandatory	Description
type	string	For now, only valid value is TAX_ID	true	Type of document
number	string	Char (50)	true	Document number
country	string	ISO 2 digits country code: wiki	true	Document country code

Response object description:

Name	Type	Description
redirect_url	string	Redirect URL which merchant customer should follow to get to Cashier Payment Page

Request example:

curl -X 'POST' \
  'https://{api_url}/business-api/v1/intent/init' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {jwt_token}\
  -H 'Content-Type: application/json' \
  -d '{
  "customer": {
    "id": "42",
    "country": "UA",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "full_phone_number": "+442073238000",
    "currency": "USD",
    "city": "Kyiv",
    "address": "123 Main St",
    "postal_code": "01001",
    "is_depositor": true,
    "affiliate_name": "Affiliate name",
    "balance": "1000",
    "assigned_to_department_tree_path": "Dev/Team1",
    "trading_account_id": "123456789",
    "documents": [
      {
        "type": "TAX_ID",
        "number": "AB123456",
        "country": "UA"
      }
    ]
  },
  "notification_url": "https://example.com/notification",
  "origin_transaction_id": "123456789",
  "lang": "en",
  "source": "WEB",
  "gtm": "GTM-ABCDEF",
  "variable1": "variable1",
  "variable2": "variable2",
  "variable3": "variable3"
}'

Success response (status 200) example:

{
  "redirect_url": "https://example.com/brand/index.htmljwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50X3V1aWQiOiJkOWFjNjA4ZC04Y2VhLTQ0MzAtODFlOS05MDFhYzE4OTcwZTEiLCJjdXN0b21lcklkIjoiMSIsImJyYW5kIjoic29tZWJyYW5kIiwiZXhwIjoxNzQzMDg2MDUxfQ.GG6hY6tAXSvEDrBknGDsJHK-Kfmp-_zhy9KFNiqOudU&lang=en&source=WEB&gtm=GTM-ABCDEF&variable1=variable1&variable2=variable2&variable3=variable3"
}

Validation error response (status 422) example:

[
  {
    "code": "VALIDATION_ERROR",
    "message": "This value should not be blank.",
    "context": {
      "propertyPath": "customer.id"
    }
  }
]

Internal error response (status 500) example:

[
  {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
]

Refund endpoint

Initiates a refund process for a completed transaction.

URL: {api_url}/business-api/v1/batch-refunds/

HTTP Method: GET

Headers:

• Content-type: application/json
• Authorization: API JWT bearer token.

Request fields:

Name	Type	Size/Format	Mandatory	Description
refunds	Array of JSON objects	Array of Refund request objects	true	List of transaction refund request

Refund request object

Name	Type	Size/Format	Mandatory	Description
transaction_id	string		true	Cashier360 PSP/APM Transaction UUID
origin_transaction_id	string		false	Merchant`s refund transaction ID
money	Money	Money object	true	Money object in the customer's account original currency
converted_money	Money	Money object	false	Money object in the payment provider's currency

Money object

Name	Type	Size/Format	Mandatory	Description
amount	int	In minor units: wiki	true	Money amount
currency	string	ISO currency code: wiki	true	Money currency

Request example:

curl -X 'POST' \
  'https://{api_url}/api/gateway/business-api/v1/batch-refunds/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {jwt_token}\
  -H 'Content-Type: application/json' \
  -d '{
  "refunds": [
    {
      "transaction_id": "14f80a6f-7ad3-42f4-b036-6e535b2943db",
      "origin_transaction_id": "123456",
      "money": {
        "amount": 110,
        "currency": "USD"
      },
      "converted_money": {
        "amount": 110,
        "currency": "USD"
      }
    }
  ]
}'

Success response (status 200) example:

{
  "status": "ACCEPTED"
}

Validation error response (status 422) example:

[
  {
    "code": "VALIDATION_ERROR",
    "message": "This value should not be blank.",
    "context": {
      "propertyPath": "transaction_id"
    }
  }
]

Internal error response (status 500) example:

[
  {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
]