Creating recurring payment

Recurring payments in cryptocurrency are a way to automate regular transactions using digital assets. They can be useful for subscription-based services, donations, memberships, and other recurring payments.

To use recurring payments, you need to create a payment that specifies the amount, currency, and frequency of the payments, and then share it with your payers. The payer will be redirected to the cryptomus website, where he will need to log in to confirm the payment plan and make the first payment. After that, payments will be made automatically according to the plan.

post

https://api.cryptomus.com/v1/recurrence/create

COPY

Request

Query parameters

Name	Parameter type	Default value	Definition
amount*	string		Recurring payment amount
currency*	string		Currency code
name*	stringmin:3max:60		Recurring payment name
period*	string		Recurring payment periodavailable:weeklymonthlythree_month
to_currency			Currency code for accepting paymentsThe parameter is used to specify the target currency for converting the recurrent payment amount.For example, to create an recurrent payment for 20 USD in bitcoin: amount: 20 currency: USD to_currency: BTCThe API will convert 20 USD amount to its equivalent in BTC based on the current exchange rate and the user will pay in BTCThe to_currency should always be the cryptocurrency code, not a fiat currency code.
order_id	stringmin:1max:100	null	Order ID in your system
url_callback	url	null	Url to which webhooks with payment status will be sent
discount_days	integermin:1max:365	0	Discount period days (required with 'discount_amount')
discount_amount	string	null	Discount amount (required with 'discount_days').Here the amount in the currency of the parameter ‘currency’
additional_data	string	null	Additional recurring payment details

Parameter type

string

Definition

Recurring payment amount

Parameter type

string

Definition

Currency code

Parameter type

stringmin:3max:60

Definition

Recurring payment name

Parameter type

string

Definition

Recurring payment periodavailable:weeklymonthlythree_month

Definition

Currency code for accepting paymentsThe parameter is used to specify the target currency for converting the recurrent payment amount.For example, to create an recurrent payment for 20 USD in bitcoin:
amount: 20
currency: USD
to_currency: BTCThe API will convert 20 USD amount to its equivalent in BTC based on the current exchange rate and the user will pay in BTCThe to_currency should always be the cryptocurrency code, not a fiat currency code.

Parameter type

stringmin:1max:100

Definition

Order ID in your system

Parameter type

url

Definition

Url to which webhooks with payment status will be sent

Parameter type

integermin:1max:365

Definition

Discount period days (required with 'discount_amount')

Parameter type

string

Definition

Discount amount (required with 'discount_days').Here the amount in the currency of the parameter ‘currency’

Parameter type

string

Definition

Additional recurring payment details

* - mandatory parameter

Discount:

The first period in days (the discount_days parameter), which will cost a different amount (the discount_amount parameter). For example, you can set a discount_amount for the first 30 days and a monthly period, then the user will pay the first payment with a lower price, the second and subsequent payments will be at full price.

The discount amount must be in the currency specified by the parameter ‘currency’.

Request example

Below is a sample example with the minimum required number of parameters In this case, an invoice will be created with the fiat currency USD. On the payment page, the user will be able to select the cryptocurrency and network to pay this bill.


curl https://api.cryptomus.com/v1/recurrence/create \
-X POST \
-H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
-H 'sign: fe99035f86fa436181717b302b95bacff1' \
-H 'Content-Type: application/json' \
-d '{
	"amount": "15",
	"currency": "USDT",
	"name": "Recurring payment",
	"period": "monthly"
}'

COPY

Response

Response parameters

Name	Definition
uuid	Recurring uuid
name	Recurring name
order_id	Order ID in your system
amount	Recurring amount
currency	Currency code
payer_currency	The currency in which the customer must make the payment.
payer_amount_usd	The equivalent USD amount in payer_currency that the customer must pay
payer_amount	The amount in payer_currency that the customer must pay
url_callback	Url to which webhooks with payment status will be sent
period	Recurring payment period
status	Recurring statusAvailable options:• wait_accept• cancel_by_merchant• active• cancel_by_user
url	The URL of the Cryptomus payment page where the payer will make the payment
last_pay_off	Date of the last payment. The time zone is UTC+3. If the value is null, no payments were made.
additional_data	Additional recurring payment details

: Definition
Recurring uuid
: Definition
Recurring name
: Definition
Order ID in your system
: Definition
Recurring amount
: Definition
Currency code
: Definition
The currency in which the customer must make the payment.
: Definition
The equivalent USD amount in payer_currency that the customer must pay
: Definition
The amount in payer_currency that the customer must pay
: Definition
Url to which webhooks with payment status will be sent
: Definition
Recurring payment period
: Definition
Recurring statusAvailable options:- wait_accept- cancel_by_merchant- active- cancel_by_user
: Definition
The URL of the Cryptomus payment page where the payer will make the payment
: Definition
Date of the last payment. The time zone is UTC+3. If the value is null, no payments were made.
: Definition
Additional recurring payment details

