Build subscriptions integration

Supported Payment method

Card

CARD BRAND	Popular country / region	Subscription
Visa	Global	✅
Mastercard	Global	✅

Wallets

Payment methods	Popular country / region	Subscription
Alipay	China	✅
AlipayHK	Hong Kong	✅
Boost	Malaysia	✅
DANA	Indonesia	✅
GCash	Philippines	✅
KakaoPay	South Korea	✅
Rabbit LINE Pay	Thailand	✅
Touch'n Go	Malaysia	✅
TrueMoney	Thailand	✅

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。

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <!-- Note: If using PHP set the action to /create-checkout-session.php -->

      <input type="hidden" name="priceId" value="price_1795818288165421056" />
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

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.

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.

Last modified: 4 个月前