LoginGet Started

Accept Crypto Subscription Payment

Example of how to create a recurring subscription using Copperx APIs

Overview

This guide provides an example of how to create a recurring subscription using Copperx APIs. In this example, we will set up a subscription payment for 10 USDC per month.

Prerequisites

Before starting, ensure you have the following:

  1. Development Environment: We will use the Polygon Mumbai Testnet and Goerli Testnet. https://dashboard.copperx.dev

  2. API Key: Generate your API key from the Copperx Dashboard. If you don't have one, then generate it from here.

  3. Test ERC20 Faucets: You can request test tokens from Goerli Faucet and Polygon Faucet. For additional test tokens, contact our team. As you are using test environment, there is no real money involved. So feel free to play around.

  4. Copperx Account: Ensure you have an account to access the dashboard.

Steps to Create a Subscription

1. Create a Plan in Copperx Dashboard

To start a subscription, you first need to create a plan in the Copperx Dashboard.

  1. Go to the Copperx Dashboard.

  2. Log in with your Copperx account.

  3. Click on Billing in the top menu and select Plans.

  4. Click the Create Plan button in the top-right corner.

  5. Fill in the plan details:

    • Title: Plan title

    • Description: Plan description

    • Recurring Interval: Set to monthly

    • Price: Set to 10 USDC

  6. Click the Create Plan button.

Congratulations! 🎉 You have successfully created your first plan on Copperx.

Congratulations 🎉, you have successfully created your first plan on Copperx.

2. Create a Checkout Session

To create a subscription, you need to create a Checkout Session using the priceId of the newly created plan.

  1. Open Plans dashboard (https://dashboard.copperx.dev/billing/plans)

  2. Find the plan for which you want to create a Checkout Session.

  3. Click ••• > Details to find more details.

  4. On details page, you will find a field called Plan Id.

  5. Press Copy icon to copy Price Id

Now let's go ahead and create subscription of our plan.

To create a checkout session, run below command in your terminal:

Make sure you update YOUR_API_KEY and PRICE_ID in the code.

curl --request POST \
--url 'https://api.copperx.io/api/v1/checkout/sessions' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json'
--data-raw '{
    "successUrl": "https://copperx.io?cid={CHECKOUT_SESSION_ID}",
    "mode": "subscription",
    "lineItems": [{
        "priceId": "{PRICE_ID}" 
    }],
    "emailCollection": true,
}'

You will receive the responsive as below:

