Logo

SMARTy Docs

Subscriptions

The API allows for the creation of recurring payments, also known as subscriptions..

Guide: Subscriptions

The Subscription object

The Subscription object includes all relevant details about a subscription.

Properties

  • Name
    contractAddress
    Type
    string
    Description

    Unique identifier for the subscription, corresponding to the unique smart-contract address of the subscription.

  • Name
    planId
    Type
    string
    Description

    The identifier of the subscription plan.

  • Name
    amount
    Type
    money
    Description

    The price of the plan.

  • Name
    blockchain
    Type
    string
    Description

    The code of the blockchain network for this subscription.

  • Name
    customerId
    Type
    string
    Description

    The external identifier of the payer in the merchant's system.

  • Name
    payer
    Type
    string
    Description

    The blockchain address of the payer.

  • Name
    nextChargeAt
    Type
    string
    Description

    ISO8601 Timestamp of when the next charge is expected.

  • Name
    createdAt
    Type
    string
    Description

    ISO8601 Timestamp of when the subscription was created.

  • Name
    startFrom
    Type
    string
    Description

    ISO8601 Timestamp of when the subscription is expected to start.

  • Name
    maxPeriods
    Type
    number
    Description

    Number of recurrences of the subscription.

  • Name
    status
    Type
    string
    Description

    Status of the subscription.

POST/v1/subscriptions/customer-tokens

Create a customer token

This endpoint allows you to create a new customer token. Use this token to create a subscription via the widget.

Required attributes

  • Name
    merchantId
    Type
    string
    Description

    The identifier of the merchant this plan is related to.

  • Name
    customerId
    Type
    string
    Description

    The external identifier of the payer in the merchant's system.

Optional attributes

None

Error codes

If something goes wrong during the processing of this request the error code in standard format is returned.

See error codes

Request

POST
/v1/subscriptions/customer-tokens
curl --request POST \
  --url https://partner-api.smartypay.io/v1/subscriptions/customer-tokens \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "customerId": "cust-100311",
    "merchantId": "9xBoSUdGWeiAzMn5VHBvMB"
}'

Response

{
    "token":"y15G61QDgHaB6GecR6gBDhCpEFK6Eun6pID6lsX6etppjioT"
}
POST/v1/subscriptions/search

Search for subscriptions

This endpoint allows you to retrieve a paginated list of subscriptions that optionally can be filtered based on the predicates defined below.

Predicates are combined with AND semantics.

Read more about pagination

Required attributes

  • Name
    merchantId
    Type
    string
    Description

    The identifier of the merchant.

Optional attributes

  • Name
    page
    Type
    object
    Description

    Defines pagination and sorting options.

  • Name
    predicates.statusIn
    Type
    array
    Description

    List of subscription statuses to include into the result.

Request

POST
/v1/subscriptions/search
curl --request POST \
  --url https://partner-api.smartypay.io/v1/subscriptions/search \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "predicates": {
        "statusIn": [
            "Draft",
            "Active"
        ]
    },
    "page": {
        "limit": 5
    }
}'

Response

{
    "list": [
        {
            contractAddress: "0x98F8d711Fe2AF2Ae45ac74cE2b13bb9129c97c60",
            amount: {
                "value": "15",
                "currency": "btUSDTv2"
            },
            blockchain: "BinanceTestNet"
            createdAt: "2024-02-13T19:33:50.995971Z"
            customerId: "demo-24e87e5"
            maxPeriods: 1024
            nextChargeAt: "2024-03-15T19:33:50.779Z"
            payer: "0x3D5173fa845F84A259D53DddB674d0515b4C1b9F"
            planId: "M10A-crpSA6MdNCZX8_JXw"
            startFrom: "2024-02-13T19:33:50.779Z"
            status: "Active"
        },
        {
            "id": "rFI995vUhSIhXBhNe8Xv7x"
            // ...
        }
    ],
    "page": {
        "limit": 5,
        "offset": 0
    },
}
GET/v1/subscriptions/{subscriptionAddress}

Retrieve a subscription

This endpoint allows you to retrieve a subscription by providing their unique id.

Refer to the list at the top of this page to see which properties are included with subscription objects.

Request

GET
/v1/subscriptions/{subscriptionAddress}
curl https://partner-api.smartypay.io/v1/subscriptions/0x98F8d711Fe2AF2Ae45ac74cE2b13bb9129c97c60 \
  --user API_KEY:SECRET

Response

{
    contractAddress: "0x98F8d711Fe2AF2Ae45ac74cE2b13bb9129c97c60",
    amount: {
        "value": "15",
        "currency": "btUSDTv2"
    },
    blockchain: "BinanceTestNet"
    createdAt: "2024-02-13T19:33:50.995971Z"
    customerId: "demo-24e87e5"
    maxPeriods: 1024
    nextChargeAt: "2024-03-15T19:33:50.779Z"
    payer: "0x3D5173fa845F84A259D53DddB674d0515b4C1b9F"
    planId: "M10A-crpSA6MdNCZX8_JXw"
    startFrom: "2024-02-13T19:33:50.779Z"
    status: "Active"
}

Error codes

In case of error, you will receive the standard error object as a response with the following possible error codes. Use this code to handle them in an appropriate way.

The error codes listed below are only related to subscription plans; some generic errors might be also returned.

CodeHTTP CodeDescription
MerchantNotFound404The merchant that provided in merchantId attribute is not found.
SubscriptionNotFound404Subscription is not found.