Subscriptions

Subscriptions is a beta feature, things can change slightly here and there.

Use the API described below to integrate subscriptions into your app or e-commerce system.

To learn more about subscriptions, visit this section.

To create a subscription via API one should follow these steps:

1. Get active subscription plans.

2. Create a new subscription in a Draft state, and get a future contract address.

3. Broadcast a particular approve spending transaction into the blockchain, for the corresponding token and contract as a spender.

4. Activate subscription.

See also:

• See create signature logic.

• See a full example with signature creation.

• See the list of supported tokens for the possible amount values.

Things to consider:

1. Subscription plans should be created upfront via Merchant Admin UI.

2. Plans should be activated to be used.

3. API Key and Secret should be created.

4. ❗Gas Wallet for the corresponding network should be configured.

Returns active subscription plans

GET <api>/integration/subscription-plans

Query Parameters

Name	Type	Description
limit	Integer	Result limit
offset	Integer	Result offset

Headers

Name	Type	Description
x-api-key*	String	API Key
x-api-sig*	String	Signature created using API Secret
x-api-ts*	String	Timestamp of the request

200: OK Successful response

// Example
```json
{
    "plans": [
        {
            "id": "OHJXE_IURo-tE7Ou0GLnww",
            "description": "10GB Data plan for SkyX Mobile",
            "amount": "1.33 bUSDT",
            "periodSeconds": 300,
            "createdAt": "2022-12-14T12:57:07.455558Z",
            "tags": [],
            "status": "Active"
        }
    ]
}
```

Create a subscription

POST <api>/integration/subscriptions

Creates a new subscription in a Draft state, you should activate it by giving allowance for the subscription contract.

Headers

Name	Type	Description
x-api-key*	String	API Key
x-api-sig*	String	Signature created using API Secret
x-api-ts*	String	Timestamp of the request

Request Body

Name	Type	Description
planId*	String	ID of a subscription plan
customerId*	String	Customer correlation ID
payer*	String	Blockchain address of a payer
startFrom*	String	Date/time when invoice expires (in ISO 8601 format)
metadata*	String	Additional data to be passed with webhooks
maxPeriods	Integer	A limit for the maximum allowed charges, default is 24 periods.

200: OK Successful response

// Example
```json
{
    "contractAddress": "0xd90537f50e6273f904ac5d2cadc68b5dc679e36e",
    "planId": "OHJXE_IURo-tE7Ou0GLnww",
    "asset": "btMNXe",
    "blockchain": "BinanceTestNet",
    "customerId": "stage-user-001",
    "nextChargeAt": "2022-12-14T13:12:05Z",
    "payer": "0x14186c8215985f33845722730c6382443bf9ec65",
    "mode": "Simple",
    "createdAt": "2022-12-14T13:05:30.741431Z",
    "metadata": "002",
    "status": "Draft"
}
```

Returns subscriptions by filter

GET <api>/integration/subscriptions

Use this method to get a collection of subscriptions based on a filter.

Query Parameters

Name	Type	Description
customerId	String	External customer Id
payer	String	Address of the payer
statusIn	String	Comma-separated statuses
limit	Integer	Result limit
offset	Integer	Result offset

Headers

Name	Type	Description
x-api-key*	String	API Key
x-api-sig*	String	Signature created using API Secret
x-api-ts*	String	Timestamp of the request

200: OK Successful response

// Example
{
    "subscriptions": [
        {
            "contractAddress": "0xd90537f50e6273f904ac5d2cadc68b5dc679e36e",
            "planId": "OHJXE_IURo-tE7Ou0GLnww",
            "asset": "btMNXe",
            "blockchain": "BinanceTestNet",
            "customerId": "stage-user-001",
            "nextChargeAt": "2022-12-14T13:12:05Z",
            "payer": "0x14186c8215985f33845722730c6382443bf9ec65",
            "mode": "Simple",
            "createdAt": "2022-12-14T13:05:30.741431Z",
            "metadata": "002",
            "status": "Draft"
        }
    ],
    "page": {
        "limit": 100,
        "offset": 0
    }
}

Create access token for external widget

POST <api>/integration/subscriptions/create-customer-token

Headers

Name	Type	Description
x-api-key*	String	API Key
x-api-sig*	String	Signature created using API Secret
x-api-ts*	String	Timestamp of the request

Request Body

Name	Type	Description
customerId*	String	Customer correlation ID

200: OK Successful response

{
    "token": "....."
}