{
    "id": "6c88e598-335d-468b-aea5-fa7a3aa074bf",
    "createdAt": "2023-04-03T17:57:16.943Z",
    "updatedAt": "2023-04-03T17:57:16.982Z",
    "mode": "subscription",
    "paymentMethodTypes": [
        "allowance_based_recurring"
    ],
    "paymentSetting": {
        "allowedChains": [
            {
                "chainId": 137
            }
        ],
        "paymentMethodTypes": null,
        "preferredChainId": 137,
        "allowSwap": false
    },
    "expiresAt": "2023-04-03T18:57:16.940Z",
    "customerCreation": "if_required",
    "customerUpdate": null,
    "submitType": "pay",
    "afterCompletion": null,
    "organizationId": "758cbac4-58b8-4e0a-b1a2-27b60d4b148d",
    "amountTotal": "10000000",
    "currency": "usdc",
    "paymentLinkId": null,
    "subscriptionId": null, // This is set as soon use complete checkout session for subscription
    "customerId": "820b4fa9-8f4d-4866-9333-527752e32775",
    "clientReferenceId": null,
    "successUrl": "https://copperx.io?cid=6c88e598-335d-468b-aea5-fa7a3aa074bf",
    "cancelUrl": null,
    "status": "open",
    "paymentStatus": "unpaid",
    "metadata": null,
    "emailCollection": false,
    "phoneNumberCollection": false,
    "shippingAddressCollection": false,
    "billingAddressCollection": false,
    "afterCompletionConfirmMsg": null,
    "shippingDetails": {},
    "billingDetails": {},
    "url": "https://buy.copperx.io/payment/checkout-session/6c88e598-335d-468b-aea5-fa7a3aa074bf",
    "customer": {
        "name": null,
        "email": "support@example.com",
        "phone": null,
        "id": "820b4fa9-8f4d-4866-9333-527752e32775",
        "createdAt": "2023-04-03T17:57:16.921Z",
        "updatedAt": "2023-04-03T17:57:16.921Z",
        "customerReferenceId": null,
        "visibility": 10,
        "metadata": {}
    },
    "customerDetails": {
        "name": null,
        "email": null,
        "phone": null,
        "address": {}
    },
    "lineItems": {
        "object": "list",
        "data": [
            {
                "amountTotal": "10000000",
                "currency": "usdc",
                "description": null,
                "quantity": 1,
                "price": {
                    "id": "ae575f1d-57b0-47cd-b40b-f1c2a057c067",
                    "createdAt": "2023-04-03T17:57:16.909Z",
                    "updatedAt": "2023-04-03T17:57:16.909Z",
                    "billingScheme": "per_unit",
                    "currency": "usdc",
                    "productId": "a90004dc-48be-4d21-9f45-05cc3acacc52",
                    "interval": "month",
                    "usageType": null,
                    "type": "recurring",
                    "unitAmount": "10000000",
                    "unitAmountDecimal": null,
                    "customUnitMax": null,
                    "customUnitMin": null,
                    "customPreset": null,
                    "customUnitAmountSuggestions": null,
                    "product": {
                        "id": "a90004dc-48be-4d21-9f45-05cc3acacc52",
                        "createdAt": "2023-04-03T17:57:16.903Z",
                        "updatedAt": "2023-04-03T17:57:16.918Z",
                        "name": "Basic",
                        "description": "For early stage projects who are getting started",
                        "isActive": true,
                        "images": [],
                        "unitLabel": null,
                        "url": null,
                        "metadata": null,
                        "defaultPriceId": "ae575f1d-57b0-47cd-b40b-f1c2a057c067",
                        "visibility": 20
                    },
                    "metadata": null,
                    "isActive": true,
                    "visibility": 20
                }
            }
        ]
    },
    "addresses": [
        {
            "id": "c0e4bd0d-e7a4-4202-ac4d-f7bc60e6c474",
            "createdAt": "2023-04-03T17:57:16.982Z",
            "updatedAt": "2023-04-03T17:57:16.982Z",
            "checkoutSessionId": "6c88e598-335d-468b-aea5-fa7a3aa074bf",
            "asset": {
                "id": "13056880-798b-4bd4-a555-c1c71de017fa",
                "name": "USDC",
                "address": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
                "chainId": 137,
                "currency": "usdc",
                "symbol": "USDC",
                "decimals": 6,
                "coingeckoId": "usd-coin",
                "isPublic": true,
                "superToken": {
                    "address": "0xcaa7349cea390f89641fe306d93591f87595dc1f",
                    "symbol": "USDCx",
                    "decimals": 18
                },
                "chain": {
                    "id": 137,
                    "name": "Polygon",
                    "icon": "icon",
                    "currency": "matic",
                    "blockExplorerName": "Polygonscan",
                    "blockExplorerTransactionUrl": "https://polygonscan.com/tx/{hash}"
                }
            },
            "paymentAddress": "0xd55069e3b3a088dfe3690decac89740b897bd1e7"
        }
    ],
    ...
}

Here,

id = Unique Identifier for Checkout Session

amountTotal = Amount to be collected from user (in 8 decimal)

currency = Payment Currency

url = Hosted Checkout page for the Session. You need to redirect user to this URL.

To know more about the full Checkout Session object, click here.

Once you create a Checkout Session, you need to redirect user to the give URL in url parameter of the response.

Once user makes the payment, user will be redirected to the URL provided in successUrl.

If user cancels the payment, then user will be redirected to the URL provided in cancelUrl.

Learn More

To learn more about handling subscription webhooks and the subscription lifecycle, refer to the following documentation pages:

If you are facing issues while using our API, feel free to contact us on support@copperx.io.

PreviousAccept Crypto PaymentNextSubscription Lifecycle

Last updated