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
Default value
null
Definition
Order ID in your system
: Parameter type
url
Default value
null
Definition
URL to which webhooks with payment status will be sent
: Parameter type
integermin:1max:365
Default value
0
Definition
Discount period days (required with 'discount_amount')
: Parameter type
string
Default value
null
Definition
Discount amount (required with 'discount_days').Here the amount in the currency of the parameter ‘currency’
: Parameter type
string
Default value
null
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