Response example

If the request is successful. the response code is 200.


1{
2	"state": 0,
3	"result": {
4		"uuid": "afd050e8-35ea-4129-bbdd-73f510dce556",
5		"name": "Recurring payment",
6		"order_id": null,
7		"amount": "15",
8		"currency": "USDT",
9		"payer_currency": "USDT",
10		"payer_amount_usd": "15.00",
11		"payer_amount": "15.00000000",
12		"url_callback": null,
13		"period": "monthly",
14		"status": "wait_accept",
15		"url": "https://pay.cryptomus.com/recurring/afd050e8-35ea-4129-bbdd-73f510dce556",
16		"last_pay_off": null
17	}
18}

COPY

More examples

Request data example to create a recurrence payment for 15 USD


1{
2	"amount": "15",
3	"currency": "USD",
4	"name": "Recurring payment",
5	"period": "monthly",
6	"url_callback": "https://your.site/callback"
7}

COPY

Response example:


1{
2	"state": 0,
3	"result": {
4		"uuid": "1d4c1ef7-1dcd-4f98-9433-2e19d2e62820",
5		"name": "Recurring payment",
6		"order_id": null,
7		"amount": "15",
8		"currency": "USD",
9		"payer_currency": null,
10		"payer_amount_usd": "0.00",
11		"payer_amount": null,
12		"url_callback": "https://your.site/callback",
13		"period": "monthly",
14		"status": "wait_accept",
15		"url": "https://pay.cryptomus.com/recurring/1d4c1ef7-1dcd-4f98-9433-2e19d2e62820",
16		"last_pay_off": null
17	}
18}

COPY

Request data example to create a recurrence payment for 15 USDT (only USDT will be allowed for payment)


1{
2	"amount": "15",
3	"currency": "USDT",
4	"name": "Recurring payment",
5	"period": "monthly",
6	"url_callback": "https://your.site/callback"
7}

COPY

Response example:


1{
2	"state": 0,
3	"result": {
4		"uuid": "ec04dc64-fea4-445a-9698-59baa474317a",
5		"name": "Recurring payment",
6		"order_id": null,
7		"amount": "15",
8		"currency": "USDT",
9		"payer_currency": "USDT",
10		"payer_amount_usd": "15.00",
11		"payer_amount": "15.00000000",
12		"url_callback": "https://your.site/callback",
13		"period": "monthly",
14		"status": "wait_accept",
15		"url": "https://pay.cryptomus.com/recurring/ec04dc64-fea4-445a-9698-59baa474317a",
16		"last_pay_off": null
17	}
18}

COPY

Request data example to create a recurrence payment for 15 USD and allow only BTC currency for payment


1{
2	"amount": "15",
3	"currency": "USD",
4	"to_currency": "BTC",
5	"name": "Recurring payment",
6	"period": "monthly",
7	"url_callback": "https://your.site/callback"
8}

COPY

Response example:


1{
2	"state": 0,
3	"result": {
4		"uuid": "e7d9c265-3849-4ff8-84c1-15435368f05f",
5		"name": "Recurring payment",
6		"order_id": null,
7		"amount": "15",
8		"currency": "USD",
9		"payer_currency": "BTC",
10		"payer_amount_usd": "15.00",
11		"payer_amount": "0.00051495",
12		"url_callback": "https://your.site/callback",
13		"period": "monthly",
14		"status": "wait_accept",
15		"url": "https://pay.cryptomus.com/recurring/e7d9c265-3849-4ff8-84c1-15435368f05f",
16		"last_pay_off": null
17	}
18}

COPY

Request data example to create a recurring payment in the amount of $15. The first 30 days the price will be $1, after that - $15:


1{
2	"amount": "15",
3	"currency": "USD",
4	"name": "Recurring payment",
5	"period": "monthly",
6	"discount_days": 30,
7  "discount_amount": "1"
8	"url_callback": "https://your.site/callback"
9}

COPY

Response example:


1{
2	"state": 0,
3	"result": {
4		"uuid": "1ee00fbd-42e7-4653-b316-1ab12f8a447b",
5		"name": "Recurring payment",
6		"order_id": null,
7		"amount": "15",
8		"currency": "USD",
9		"payer_currency": null,
10		"payer_amount_usd": "0.00",
11		"payer_amount": null,
12		"url_callback": "https://your.site/callback",
13		"discount_days": "30",
14                "discount_amount": "1",
15		"end_of_discount": "2023-07-11T20:23:52+03:00",
16		"period": "monthly",
17		"status": "wait_accept",
18		"url": "https://pay.cryptomus.com/recurring/1ee00fbd-42e7-4653-b316-1ab12f8a447b",
19		"last_pay_off": null
20	}
21}

COPY