subscription

1. Retrieve Subscription Details

Step 1: Get Subscription List

Description: This step allows you to retrieve information about all of a user's subscriptions, including amounts, currency, identifiers, and statuses.

API Endpoint: GET /v1/subscriptions

Request Parameters:

userId (string, optional): The identifier of the user for whom you want to get subscriptions.

Example Request:

GET /reg/subscriptions?userId=exampleUserId

Example Response:

[
  {
    "amount": 0,  // amount of the subscription.
    "currency": "USD",  // currency of the subscription.
    "id": "8b3d1cdc-cd79-42ae-8040-7404c35a3026",  // unique identifier of the subscription.
    "nextPaymentDate": "2024-09-02T15:04:26.085Z",  // next payment date for the subscription.
    "status": "INIT"  // current status of the subscription.
  }
]

2. Create a New Subscription

Step 2: Create Subscription

Description: This step allows you to create a new subscription based on a subscription details identifier.

API Endpoint: POST /v1/subscriptions/create

Request Parameters:

subscriptionDetailsId (string): The identifier of the subscription form to use for creating a new subscription.

Example Request:

POST /reg/subscriptions/create

Example Response:

{
  "desc": "Subscription created successfully",  // description of the result.
  "id": "newSubscriptionId",  // unique identifier of the newly created subscription.
  "payUrl": "https://payment.example.com",  // URL to the payment page.
  "result": 0,  // result status code.
  "transactionId": "transactionIdExample"  // transaction identifier.
}

3. Retrieve Available Subscription Details

Step 3: Get Available Subscription Details

Description: This step allows you to get a list of available subscription forms, including their amounts, currency, descriptions, identifiers, names, and subscription intervals.

API Endpoint: GET /v1/subscriptions/details/available

Example Request:

GET /reg/subscriptions/details/available

Example Response:

[
  {
    "amount": 0,  // amount of the subscription detail.
    "currency": "USD",  // currency of the subscription detail.
    "description": "Basic Plan",  // description of the subscription detail.
    "id": "8b3d1cdc-cd79-42ae-8040-7404c35a3026",  // unique identifier of the subscription detail.
    "name": "Basic Plan",  // name of the subscription detail.
    "subscriptionInterval": "DAYS30"  // interval of the subscription.
  }
]

4. Handle Subscription Webhooks

Step 4: Handle Subscription Webhooks

Description: This step allows you to handle webhook notifications about subscription events, including invoice payments, initial and periodic payments, linked invoices, and status updates.

API Endpoint: POST /v1/subscriptions/webhook

Example Response:

{
  "amount": 100,  // amount needed to complete the invoice.
  "currency": "USD",  // currency of the invoice.
  "externalClientId": "exampleClientId",  // external client identifier.
  "id": "exampleInvoiceId",  // unique identifier of the invoice.
  "paymentDate": 1693678800000,  // payment date (timestamp).
  "type": "ORIGINAL",  // type of invoice.
  "initialPaymentAmount": 50,  // amount of the first payment for this recurrent invoice.
  "linkedInvoices": [  // list of linked invoices for payment.
    {
      "amount": 50,  // amount of the linked invoice.
      "currency": "USD",  // currency of the linked invoice.
      "id": "linkedInvoiceId1",  // unique identifier of the linked invoice.
      "paymentDate": 1693678800000,  // payment date (timestamp).
      "type": "RECURRING"  // type of the linked invoice.
    }
  ],
  "nextPaymentDate": 1694284800000,  // date of the next payment for this recurrent invoice (timestamp).
  "recurrentInvoiceInterval": "DAYS30",  // interval of the current recurrent invoice.
  "status": "INIT"  // current status of the recurrent invoice.
}

5. Cancel a Subscription

Step 5: Cancel Subscription

Description: This step allows you to cancel a user's subscription by its unique identifier.

API Endpoint: DELETE /v1/subscriptions/{subscriptionId}

Request Parameters:

subscriptionId (string): The unique identifier of the subscription to cancel.

Example Request:

DELETE /reg/subscriptions/8b3d1cdc-cd79-42ae-8040-7404c35a3026

6. Retrieve Subscription Details

Step 6: Get Subscription Details

Description: This step allows you to get information about a subscription by its unique identifier.

API Endpoint: GET /v1/subscriptions/{subscriptionId}

Request Parameters:

subscriptionId (string): The unique identifier of the subscription.

Example Request:

{
  "amount": 0,  // amount of the subscription.
  "currency": "USD",  // currency of the subscription.
  "externalClientId": "8b3d1cdc-cd79-42ae-8040-7404c35a3026",  // external client identifier.
  "id": "8b3d1cdc-cd79-42ae-8040-7404c35a3026",  // unique identifier of the subscription.
  "paymentDate": 0,  // payment date (timestamp).
  "type": "ORIGINAL",  // type of the subscription.
  "status": "CREATED"  // current status of the subscription.
}

7. Update Subscription Details

Step 7: Update Subscription

Description: This step allows you to update subscription details by its unique identifier.

API Endpoint: PUT /v1/subscriptions/{subscriptionId}

Request Parameters:

subscriptionId (string): The unique identifier of the subscription.
accountId (string): The identifier of the account associated with the subscription.

Example Request:

PUT /reg/subscription/123/?accountId=123

8. Renew Subscription

Step 8: Update Subscription

Description: This endpoint renews a subscription identified by subscriptionId.

API Endpoint: PUT /reg/subscription/{subscriptionId}/renew

Request Parameters:

subscriptionId (string): Unique identifier for the subscription to be renewed.

Example Request:

PUT /v1/subscriptions/8b3d1cdc-cd79-42ae-8040-7404c35a3026?accountId=exampleAccountId

Example Request:

{
  "desc": "Subscription renewed successfully",  // description of the result.
  "id": "8b3d1cdc-cd79-42ae-8040-7404c35a3026",  // unique identifier of the renewed subscription.
  "payUrl": "https://payment.example.com",  // URL to the payment page.
  "result": 0,  // result status code.
  "transactionId": "transactionIdExample"  // transaction identifier.
}

Choosing a Subscription Plan

Not sure which subscription plan to choose? You can explore our subscription options here to find the best fit for your needs.