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

Request

{
    "currency": "USD",
    "product_data": {
        "name":"Plus plan"
    },
    "unit_amount": 1000,
    "active": true,
    "recurring": {
         "interval": "month",
         "interval_count": 1
     }
}

Response

{
    "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。

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

Request

{
    "mode": "subscription",
    "success_url": "https://yourwebsite.com",
    "line_items": [
        {
            "quantity": 1,
            "price":"price_1795818288165421056"
        }
    ]
}

Response

{
    "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

After the subscription signup succeeds, the customer returns to your website at the success_url, which initiates a checkout.session.completed webhooks.

When you receive a checkout.session.completed event, you can provision the subscription.

Continue to provision each month (if billing monthly) as you receive invoice.paid events.

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

{
    "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

{
    "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

Discount applied only to the first subscription payment

Create a coupon

{
    "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.

{
    "mode": "subscription",
    "success_url": "https://yourwebsite.com",
    "line_items": [
        {
            "quantity": 1,
            "price":"price_1795818288165421056"
        }
    ],
    "discounts":[{
        "coupon":"coupon_1866449681802854400"
    }]
}

Discount applied to multiple billing cycles

Create a coupon

{
    "percent_off" :20,
    "duration":"forever",
    "name" : "TEST 20% off"
}

Apply coupons to Checkout

Theiterations parameter indicates how many billing cycles the discount applies to in the subscription.

{
    "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

{
    "currency": "USD",
    "product_data": {
        "name":"Plus plan"
    },
    "unit_amount": 1000,
    "active": true,
    "recurring": {
         "interval": "test_minute",
         "interval_count": 5
     }
}

Create a Checkout Session

Request

{
    "mode": "subscription",
    "success_url":"https://yourwebsite.com",
    "cancel_url":"https://yourwebsite.com"
    "line_items": [
        {
            "quantity": 1,
            "price":"price_XXXXXXXX"
        }
    ]
}

Response

{
    "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.

Build subscriptions integration

Card#

Wallets#

What you’ll build#

1.Create the pricing model#

2. Create a Checkout Session#

3. Provision and monitor subscriptions#

Delay payments on active subscriptions using trial periods.#

Add discounts to subscriptions and subscription items using coupons#

Test Your Integration#

Card

Wallets

What you’ll build

1.Create the pricing model

2. Create a Checkout Session

3. Provision and monitor subscriptions

Delay payments on active subscriptions using trial periods.

Add discounts to subscriptions and subscription items using coupons

Test Your Integration