Skip to main content

1. Creating a payment

`payments/create`

The merchant's website or app sends a request to the Processing Service to create a payment, which has the following form:

POST https://<HOSTNAME>/api/v1/payments/create
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
Idempotence-Key: ps_1614589640890_3134
Content-Type: application/json

{
  "email": "[email protected]",
  "shop_order_id": "208843-42-23-842",
  "amount": "100.00",
  "amount_of_shipping": "15.00",
  "callback_url": "https://website.com/api/change-status",
  "description": "Order #208843-42-23-842",
  "expires": "2020-02-22T00:00:00-00:00"
}

Fields description

Field	Type	Required	Description
email	string	yes	buyer's email; used when refunds are necessary;
shop_order_id	string	no	shop order id
amount	string	yes if "client_amount" field is not specified	total payment amount (currency is specified in the merchant's profile); You cannot use this field in conjunction with the "client_amount" field.
amount_of_shipping	string	no	amount of shipping. This field has an informational function.
callback_url	string	no	URL address of callback API of the store to which the Processing Service will send a request when payment status is changed (when payment is executed) Attention! Keep in mind that if the site in which You are testing payments is not publicly accessible for requests from the Internet, then notifications of changes in the status of payments from Our processing service will not be able to reach Your online store, as a result of which the status of orders in your store will not change.
description	string	no	if you need to add a description of the payment which the merchant wants to see in the personal account, you must pass the description parameter. Description must not exceed 128 characters.
expires	string	no	the date when the payment expires in RFC3339 format. Default: 1 hour from the moment of sending;
client_currency	string	no	currency displayed for the client
client_amount	string	yes if "amount" field is not specified	total payment amount in the client's currency. You cannot use this field in conjunction with the "amount" field. Can only be used in conjunction with the "client_currency" field.
client_amount_of_shipping	string	no	delivery amount in the client's currency. This field has an informational function. Can only be used in conjunction with the "client_currency" and "client_amount" fields.

The processing service returns the created payment object with a token to initialize the widget.

{
  "id": "23d93cac-000f-5000-8000-126628f15141",
  "status": "pending",
  "amount": "100.00",
  "currency": "EUR",
  "description": "Order #208843-42-23-842",
  "confirmation_token": "ct-24301ae5-000f-5000-9000-13f5f1c2f8e0",
  "created_at": "2019-01-22T14:30:45-03:00",
  "expires": "2020-02-22T00:00:00-00:00"
}

Fields description

Field	Type	Required	Description
id	string	yes	payment identifier
status	string	yes	payment status. Value options: "pending"- pending payment; "awaiting_payment_confirmation" - the transaction was found in the mempool, its confirmation in the blockchain network is pending; "paid" - payment made; "cancelled" - the payment is cancelled by the seller; "expired" - payment time has expired;
amount	string	yes	total amount of payment
amount_of_shipping	string	no	amount of shipping
currency	string	yes	payment currency
description	string	yes	payment description, maximum 128 characters
confirmation_token	string	yes	payment token, that is necessary to initialize the widget
created_at	string	yes	payment creation date, RFC3339 format
expires	string	yes	date when payment expires, RFC3339 format
client_currency	string	no	currency displayed for the client
client_amount	string	yes	total payment amount in the client's currency
client_amount_of_shipping	string	no	delivery amount in the client's currency

Examples of parameters with client currency

Here the amount in the merchant's currency will be displayed in the amount in the client's currency.

{
  "email": "[email protected]",
  "shop_order_id": "208843-42-23-842",
  "client_сurrency": "TRY",
  "amount": "100.00",
  "amount_of_shipping": "15.00",
  "callback_url": "https://website.com/api/change-status",
  "description": "Order #208843-42-23-842",
  "expires": "2020-02-22T00:00:00-00:00"
}

Here, the amount displayed in the client's currency will be automatically converted into the merchant's currency at the current rate.

{
  "email": "[email protected]",
  "shop_order_id": "208843-42-23-842",
  "client_сurrency": "TRY",
  "client_amount": "100.00",
  "client_amount_of_shipping": "15.00",
  "callback_url": "https://website.com/api/change-status",
  "description": "Order #208843-42-23-842",
  "expires": "2020-02-22T00:00:00-00:00"
}

payments/create
Examples of parameters with client currency