Hosted Subscription Checkout Page
A secured page to accept your subscriptions payments.
Subscriptions are recurring transactions based on predefined billing cycles. Subscriptions work well for businesses that offer a service that can be renewed on a regular basis.
The Hosted Subscriptions Checkout Page enables you to collect recurring payments for products through the Fixed Price Plan. This hosted solution can allow you to effectively manage subscriptions for your organization, and more easily collect payments from customers by directing them to the Hosted Subscriptions Checkout Page.
Common use cases may include:
Accepting recurring payments from your customers without having to handle their credit card information.
Offering a subscriptions solution to other businesses or merchants without a PCI-DSS certification.
A no-code solution to generate a subscriptions page via the Client Portal.
Enter your payment information.
Enter your address and billing address.
Click Subscribe.
Complete 3DS Verification.
Redirect to the subscription success page.
Click Finish.
Supported Payment Methods
The following payment methods are supported for the Hosted Subscription Checkout Page:
Cards
Bank Redirect
Step 1: Create a Product for Your Subscription
Decide the product to use for your subscription.
Use Create Product to generate the product that will be used in the description. See Subscriptions - Create a Product for more detail about parameters.
Note: A product used in pricing plans must have their
typeset to service.Rapyd generates a product ID.
Rapyd sends a webhook response.
Step 2: Create a Plan for Your Subscription
You decide the pricing settings for your pricing plan.
Use Create Plan to generate your plan. See Subscriptions - Create a Plan for more details about parameters.
Rapyd generates a plan ID.
Rapyd sends a webhook reponse.
Note: The Hosted Subscription page can only be generated with the Fixed Price Plan.
Step 3: Create a Customer for Your Subscription.
Use Create Customer to generate a customer through the API for your subscription.
You ask Rapyd to generate a customer ID. See Subscriptions - Create a Customer Profile for more details about parameters.
Rapyd generates a unique customer ID.
Note: See Create Subscription by Hosted Page for more information on how to generate a Hosted Subscription Checkout page without Customer ID.
Step 4: Generate a Hosted Checkout Page for Subscriptions
You request Rapyd to generate a Hosted Subscription Checkout Page.
Rapyd processes your request and sends the response with the redirect URL.
You display the redirect URL to the customer.
The customer completes the payment on the hosted page.
The message sequence diagrams below describe how information is exchanged between Rapyd, the merchant, the merchant's customers, and the card network.
Create Hosted Subscription Page
Subscription payment information is collected by Rapyd through a generated hosted page. If a customer does not have a card on file, you can direct them to the Hosted Subscriptions Checkout page to collect their payment information for the subscription. In addition, you can generate multiple hosted pages and send them to different customers.
You can customize the look and feel of your page to match your brand and website experience as described in Customizing Your Hosted Page
You need to complete the following steps in order to generate a Hosted Subscriptions Checkout Page:
Create a Product (API integration)
Create a Plan (Create a pricing plan for the product through API integration)
Create a Customer (API Integration or via the Client Portal)
Generate a Hosted Checkout Page for Subscriptions (API Integration or via the Client Portal)
The Create Subscription by Hosted Page describes the parameters in the request in greater detail.
Body Parameter | Required | Description | Relates To |
|---|---|---|---|
subscription_items | yes | Array of subscription items. Each item contains a plan (required) and a quantity (optional).
| Subscription Object |
customer | yes | ID of the customer who pays for this subscription. String starting with cus_ | |
billing | yes | Determines the method of billing. Set to pay_automatically |
Request
// Request URL: GET https://sandboxapi.rapyd.net/v1/checkout/subscription // Message body: { "subscription_items": [ { "plan": "plan_9d7bc847f1ad3fe36f389273f5e22b56", "quantity": 1 } ], "country": "US", "language": "EN", "customer": "cus_49ea9673acfbe53fac114fbf4bd94be3", "coupon": "coupon_da009d56dd6b7fdf4de28af673430a63", "billing": "pay_automatically", "tax_percent": 3, "trial_period_days": 7, "metadata": [{ "my_meta_data_key": "metadata_value" }] }
Main Button Text
The merchant_main_button parameter in the request allows you to define the text for the main button for the Hosted Subscription page. This is for subscriptions that do not have trials.
The options for the button text are:
Subscribe
Purchase
Pay
When a subscription with a trial is used for the Hosted Subscription page, the default option of Start trial is used.
Create Subscription by Hosted Page describes the fields in the response.
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "9e7ede34-9c44-494f-b833-c1734afee646" }, "data": { "id": "hp_sub_f477f7b37e66ffef1b4be5becfccea46", "status": "NEW", "cancel_url": "https://www.rapyd.net", "complete_url": "https://www.rapyd.net", "language": "en", "merchant_color": "", "merchant_logo": "", "merchant_website": "https://www.rapyd.net", "merchant_customer_support": {}, "merchant_alias": "rap", "merchant_terms": "", "merchant_privacy_policy": "", "page_expiration": 1701594560, "redirect_url": "https://sandboxcheckout.rapyd.net/subscription?token=hp_sub_f477f7b37e66ffef1b4be5becfccea46", "merchant_main_button": "start_trial", "subscription_items": [ { "id": "", "plan": { "id": "09de6170-d76b-4450-8dcb-7833f5706384", "tiers": [], "token": "plan_9d7bc847f1ad3fe36f389273f5e22b56", "amount": 100, "product": null, "interval": "day", "metadata": { "merchant_defined": true }, "nickname": "hcp", "created_at": 1700384490, "deleted_at": 0, "tiers_mode": "", "usage_type": "licensed", "product_name": "HCP", "product_type": "service", "currency_code": "USD", "product_token": "product_eb45c8152bede037911d5e99ee4bc116", "billing_scheme": "per_unit", "interval_count": 20, "aggregate_usage": "sum", "organization_id": "", "transform_usage": {}, "product_is_active": 1, "trial_period_days": 0, "transform_usage_round": "up", "transform_usage_divide_by": 1 }, "token": "", "created": 0, "deleted": false, "prorate": true, "quantity": 1, "plan_token": "plan_9d7bc847f1ad3fe36f389273f5e22b56", "clear_usage": false, "proration_date": 0 } ], "customer": "cus_49ea9673acfbe53fac114fbf4bd94be3", "customer_payment_methods": [], "bank_redirect_customer_payment_methods": [], "country": "US", "trial_from_plan": false, "trial_period_days": 7, "tax_percent": 3, "billing_cycle_anchor": 0, "billing": "pay_automatically", "cancel_checkout_url": "https://www.rapyd.net", "complete_checkout_url": "https://www.rapyd.net", "payment": { "amount": null, "original_amount": 0, "is_partial": false, "currency_code": "", "country_code": "", "status": "", "description": "", "merchant_reference_id": "", "customer_token": "", "payment_method": "", "payment_method_data": {}, "expiration": 0, "captured": false, "refunded": false, "refunded_amount": 0, "receipt_email": "", "complete_payment_url": "", "error_payment_url": "", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "", "transaction_id": "", "metadata": null, "failure_code": "", "failure_message": "", "paid": false, "paid_at": 0, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": {}, "textual_codes": {}, "instructions": {}, "ewallet_id": null, "ewallets": [], "payment_method_options": {}, "payment_method_type": "", "payment_method_type_category": "", "fx_rate": "", "merchant_requested_currency": null, "merchant_requested_amount": null, "fixed_side": "", "payment_fees": null, "invoice": "", "escrow": null, "group_payment": "", "cancel_reason": null, "initiation_type": "", "mid": "", "next_action": "not_applicable" }, "metadata": [ { "my_meta_data_key": "metadata_value" } ], "custom_elements": { "save_card_default": false, "display_description": false, "payment_fees_display": true, "merchant_currency_only": false, "billing_address_collect": false, "dynamic_currency_conversion": false }, "payment_method_type": "", "coupon": "coupon_da009d56dd6b7fdf4de28af673430a63", } }
The data for this section shows:
The id of the subscription is sub_f477f7b37e66ffef1b4be5becfccea46.
The customer’s payment method will be charged every 20 days for the units they use for the subscription service.
The coupon ID is coupon_da009d56dd6b7fdf4de28af673430a63.
Hosted Subscription Page Coupon Support
Coupons are supported for Hosted Subscription pages. Pass the ‘coupon’ parameter in the request of Create Subscription by Hosted Page with the coupon ID, starting with coupon_.
You can also add a coupon by passing the ‘coupon’ parameter in the request of Create Customer. You then pass the Customer ID when creating the Hosted Subscription Page.