--- title: "Create Subscription by Hosted Page" source_url: https://docs.rapyd.net/en/create-subscription-by-hosted-page.html lang: en --- # Create Subscription by Hosted Page Create a subscription using a hosted page. Relevant to card payments. > **Note:** > > - This method replaces the following deprecated endpoint: post /v1/checkout/subscription > - Rapyd continues to support the deprecated endpoint. No sunset date has been set. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Body Parameters - - billing - Determines the method of billing at the end of the billing cycle. Set to **pay_automatically** - Rapyd generates a `payment` object, then attempts to pay it using the designated payment method. - - cancel_at_period_end - Determines the last date that charges accrue. - **true** - Charges accrue until the end of the current billing period, then the subscription is canceled. - When no trial period is set, after this parameter is set to **true** the subscription will not be renewed at the next interval. - When a trial period is set after this parameter is set to **true**, the subscription will not begin. - **false** - When the subscription is created, no end is defined. When [Cancel Subscription](https://docs.rapyd.net/en/cancel-subscription.md "Cancel Subscription") is run, charges stop immediately and the subscription is canceled. false - - complete_payment_url - URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs. - - country - The two-letter ISO 3166-1 ALPHA-2 code for the country. - - coupon - ID of a coupon to apply a discount to the subscription. If the coupon defines a fixed monetary discount, it must use the same currency as the subscription. String starting with **coupon_**. - - customer - ID of the customer who pays for this subscription. String starting with **cus_**. - - days_until_due - Number of days the customer has for paying this invoice. - - error_payment_url - URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs. - - language - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages"). - When this parameter is null, the language of the user's browser is used. - If the language of the user's browser cannot be determined, the default language is English. - - merchant_main_button - Defines the text for the call-to-action button on the subscription checkout page. - When there is no trial period, the values are: - **subscribe** (default) - **purchase** - **pay** - When there is a trial period, the value is **start_trial** (default) - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - page_expiration - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation. **Range:** 1 minute to 30 days. - - payment_fees - Defines transaction fees and foreign exchange fees. These are fees that the Rapyd merchant can define for its consumers in addition to the payment amount. They are not related to the fees Rapyd charges to its clients. - - transaction_fee - Describes the fee for processing the transaction. - - calc_type - Specifies how the fee is calculated. One of the following: - **net** - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet. - **gross** - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00. - - fee_type - One of the following: - **percentage** - A percentage of the transaction amount. For example, 5 percent is represented by **value=5**. - **absolute** - A fixed amount. - - value - The amount of the fee. - - fx_fee - Describes the fees for processing the currency exchange. Relevant to payments with FX. - - calc_type - Specifies how the fee is calculated. One of the following: - **net** - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet. - **gross** - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00. - - value - The amount of the fee. Percentage. - - gross_fees - The total gross fees for the transaction, in units defined by `currency_code`. - - net_fees - The total net fees for the transaction, in units defined by `merchant_requested_currency`. - - total_merchant_fees - The amount of the fee. - - payment_fields - Additional `payment_options` fields. - - payment_method - Payment method used for paying invoices generated by this subscription. The ID is a string starting with **card_** or **other_**. - - subscription_items - An array of objects containing the following fields. Currently supports a single plan and product. - - plan - ID of a plan that describes the service and pricing structure. The plan must be active. > **Note:** > > - The values for `interval` and `interval_count` must be the same in all plans. > - The value of `billing_scheme` must be **per_unit** in all plans. - - quantity - Number of units of the service described in `plan`. - - tax_percent - The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal. Range: 0-100, with up to four decimal places. - - trial_end - The date and time of the end of the customer's free trial period, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"), or the string **now**. Takes precedence over `trial_period_days`. If `trial_end` is not set by the client, Rapyd calculates this date by adding `trial_period_days` to the date in `created_at`. Relevant when `trial_period_days` is not defined. - - trial_from_plan - Determines whether a free trial period can be defined in a 'plan' object attached to the subscription. - **true** - Free trials can be defined in plans that are attached to the subscription. - **false** - Definitions of free trial in plans are ignored. false - - trial_period_days - The number of days in the customer's free trial period. Integer. Range: 0-730. This value takes precedence over trial periods that are defined in a plan. Relevant when `trial_end` is not defined. ### Response Parameters - - billing - Determines the method of billing at the end of the billing cycle. Set to **pay_automatically** - Rapyd generates a `payment` object, then attempts to pay it using the designated payment method. - - billing_cycle_anchor - Determines the start of the next full billing cycle, as defined in the plan described in the `items`. One of the following values: - **now** - The present day. The next billing cycle starts right now. - *Timestamp* in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") - A time in the future, at or after the end of the free trial period, not more than the length of the billing cycle. The current billing cycle will be shorter than all other billing cycles. Relevant to creating a subscription. - **unchanged** - The original billing cycle anchor is unchanged. Relevant to updating a subscription. - - cancel_at_period_end - Determines the last date that charges accrue. - **true** - Charges accrue until the end of the current billing period, then the subscription is canceled. - When no trial period is set, after `cancel_at_period_end` is set to **true** the subscription will not be renewed at the next interval. - When a trial period is set after `cancel_at_period_end` is set to **true**, the subscription will not begin. - **false** - When the subscription is created, no end is defined. When [Cancel Subscription](https://docs.rapyd.net/en/cancel-subscription.md "Cancel Subscription") is run, charges stop immediately and the subscription is canceled. - - cancel_checkout_url - URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - canceled_at - Date and time that the subscription is canceled by the customer or by the client. [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - complete_checkout_url - URL where the customer is redirected after pressing **Finish** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - complete_payment_url - URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs. - - country - The two-letter ISO 3166-1 ALPHA-2 code for the country. - - coupon - ID of a coupon to apply a discount to the subscription. String starting with **coupon_**. - - created_at - Time of creation of this subscription, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - current_period_end - End of the current billing cycle, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - current_period_start - Start of the current billing cycle, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - custom_elements - Describes customizations of the hosted page as it appears to the customer. - - billing_address_collect - Determines whether the customer is asked to fill in the billing address. Relevant when a card payment method is selected. - **true** - The address fields appear on the checkout page. - **false** - The address fields appear only if the `country` is **US**, **GB** or **CA**. false > **Note:** > > When the customer already has address details, it is always displayed. - - cardholder_name - The name of the card owner, printed on the front of the card. - - display_description - Determines whether the checkout page displays the payment description. - **true** - The payment description appears. - **false** - The payment description does not appear. false Relevant when `description` is passed in the [Create Checkout Page](https://docs.rapyd.net/en/create-checkout-page.md "Create Checkout Page") request. - - dynamic_currency_conversion - Determines whether the checkout page displays multiple currency options for a payment. - **true** - Multiple currency options appear. - **false** - Currency options do not appear. false When the customer selects the requested currency, the checkout page displays the following information: - The original amount and currency. - The converted amount in the requested currency. - The exchange rate. Relevant when: - The [Create Checkout Page](https://docs.rapyd.net/en/create-checkout-page.md "Create Checkout Page") request passes `requested_currency`. - `fixed_side` is **buy**. - One or more payment methods support the values for `currency` and `requested_currency`. - - merchant_color - Reserved. - - merchant_currency_only - In a payment with FX where `fixed_side`=**buy**, determines whether the buyer's currency and the exchange rate appear. One of the following: - **true** - The currency and the exchange rate are hidden. - **false** - The currency and the exchange rate appear. false - - payment_fees_display - Determines whether payment fees appear on the checkout page. - **true** - Payment fees appear when the `payment_fees` object is set in the [Create Checkout Page](https://docs.rapyd.net/en/create-checkout-page.md "Create Checkout Page") request. - **false** - Payment fees do not appear. true - - required_customer_fields - Indicates the list of fields that the customer has to fill in on the payment page before completing the payment via hosted checkout. Valid values include: - **name**– The customer's full name (default). - **email** – The customer's email address. - **phone_number** – The customer's phone number. - **address** – The address of the customer. - - save_card_default - Determines whether the **save card** checkbox is checked by default. - **true** - The **save card** checkbox is checked. - **false** - The **save card** checkbox is cleared. false Relevant when `customer_id` is passed in the [Create Checkout Page](https://docs.rapyd.net/en/create-checkout-page.md "Create Checkout Page") request. - - customer - ID of the customer who pays for this subscription. String starting with **cus_**. - - days_until_due - Number of days the customer has for paying this invoice. - - discount - Contains information about the coupon that applies to the subscription. Returned as a **null** value when there is no discount. - - error_payment_url - URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs. - - id - ID of the subscription. String starting with **hp_sub_**. - - language - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages"). - When this parameter is null, the language of the user's browser is used. - If the language of the user's browser cannot be determined, the default language is English. - - merchant_alias - Client's name. Rapyd - - merchant_color - Color of the call-to-action (CTA) button on the hosted page. To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - merchant_customer_support - Contains details of the client’s customer support. To configure these fields, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - email - Email address. - - url - URL for the client's customer support service. - - phone_number - Phone number for contacting the client's customer support service. - - merchant_main_button - Indicates the text for the call-to-action button on the subscription checkout page. - - merchant_privacy_policy - URL for the terms and conditions of the agreement between the client and the client’s customers. To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - merchant_terms - URL for the client's terms and conditions. To configure this field, use the Client Portal. - - merchant_website - The URL where the customer is redirected after exiting the hosted page. Relevant when one or both of the following fields is unset: - `cancel_url` - `complete_url` To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page"). - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - page_expiration - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation. **Range:** 1 minute to 30 days. - - payment - Describes the payment that will result from the hosted page. The `id` and `status` values are **null** until the customer successfully submits the information on the hosted page. For more information about the fields in the 'payment' object, see [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment"). - - payment_fields - Additional `payment_options` fields. - - payment_method - Payment method used for paying invoices generated by this subscription. The ID is a string starting with **card_** or **other_**. - - redirect_url - URL of the hosted page that is shown to the customer. - - status - Status of the subscription. One of the following: - **active** - The customer is currently paying for this subscription. - **canceled** - The customer has canceled this subscription, but it remains in the Rapyd database. - **past_due** - Payment for this subscription was not received by the end of the billing period. - **trialing** - The subscription is in its free trial period. - **unpaid** - An error occurred in the payment for this subscription. - - subscription_items - An array of objects containing fields. Currently supports a single plan and product. For more information about the fields in the 'subscription_item' object, see [Create Subscription Item](https://docs.rapyd.net/en/create-subscription-item.md "Create Subscription Item"). - - tax_percent - The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal. Range: 0-100, with up to four decimal places. - - total_count - Total number of subscription items. - - trial_end - The date and time of the end of the customer's free trial period, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"), or the string **now**. Takes precedence over `trial_period_days`. If `trial_end` is not set by the client, Rapyd calculates this date by adding `trial_period_days` to the date in `created_at`. Relevant when `trial_period_days` is not defined. - - trial_from_plan - Determines whether a free trial period can be defined in a plan attached to the subscription. - - trial_period_days - The number of days in the customer's free trial period. Integer. Range: 0-730. This value takes precedence over trial periods that are defined in a plan. Relevant when `trial_end` is not defined. - - trial_start - Date and time of the start of the customer's free trial period, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - /v1/checkout/subscriptions - Create Subscription by Hosted Page - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/checkout/subscriptions' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "customer": "cus_4e25112ac20e144ad073a614dc46934b", "country": "IS", "billing": "pay_automatically", "payment_method_": "card_0ef78a1d5cbd4d84133c8d94b2d34a4f", "subscription_items": [ { "plan": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "quantity": 1 } ], "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "page_expiration": 1795276710, "merchant_main_button": "pay" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "45658970-a9f2-406b-8fa6-834fd377aef8" }, "data": { "id": "hp_sub_2c95c21982da9182db37a0182a5a80dd", "status": "NEW", "cancel_url": "https://example1234.net", "complete_url": "https://example1234.net", "language": "", "merchant_color": "323fff", "merchant_logo": "", "merchant_website": "https://example1234.net", "merchant_customer_support": { "url": "https://example1234.net", "email": "support@example1234.net", "phone_number": "121255551213" }, "merchant_alias": "Doc Team", "merchant_terms": "https://example1234.net/terms_and_conditions", "merchant_privacy_policy": "https://example1234.net/privacy_policy", "page_expiration": 1764160568, "redirect_url": "https://sandboxcheckout.rapyd.net/subscription?token=hp_sub_2c95c21982da9182db37a0182a5a80dd", "merchant_main_button": "pay", "subscription_items": [ { "id": "", "plan": { "id": "8993ac69-bd12-4cf2-aa8f-019081441303", "tiers": [], "token": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "amount": 5, "product": null, "interval": "month", "metadata": {}, "nickname": "Basic", "created_at": 1669022872, "deleted_at": 0, "tiers_mode": "", "usage_type": "licensed", "product_name": "Music Streaming", "product_type": "services", "currency_code": "USD", "product_token": "product_8a9a3932967cb7f2caf91d3cc07be5c8", "billing_scheme": "per_unit", "interval_count": 1, "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": "", "org_id": "", "created": 0, "deleted": false, "prorate": true, "quantity": 1, "plan_token": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "clear_usage": false, "proration_date": 0 } ], "customer": "cus_4e25112ac20e144ad073a614dc46934b", "customer_payment_methods": [], "bank_redirect_customer_payment_methods": [], "country": "IS", "trial_from_plan": false, "trial_period_days": 0, "tax_percent": 0, "billing_cycle_anchor": 0, "billing": "pay_automatically", "cancel_checkout_url": "https://example1234.net", "complete_checkout_url": "https://example1234.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", "merchant_ewallet": null }, "custom_elements": { "hide_save_card": false, "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": "" } } ``` - Create Subscription by Hosted Page with Trial Period - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/checkout/subscriptions' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "customer": "cus_4e25112ac20e144ad073a614dc46934b", "country": "IS", "billing": "pay_automatically", "payment_method_": "card_0ef78a1d5cbd4d84133c8d94b2d34a4f", "subscription_items": [ { "plan": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "quantity": 1 } ], "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "page_expiration": 1795276710, "merchant_main_button": "pay", "cancel_at_period_end": true, "trial_end": 1795276710, "trial_from_plan": false }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "1c53ec2b-73f8-474a-b76e-55cd8b13994f" }, "data": { "id": "hp_sub_2e44f86f1970448810e53f306efae10b", "status": "NEW", "cancel_url": "https://example1234.net", "complete_url": "https://example1234.net", "language": "", "merchant_color": "323fff", "merchant_logo": "", "merchant_website": "https://example1234.net", "merchant_customer_support": { "url": "https://example1234.net", "email": "support@example1234.net", "phone_number": "121255551213" }, "merchant_alias": "Doc Team", "merchant_terms": "https://example1234.net/terms_and_conditions", "merchant_privacy_policy": "https://example1234.net/privacy_policy", "page_expiration": 1764160819, "redirect_url": "https://sandboxcheckout.rapyd.net/subscription?token=hp_sub_2e44f86f1970448810e53f306efae10b", "merchant_main_button": "start_trial", "subscription_items": [ { "id": "", "plan": { "id": "8993ac69-bd12-4cf2-aa8f-019081441303", "tiers": [], "token": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "amount": 5, "product": null, "interval": "month", "metadata": {}, "nickname": "Basic", "created_at": 1669022872, "deleted_at": 0, "tiers_mode": "", "usage_type": "licensed", "product_name": "Music Streaming", "product_type": "services", "currency_code": "USD", "product_token": "product_8a9a3932967cb7f2caf91d3cc07be5c8", "billing_scheme": "per_unit", "interval_count": 1, "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": "", "org_id": "", "created": 0, "deleted": false, "prorate": true, "quantity": 1, "plan_token": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "clear_usage": false, "proration_date": 0 } ], "customer": "cus_4e25112ac20e144ad073a614dc46934b", "customer_payment_methods": [], "bank_redirect_customer_payment_methods": [], "country": "IS", "trial_end": 1795276710, "trial_from_plan": false, "trial_period_days": 0, "tax_percent": 0, "billing_cycle_anchor": 0, "billing": "pay_automatically", "cancel_checkout_url": "https://example1234.net", "complete_checkout_url": "https://example1234.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", "merchant_ewallet": null }, "custom_elements": { "hide_save_card": false, "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": "" } } ``` - Create Subscription by Hosted Page with Coupon - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/checkout/subscriptions' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "customer": "cus_4e25112ac20e144ad073a614dc46934b", "country": "IS", "billing": "pay_automatically", "payment_method_": "card_0ef78a1d5cbd4d84133c8d94b2d34a4f", "subscription_items": [ { "plan": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "quantity": 1 } ], "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "page_expiration": 1795276710, "merchant_main_button": "pay", "coupon": "coupon_e4ea7af090c212aa2634b6d88a308a80" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "b20242dc-4147-4300-b701-e5c2fb19a62b" }, "data": { "id": "hp_sub_bb61e733db533c95125ab96c24a97cb3", "status": "NEW", "cancel_url": "https://example1234.net", "complete_url": "https://example1234.net", "language": "", "merchant_color": "323fff", "merchant_logo": "", "merchant_website": "https://example1234.net", "merchant_customer_support": { "url": "https://example1234.net", "email": "support@example1234.net", "phone_number": "121255551213" }, "merchant_alias": "Doc Team", "merchant_terms": "https://example1234.net/terms_and_conditions", "merchant_privacy_policy": "https://example1234.net/privacy_policy", "page_expiration": 1764161258, "redirect_url": "https://sandboxcheckout.rapyd.net/subscription?token=hp_sub_bb61e733db533c95125ab96c24a97cb3", "merchant_main_button": "pay", "subscription_items": [ { "id": "", "plan": { "id": "8993ac69-bd12-4cf2-aa8f-019081441303", "tiers": [], "token": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "amount": 5, "product": null, "interval": "month", "metadata": {}, "nickname": "Basic", "created_at": 1669022872, "deleted_at": 0, "tiers_mode": "", "usage_type": "licensed", "product_name": "Music Streaming", "product_type": "services", "currency_code": "USD", "product_token": "product_8a9a3932967cb7f2caf91d3cc07be5c8", "billing_scheme": "per_unit", "interval_count": 1, "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": "", "org_id": "", "created": 0, "deleted": false, "prorate": true, "quantity": 1, "plan_token": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "clear_usage": false, "proration_date": 0 } ], "customer": "cus_4e25112ac20e144ad073a614dc46934b", "customer_payment_methods": [], "bank_redirect_customer_payment_methods": [], "country": "IS", "trial_from_plan": false, "trial_period_days": 0, "tax_percent": 0, "billing_cycle_anchor": 0, "billing": "pay_automatically", "cancel_checkout_url": "https://example1234.net", "complete_checkout_url": "https://example1234.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", "merchant_ewallet": null }, "custom_elements": { "hide_save_card": false, "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_e4ea7af090c212aa2634b6d88a308a80" } } ``` - Bad Request - Customer Not Found - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/checkout/subscriptions' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "customer": "cus_4e25112ac20e144ad073a614dc46934", "country": "IS", "billing": "pay_automatically", "payment_method_": "card_0ef78a1d5cbd4d84133c8d94b2d34a4f", "subscription_items": [ { "plan": "plan_27921a1d4ebeb2db2e6aadf69a0094b1", "quantity": 1 } ], "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "page_expiration": 1795276710, "merchant_main_button": "pay" }' ``` - ```json { "status": { "error_code": "ERROR_HOSTED_PAGE_GET_CUSTOMER", "status": "ERROR", "message": "The request tried to create a checkout page, but the customer was not found. The request was rejected. Corrective action: For 'customer', provide a valid customer ID, a string starting with 'cus_'.", "response_code": "ERROR_HOSTED_PAGE_GET_CUSTOMER", "operation_id": "3b133e78-1df5-4b14-9002-6b3ff7586b8d" } } ``` - Bad Request - Plan Not Found - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/checkout/subscriptions' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "customer": "cus_4e25112ac20e144ad073a614dc46934b", "country": "IS", "billing": "pay_automatically", "payment_method_": "card_0ef78a1d5cbd4d84133c8d94b2d34a4f", "subscription_items": [ { "plan": "plan_27921a1d4ebeb2db2e6aadf69a0094b", "quantity": 1 } ], "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "page_expiration": 1795276710, "merchant_main_button": "pay" }' ``` - ```json { "status": { "error_code": "ERROR_GET_PLAN", "status": "ERROR", "message": "The request tried to retrieve a plan, but the plan was not found. The request was rejected. Corrective action: Use a valid plan ID.", "response_code": "ERROR_GET_PLAN", "operation_id": "6410bb34-9683-4cad-8908-17633d4782d0" } } ``` ### Related Information - [Hosted Subscription Checkout Page](https://docs.rapyd.net/en/hosted-subscription-checkout-page.md "Hosted Subscription Checkout Page")