Skip to main content

Documentation

Create Subscription by Hosted Page

Create a subscription using a hosted page. Relevant to card payments.

Note

Deprecated endpoint - post /v1/checkout/subscription

Rapyd continues to support the deprecated endpoint. No sunset date has been set.

  • /v1/checkout/subscriptions

  • Create Subscription by Hosted Page

  • 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'
    -d '{
        "customer": "cus_d3ed65d5091a8398cc3651bcedec1201",
        "merchant_reference_id": "acct_111197",
        "country": "us",
        "language": "en",
        "billing": "pay_automatically",
        "simultaneous_invoice": true,
        "cancel_at_period_end": true,
        "coupon": "",
        "payment_fees": {
            "fx_fee": {
                "calc_type": "net",
                "fee_type": "percentage",
                "value": 2.5
            }
        },
        "payment_method_": "card_156da7de485275ad0bae798b7cb8fea1",
        "subscription_items": [
            {
                "plan": "plan_27921a1d4ebeb2db2e6aadf69a0094b1",
                "quantity": 1
            }
        ],
        "metadata": {
            "merchant_defined": true
        },
        "tax_percent": 10.5,
        "complete_payment_url": "https://example.com/thankyou",
        "error_payment_url": "https://example.com/error",
        "page_expiration": 1692276710,    
        "merchant_main_button": "pay"
    }'
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "f723ad19-1c7c-4f1f-be73-5dca009a54bc"
        },
        "data": {
            "id": "hp_sub_26db4525d0de8d999715b649a615dd3f",
            "status": "NEW",
            "cancel_url": "https://rapyd.net",
            "complete_url": "https://rapyd.net",
            "language": "en",
            "merchant_color": "323fff",
            "merchant_logo": "",
            "merchant_website": "https://rapyd.net",
            "merchant_customer_support": {},
            "merchant_alias": "Doc Team",
            "merchant_terms": "",
            "merchant_privacy_policy": "",
            "page_expiration": 1692276710,
            "redirect_url": "https://sandboxcheckout.rapyd.net/subscription?token=hp_sub_26db4525d0de8d999715b649a615dd3f",
            "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": "",
                    "created": 0,
                    "deleted": false,
                    "prorate": true,
                    "quantity": 1,
                    "plan_token": "plan_27921a1d4ebeb2db2e6aadf69a0094b1",
                    "clear_usage": false,
                    "proration_date": 0
                }
            ],
            "customer": "cus_d3ed65d5091a8398cc3651bcedec1201",
            "customer_payment_methods": [],
            "bank_redirect_customer_payment_methods": [],
            "country": "US",
            "trial_end": null,
            "trial_from_plan": false,
            "trial_period_days": 0,
            "tax_percent": 10.5,
            "billing_cycle_anchor": 0,
            "billing": "pay_automatically",
            "cancel_checkout_url": "https://rapyd.net",
            "complete_checkout_url": "https://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": {
                "merchant_defined": true
            },
            "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": "",
            "payment_method_types_include": null,
            "payment_method_types_exclude": null,
            "payment_method_type_categories": null
        }
    }
    
  • Create Subscription by Hosted Page with Trial Period

  • 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'
    -d '{
        "customer": "cus_9628d1fdd40158feec710fb36db83154",
        "country": "us",
        "billing": "pay_automatically",
        "cancel_at_period_end": true,
        "coupon": "",
        "payment_method": "card_156da7de485275ad0bae798b7cb8fea1",
        "subscription_items": [
            {
                "plan": "plan_243ae97f27d388df5a718cbc35688f75",
                "quantity": 1
            }
        ],
        "metadata": {
            "merchant_defined": true
        },
        "tax_percent": 10.5,
        "complete_payment_url": "https://example.com/thankyou",
        "error_payment_url": "https://example.com/error",
        "trial_end": 1649980020,
        "trial_from_plan": false
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "6563bf28-fa70-4536-9e39-0dbbe3a2ac4f"
        },
        "data": {
            "token": "hp_sub_2140d3eb871e9427a618790c653c881d",
            "status": "NEW",
            "cancel_url": "https://www.acmemusic123.net/cancel",
            "complete_url": "https://www.acmemusic123.net",
            "language": "",
            "merchant_color": "",
            "merchant_logo": "",
            "merchant_website": "https://www.rapyd.net",
            "merchant_customer_support": {},
            "merchant_alias": "Doc Team",
            "merchant_terms": "",
            "merchant_privacy_policy": "",
            "page_expiration": 0,
            "redirect_url": "https://sandboxhosted.rapyd.net/subscription?token=hp_sub_2140d3eb871e9427a618790c653c881d",
            "region": null,
            "geo_country": null,
            "merchant_main_button": "start_trial",
            "subscription_items": [
                {
                    "id": "",
                    "plan": {
                        "id": "de9a5bfc-ec56-4584-896e-83fd5fefb1ea",
                        "tiers": [],
                        "token": "plan_243ae97f27d388df5a718cbc35688f75",
                        "amount": 1,
                        "product": null,
                        "interval": "month",
                        "metadata": {},
                        "nickname": "Basic",
                        "created_at": 1648982677,
                        "deleted_at": 0,
                        "tiers_mode": "",
                        "usage_type": "licensed",
                        "product_name": "Acme music stream",
                        "product_type": "services",
                        "currency_code": "USD",
                        "product_token": "product_ca7685a10233e9bc0d82669e6a6c83d3",
                        "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": "",
                    "created": 0,
                    "deleted": false,
                    "prorate": true,
                    "quantity": 1,
                    "plan_token": "plan_243ae97f27d388df5a718cbc35688f75",
                    "clear_usage": false,
                    "proration_date": 0
                }
            ],
            "customer": "cus_9628d1fdd40158feec710fb36db83154",
            "country": "US",
            "trial_end": 1649980020,
            "trial_from_plan": false,
            "trial_period_days": 0,
            "tax_percent": 10.5,
            "billing_cycle_anchor": 0,
            "billing_address_collect": false,
            "billing": "pay_automatically",
            "cancel_checkout_url": "https://www.acmemusic123.net/cancel",
            "complete_checkout_url": "https://www.acmemusic123.net/cancel",
            "payment": null,
            "metadata": {
                "merchant_defined": true
            }
        }
    }
  • Create Subscription by Hosted Page with Coupon

  • 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'
    -d '{
        "subscription_items": [
            {
                "plan": "plan_9d7bc847f1ad3fe36f389273f5e22b56",
                "quantity": 1
            }
        ],
        "country": "US",
        "language": "EN",
        "customer": "cus_49ea9673acfbe53fac114fbf4bd94be3",
        "coupon": "coupon_da009d56dd6b7fdf4de28af673430a63",
        "billing": "pay_automatically",
        "tax_percent": 3,
        "enable_retries": false,
        "metadata": {
            "merchant_defined": true
        }
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "e81feab0-7216-4ebe-b51e-d1bfad487a48"
        },
        "data": {
            "id": "hp_sub_fc4ce3d974731b2305c333025a91bbaf",
            "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": "Doc Team",
            "merchant_terms": "",
            "merchant_privacy_policy": "",
            "page_expiration": 1701595266,
            "redirect_url": "https://sandboxcheckout.rapyd.net/subscription?token=hp_sub_fc4ce3d974731b2305c333025a91bbaf",
            "merchant_main_button": "subscribe",
            "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": 0,
            "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": {
                "merchant_defined": true
            },
            "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",
            "enable_retries": false
        }
    }
Related Information