Tạo thanh toán định kỳ
Thanh toán định kỳ bằng tiền điện tử là một cách tự động hóa các giao dịch thường xuyên bằng tài sản kỹ thuật số. Chúng có thể hữu ích cho các dịch vụ đăng ký, quyên góp, thành viên và các khoản thanh toán định kỳ khác.
Để sử dụng thanh toán định kỳ, bạn cần tạo một khoản thanh toán ghi rõ số tiền, loại tiền tệ và tần suất thanh toán, sau đó chia sẻ với người thanh toán. Người thanh toán sẽ được chuyển hướng đến trang web cryptomus, nơi họ cần đăng nhập để xác nhận gói thanh toán và thực hiện khoản thanh toán đầu tiên. Sau đó, các khoản thanh toán sẽ được tự động thực hiện theo gói.
Lời yêu cầu
Tham số truy vấn
| Tên | Kiểu tham số | Giá trị mặc định | Sự định nghĩa |
|---|---|---|---|
| amount* | string | - | Số tiền thanh toán định kỳ |
| currency* | string | - | Mã tiền tệ |
| name* | stringmin:3max:60 | - | Tên thanh toán định kỳ |
| period* | string | - | Kỳ thanh toán định kỳcó sẵn:weeklymonthlythree_month |
| to_currency | - | Mã tiền tệ để chấp nhận thanh toánTham số này được sử dụng để chỉ định loại tiền tệ mục tiêu để chuyển đổi số tiền thanh toán định kỳ.Ví dụ: để tạo khoản thanh toán định kỳ 20 USD bằng bitcoin: số tiền: 20 tiền tệ: USD to_currency: BTCAPI sẽ chuyển đổi số tiền 20 USD sang số tiền tương đương bằng BTC dựa trên tỷ giá hối đoái hiện tại và người dùng sẽ thanh toán bằng BTCto_currency phải luôn là mã tiền điện tử, không phải mã tiền pháp định. | |
| order_id | stringmin:1max:100 | null | ID đơn hàng trong hệ thống của bạn |
| url_callback | url | null | URL mà webhooks có trạng thái thanh toán sẽ được gửi đến |
| discount_days | integermin:1max:365 | 0 | Thời gian giảm giá (bắt buộc phải có 'discount_amount') |
| discount_amount | string | null | Số tiền giảm giá (bắt buộc với 'discount_days'). Ở đây là số tiền theo đơn vị tiền tệ của tham số 'currency' |
| additional_data | string | null | Chi tiết thanh toán định kỳ bổ sung |
Kiểu tham số
stringSự định nghĩa
Số tiền thanh toán định kỳKiểu tham số
stringSự định nghĩa
Mã tiền tệKiểu tham số
stringmin:3max:60Sự định nghĩa
Tên thanh toán định kỳKiểu tham số
stringSự định nghĩa
Kỳ thanh toán định kỳcó sẵn:weeklymonthlythree_monthSự định nghĩa
Mã tiền tệ để chấp nhận thanh toánTham số này được sử dụng để chỉ định loại tiền tệ mục tiêu để chuyển đổi số tiền thanh toán định kỳ.Ví dụ: để tạo khoản thanh toán định kỳ 20 USD bằng bitcoin:
số tiền: 20
tiền tệ: USD
to_currency: BTCAPI sẽ chuyển đổi số tiền 20 USD sang số tiền tương đương bằng BTC dựa trên tỷ giá hối đoái hiện tại và người dùng sẽ thanh toán bằng BTCto_currency phải luôn là mã tiền điện tử, không phải mã tiền pháp định.Kiểu tham số
stringmin:1max:100Giá trị mặc định
nullSự định nghĩa
ID đơn hàng trong hệ thống của bạnKiểu tham số
urlGiá trị mặc định
nullSự định nghĩa
URL mà webhooks có trạng thái thanh toán sẽ được gửi đếnKiểu tham số
integermin:1max:365Giá trị mặc định
0Sự định nghĩa
Thời gian giảm giá (bắt buộc phải có 'discount_amount')Kiểu tham số
stringGiá trị mặc định
nullSự định nghĩa
Số tiền giảm giá (bắt buộc với 'discount_days'). Ở đây là số tiền theo đơn vị tiền tệ của tham số 'currency'Kiểu tham số
stringGiá trị mặc định
nullSự định nghĩa
Chi tiết thanh toán định kỳ bổ sung
* - tham số bắt buộc
Giảm giá:
Kỳ đầu tiên tính bằng ngày (tham số discount_days), sẽ có giá khác nhau (tham số discount_amount). Ví dụ: bạn có thể đặt discount_amount cho 30 ngày đầu tiên và một kỳ hàng tháng, sau đó người dùng sẽ thanh toán khoản thanh toán đầu tiên với mức giá thấp hơn, các khoản thanh toán tiếp theo sẽ được tính theo giá gốc.Số tiền chiết khấu phải tính bằng loại tiền tệ được chỉ định bởi tham số ‘tiền tệ’.
Ví dụ yêu cầu
Dưới đây là một ví dụ mẫu với số lượng tham số tối thiểu cần thiết. Trong trường hợp này, hóa đơn sẽ được tạo bằng tiền pháp định USD. Trên trang thanh toán, người dùng sẽ có thể chọn loại tiền điện tử và mạng lưới để thanh toán hóa đơn này.
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"
}'Phản ứng
Các thông số phản hồi
| Tên | Sự định nghĩa |
|---|---|
| uuid | UUID định kỳ |
| name | Tên định kỳ |
| order_id | ID đơn hàng trong hệ thống của bạn |
| amount | Số tiền định kỳ |
| currency | Mã tiền tệ |
| payer_currency | Loại tiền tệ mà khách hàng phải sử dụng để thanh toán. |
| payer_amount_usd | Số tiền USD tương đương theo payer_currency mà khách hàng phải trả |
| payer_amount | Số tiền bằng tiền_thanh_toán mà khách hàng phải trả |
| url_callback | URL mà webhooks có trạng thái thanh toán sẽ được gửi đến |
| period | Kỳ thanh toán định kỳ |
| status | Trạng thái định kỳCác tùy chọn có sẵn:• wait_accept• cancel_by_merchant• active• cancel_by_user |
| url | URL của trang thanh toán Cryptomus nơi người trả tiền sẽ thực hiện thanh toán |
| last_pay_off | Ngày thanh toán gần nhất. Múi giờ là UTC+3. Nếu giá trị là null, nghĩa là chưa có khoản thanh toán nào được thực hiện. |
| additional_data | Chi tiết thanh toán định kỳ bổ sung |
Sự định nghĩa
UUID định kỳSự định nghĩa
Tên định kỳSự định nghĩa
ID đơn hàng trong hệ thống của bạnSự định nghĩa
Số tiền định kỳSự định nghĩa
Mã tiền tệSự định nghĩa
Loại tiền tệ mà khách hàng phải sử dụng để thanh toán.Sự định nghĩa
Số tiền USD tương đương theo payer_currency mà khách hàng phải trảSự định nghĩa
Số tiền bằng tiền_thanh_toán mà khách hàng phải trảSự định nghĩa
URL mà webhooks có trạng thái thanh toán sẽ được gửi đếnSự định nghĩa
Kỳ thanh toán định kỳSự định nghĩa
Trạng thái định kỳCác tùy chọn có sẵn:- wait_accept- cancel_by_merchant- active- cancel_by_userSự định nghĩa
URL của trang thanh toán Cryptomus nơi người trả tiền sẽ thực hiện thanh toánSự định nghĩa
Ngày thanh toán gần nhất. Múi giờ là UTC+3. Nếu giá trị là null, nghĩa là chưa có khoản thanh toán nào được thực hiện.Sự định nghĩa
Chi tiết thanh toán định kỳ bổ sung
Ví dụ phản hồi
Nếu yêu cầu thành công, mã phản hồi là 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}Thêm ví dụ
Ví dụ về yêu cầu dữ liệu để tạo khoản thanh toán định kỳ là 15 USD
1{
2 "amount": "15",
3 "currency": "USD",
4 "name": "Recurring payment",
5 "period": "monthly",
6 "url_callback": "https://your.site/callback"
7}Ví dụ phản hồi:
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}Yêu cầu ví dụ dữ liệu để tạo khoản thanh toán định kỳ cho 15 USDT (chỉ USDT mới được phép thanh toán)
1{
2 "amount": "15",
3 "currency": "USDT",
4 "name": "Recurring payment",
5 "period": "monthly",
6 "url_callback": "https://your.site/callback"
7}Ví dụ phản hồi:
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}Yêu cầu ví dụ dữ liệu để tạo khoản thanh toán định kỳ là 15 USD và chỉ cho phép thanh toán bằng đồng BTC
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}Ví dụ phản hồi:
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}Ví dụ về yêu cầu dữ liệu để tạo khoản thanh toán định kỳ với số tiền là 15 đô la. Trong 30 ngày đầu tiên, giá sẽ là 1 đô la, sau đó là 15 đô la:
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}Ví dụ phản hồi:
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}