# Build subscriptions integration
**Supported Payment method**
## Card
| CARD BRAND | Popular country / region | Subscription |
| ---------- | ------------------------ | ------------ |
| Visa | Global | ✅ |
| Mastercard | Global | ✅ |
## **Wallets**
| Payment methods | Popular country / region | Subscription | Processing currency |
| --------------- | ------------------------ | ------------ | ----------------------- |
| Alipay | China | ✅ | CNY,GBP,USD,EUR,HKD |
| AlipayHK | Hong Kong | ✅ | HKD,GBP,USD,EUR |
| Boost | Malaysia | ✅ | MYR,GBP,USD,EUR |
| DANA | Indonesia | ✅ | IDR,GBP,USD,EUR |
| GCash | Philippines | ✅ | PHP,GBP,USD,EUR |
| KakaoPay | South Korea | ✅ | KRW,GBP,USD,EUR |
| Touch'n Go | Malaysia | ✅ | MYR,GBP,USD,EUR |
| TrueMoney | Thailand | ✅ | THB,GBPUSD,EUR |
**Create and manage subscriptions to accept recurring payments.**
# **What you’ll build**
This guide describes how to sell fixed-price monthly subscriptions using WooshPay checkout.
This guide shows you how to:
- Model your business by building a product catalog
- Add a Checkout session to your site, including a button and success and cancellation pages
- Monitor subscription events and provision access to your service
You can adapt your subscription business according to the example below.
**For example: My membership service business has a subscription fee of $10 per month.**
## 1.Create the pricing model
**First, you need to create a** **priceing** **model where the recurring field includes the billing cycle.**
[**Create a Price**](api-55501373)
*Request*
```JSON
{
"currency": "USD",
"product_data": {
"name":"Plus plan"
},
"unit_amount": 1000,
"active": true,
"recurring": {
"interval": "month",
"interval_count": 1
}
}
```
*Response*
```JSON
{
"id": "price_1795818288165421056",
"object": "price",
"created": 1716991419000,
"livemode": false,
"active": true,
"currency": "USD",
"product": {
"id": "prod_1795818288173809664",
"object": "product",
"created": 1716991419000,
"livemode": false,
"active": true,
"name": "Plus plan",
"updated": 1716991419000
},
"type": "recurring",
"recurring": {
"interval": "month",
"interval_count": 1,
"usage_type": "licensed"
},
"unit_amount": 1000,
"billing_scheme": "per_unit"
}
```
## 2. Create a Checkout Session
Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session。
```HTML
Checkout
```
**Now I need to create a checkout session where users can be redirected to WooshPay to complete the subscription.**
On the backend of your application, define an endpoint that creates the session for your frontend to call. You need these values:
- The price ID of the subscription the customer is signing up for—your frontend passes this value
- Your `success_url`, a page on your website that Checkout returns your customer to after they complete the payment
You can optionally provide `cancel_url`, a page on your website that Checkout returns your customer to if they cancel the payment process.
[**Create a Checkout Session**](api-42654181)
*Request*
```JSON
{
"mode": "subscription",
"success_url": "https://yourwebsite.com",
"line_items": [
{
"quantity": 1,
"price":"price_1795818288165421056"
}
]
}
```
*Response*
```JSON
{
"id": "cs_1796010789673369600",
"object": "checkout.session",
"created": 1717037315000,
"livemode": false,
"currency": "USD",
"customer": "",
"mode": "subscription",
"status": "open",
"url": "https://checkouttest.wooshpay.com/pay/cs_test_1796010789673369600?key=cGtfdGVzdF9OVEUzTWpFME9UUXpOalkyTkRrNU56ZzRPREV4T2pGbFJWaDNXWGxSTTBReE0wRnBkRmhZUm14T1JqTTBWVEUyT1RreU56RXlNVFU0T0RZ",
"line_items": {
"object": "list",
"data": [
{
"id": "li_1796010789715312640",
"object": "item",
"currency": "USD",
"description": "Plus plan",
"price": {
"id": "price_1795818288165421056",
"object": "price",
"created": 1716991419000,
"livemode": false,
"active": true,
"currency": "USD",
"product": {
"id": "prod_1795818288173809664",
"object": "product",
"created": 1716991419000,
"livemode": false,
"active": true,
"name": "Plus plan",
"updated": 1716991419000
},
"type": "recurring",
"recurring": {
"interval": "month",
"interval_count": 1,
"usage_type": "licensed"
},
"unit_amount": 1000,
"billing_scheme": "per_unit"
},
"quantity": 1,
"amount_subtotal": 1000,
"amount_total": 1000
}
]
},
"payment_intent": "pi_1796010789782421504",
"payment_method_types": [
"card"
],
"payment_status": "unpaid",
"success_url": "https://baidu.com",
"amount_subtotal": 1000,
"amount_total": 1000,
"billing_address_collection": "auto",
"expires_at": 1717123715183,
"payment_link": "",
"client_secret": "pi_1796010789782421504_secret_VpKljsEZq43gYYmetS1gHh03",
"customer_creation": "if_required",
"total_details": {
"amount_discount": 0
}
}
```
**Consumer will be redirected to the WooshPay checkout to complete the payment.**
## 3. Provision and monitor subscriptions
1. After the subscription signup succeeds, the customer returns to your website at the `success_url`, which initiates a `checkout.session.completed` webhooks.
2. When you receive a `checkout.session.completed` event, you can provision the subscription.
3. Continue to provision each month (if billing monthly) as you receive `invoice.paid` events.
4. If you receive an `invoice.payment_failed` event, notify your customer that the subscription has failed.
To determine the next step for your system’s logic, check the event type and parse the payload of each event object, such as `invoice.paid`. Store the `subscription.id` and `customer.id` event objects in your database for verification.
[**Create a webhook**](api-42648310)
```JSON
{
"url": "https://apitest.wooshpay.com/v1/receives",
"description": "I am description",
"enabled_events": [
"checkout.session.completed",
"invoice.payment_failed",
"invoice.paid",
"payment_intent.succeeded",
"customer.created",
"customer.subscription.updated",
"customer.subscription.created"
]
}
```
The minimum event types to monitor:
| EVENT NAME | DESCRIPTION |
| -------------------------- | ------------------------------------------------------------ |
| checkout.session.completed | Sent when a customer clicks the Pay or Subscribe button in Checkout, informing you of a new purchase. |
| invoice.paid | Sent each billing interval when a payment succeeds. |
| invoice.payment_failed | Sent each billing interval if there is an issue with your customer’s payment method. |
## Delay payments on active subscriptions using trial periods.
When creating a subscription, you can alternatively use the `trial_period_days` parameter: an integer representing the number of days the trial lasts, from the current moment.
[**Create a Checkout Session**](api-42654181)
```JSON
{
"mode": "subscription",
"success_url": "https://yourwebsite.com",
"subscription_data":{
"trial_period_days":"1"
},
"line_items": [
{
"quantity": 1,
"price_data": {
"currency": "EUR",
"unit_amount": 15100,
"recurring": {
"interval": "weekly",
"interval_count": 1
},
"product_data": {
"name": "Shit",
"description": "tsetsetdescription1112",
"images": [
"https://appletservice.oss-cn-hangzhou.aliyuncs.com/checkout_0517/Snipaste_2023-08-10_16-35-10.png"
]
}
}
}
]
}
```
## Add discounts to subscriptions and subscription items using coupons
1. Discount applied only to the first subscription payment
**Create a coupon**
```JSON
{
"percent_off" :20,
"duration":"once",
"name" : "TEST 20% off"
}
```
**Apply coupons to Checkout**
Apply coupons to subscriptions in a Checkout Session by setting the `discounts` parameter in the API. To create a session with an applied discount, pass the coupon ID in the `coupon` parameter of the `discounts` array. This coupon overrides any coupon on the customer.
```JSON
{
"mode": "subscription",
"success_url": "https://yourwebsite.com",
"line_items": [
{
"quantity": 1,
"price":"price_1795818288165421056"
}
],
"discounts":[{
"coupon":"coupon_1866449681802854400"
}]
}
```
2. Discount applied to multiple billing cycles
**Create a coupon**
```JSON
{
"percent_off" :20,
"duration":"forever",
"name" : "TEST 20% off"
}
```
**Apply coupons to Checkout**
The`iterations` parameter indicates how many billing cycles the discount applies to in the subscription.
```JSON
{
"mode": "subscription",
"success_url": "https://yourwebsite.com",
"line_items": [
{
"quantity": 1,
"price":"price_1795818288165421056"
}
],
"discounts":[{
"coupon":"coupon_1866449681802854400",
"iterations":2
}]
}
```
# Test Your Integration
You can create a subscription plan with a five-minute billing cycle in the test environment using the example below.
**Create a Price**
*Request*
```JSON
{
"currency": "USD",
"product_data": {
"name":"Plus plan"
},
"unit_amount": 1000,
"active": true,
"recurring": {
"interval": "test_minute",
"interval_count": 5
}
}
```
**Create a Checkout Session**
*Request*
```JSON
{
"mode": "subscription",
"success_url":"https://yourwebsite.com",
"cancel_url":"https://yourwebsite.com"
"line_items": [
{
"quantity": 1,
"price":"price_XXXXXXXX"
}
]
}
```
*Response*
```JSON
{
"id": "cs_1796162148158668800",
"object": "checkout.session",
"created": 1717073402000,
"livemode": false,
"currency": "USD",
"customer": "",
"mode": "subscription",
"status": "open",
"url": "https://checkouttest.wooshpay.com/pay/cs_test_1796162148158668800?key=cGtfdGVzdF9OVEUzTWpFME9UUXpOalkyTkRrNU56ZzRPREV4T2pGbFJWaDNXWGxSTTBReE0wRnBkRmhZUm14T1JqTTBWVEUyT1RreU56RXlNVFU0T0RZ",
"line_items": {
"object": "list",
"data": [
{
"id": "li_1796162148209000448",
"object": "item",
"currency": "USD",
"description": "Plus plan",
"price": {
"id": "price_1796162090960945152",
"object": "price",
"created": 1717073388000,
"livemode": false,
"active": true,
"currency": "USD",
"product": {
"id": "prod_1796162090981916672",
"object": "product",
"created": 1717073388000,
"livemode": false,
"active": true,
"name": "Plus plan",
"updated": 1717073388000
},
"type": "recurring",
"recurring": {
"interval": "month",
"interval_count": 1,
"usage_type": "licensed"
},
"unit_amount": 1000,
"billing_scheme": "per_unit"
},
"quantity": 1,
"amount_subtotal": 1000,
"amount_total": 1000
}
]
},
"payment_intent": "pi_1796162148305469440",
"payment_method_types": [
"card"
],
"payment_status": "unpaid",
"success_url": "https://yourwebsite.com",
"amount_subtotal": 1000,
"amount_total": 1000,
"billing_address_collection": "auto",
"expires_at": 1717159801859,
"payment_link": "",
"client_secret": "pi_1796162148305469440_secret_zATcpA9yn8FObbcBwsbtHenl",
"customer_creation": "if_required",
"total_details": {
"amount_discount": 0
}
}
```
You will be redirected to WooshPay's checkout to complete the payment.
Please use the following test card number to complete the payment.
| Card Number | 4000020951595032 |
| ---------------- | ---------------- |
| Card Holder Name | FL-BRW1 |
| Expiration Month | 12 |
| Expiration Year | 25 |
| CVV | 217 |
After a successful payment, a second recurring payment will be generated and successfully processed 5 minutes later.
In 5 minutes, the third recurring payment will fail, and the subscription will be canceled.
Please note that subsequent transactions will not be generated after the third transaction is automatically created.