Skip to content

Subscriptions

Subscriptions link your customers to your plans, and they are responsible for billing and charging on your recurring intervals.

Once a subscription has been created, it will begin to auto-renew on the period specified by the plan to which it is related. You may track your subscription in the bePaid back office or be subscribed in a shop notification settings on e-mails about processed transactions. Additionally, bePaid will post webhook notification to notification_url given in a subscription creation request.

Subscription statuses

Status Description
pending An initial status. All newly created subscriptions are set to that internal status before to start processing.
trial A subscription is active or cancelled and is in a trial period
trial_processing A subscription is a phase to collect overdue balances for a trial period
processing A subscription is in a phase to collect subscription overdue balances.
active A normal, active subscription. It is not in a trial, and is paid and up to date.
failed A failed subscription. bePaid was unable to collect the subscription overdue balance.
error An error occurred when bePaid tried to collect the subscription overdue balance.
canceled A subscription is cancelled and will not renew anymore.

Create a subscription

Request

To create a subscription, send a POST request to https://api.bepaid.by/subscriptions with the following parameters:

Parameter Type Description
customer object A customer resource. It includes either a customer ID or full customer details.
plan * required
 object A plan resource. It includes either a plan ID or full plan details.
dynamic_billing_descriptor string A dynamic billing descriptor.
tracking_id string(255) A ID of your transaction or order. Please, use unique values in order to get transaction information by query request otherwise, you will get the first transaction that we will find with tracking_id.
device_id string A device ID of customer subscribing on your service.
return_url string A URL where to return the customer back to the merchant's shop after payment completion. If the parameter is not defined, the customer will be redirected to a shop URL registered with bePaid. A subscription ID will be added in the id parameter of the request query string, for example http://example.com/return?id=sbs_f4117438947a554e.
notification_url string A URL where to post a webhook notification about newly created, renewed or cancelled subscriptions.
additional_data object A section contains additional information to store with a subscription. Feel free to add your own data here.
receipt_text array Text that will be added to the customer mail and will be shown on the success result page. Submit it as an array of strings, for example ["First line", "Second line"].
avs_cvc_verification object AVS/CVC verification.
settings object Hosted payment page customization settings.
language string A payment widget language. English (en) is set by default. Possible values of language parameter.

Response

If credentials and parameters are valid, bePaid will return 201 HTTP status code and a new subscription object with all the relevant details. Then the customer must be redirected to redirect_url to enter his or her card details and to complete a payment to create the subscription.

Otherwise, bePaid will return 422 HTTP status code and an error message.

Example of the request to create a subscription 
curl https://api.bepaid.by/subscriptions \
  -X POST -u shop_id:secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
    "notification_url": "http://merchant.com/subscription_notification",
    "plan": {
        "currency": "USD",
        "plan": {
            "amount": 20,
            "interval": 20,
            "interval_unit": "day"
        },
        "shop_id": 10,
        "title": "Basic plan",
        "trial": {
            "amount": 10,
            "interval": 10,
            "interval_unit": "hour"
        }
    },
    "settings": {
        "language": "it"
    }
}
'
Example of the response to the request to create a subscription 
{
    "card": {},
    "created_at": "2015-05-11T12:48:14.067Z",
    "customer": {},
    "device_id": null,
    "id": "sbs_cdf887166553b5ae",
    "last_transaction": null,
    "plan": {
        "currency": "USD",
        "id": "pln_8f9c9dd63c9a5787",
        "plan": {
            "amount": 20,
            "interval": 20,
            "interval_unit": "day"
        },
        "title": "Title",
        "trial": {
            "amount": 10,
            "interval": 10,
            "interval_unit": "hour"
        }
    },
    "redirect_url": "https://checkout.bepaid.by/v2/checkout?token=3241e439f8c87d941d92321a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "renew_at": null,
    "active_to": null,
    "state": "redirecting",
    "token": "3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "tracking_id": null
}
Example of the request when a parameter is invalid or missing 
curl https://api.bepaid.by/subscriptions \
  -X POST -u shop_id:secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
    "notification_url": "http://merchant.com/subscription_notification",
    "plan": {
        "currency": "LVL",
        "plan": {
            "amount": 20,
            "interval": 20,
            "interval_unit": "day"
        },
        "shop_id": 10,
        "title": "Basic plan",
        "trial": {
            "amount": 10,
            "interval": 10,
            "interval_unit": "hour"
        }
    },
    "settings": {
        "language": "it"
    }
}
'
Example of the response to the request when a parameter is invalid or missing 
{
    "errors": {
        "base": [
            "Currency is invalid"
        ]
    },
    "message": "Currency is invalid"
}

Create a subscription with credit card data

Request

To create a subscription with credit card data, send a POST request to https://api.bepaid.by/subscriptions with the following parameters:

Parameter Type Description
customer * required
 object A customer resource. It includes either a customer ID or full customer details.
plan * required
 object A plan resource. It includes either a plan ID or full plan details.
tracking_id string(255) A ID of your transaction or order. Please, use unique values in order to get transaction information by query request otherwise, you will get the first transaction that we will find with tracking_id.
device_id string A device ID of customer subscribing on your service.
return_url string A URL where to return the customer back to the merchant's shop if a transaction card was authenticated with 3-D Secure.

If the parameter is not defined, the customer will be redirected to a shop URL registered with bePaid. A subscription ID will be added in the id parameter of the request query string, for example http://example.com/return?id=sbs_f4117438947a554e
notification_url string A URL where to post a webhook notification to.
card object A section of card details.
number * required
 string A card number. The length is from 12 to 19 digits.
verification_value * required
 string 3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand).
It can be sent along with token parameter, and in this case, bePaid will submit to acquiring bank card details with the given CVC2/CVV2/CID.
holder * required
 string(32) A cardholder name as it appears on the card.
exp_month * required
 integer A card expiration month is expressed with two digits (for example, 01).
exp_year * required
 integer A card expiration year is expressed with four digits (for example, 2026).
token * conditionally required
 string Instead of the above 5 parameters, you can send a card token you've stored previously either with a card tokenization request or from a successful response of payment, authorization or subscription creation requests.

Response

If credentials and parameters are valid, bePaid will return 201 HTTP status code and a new subscription object with all the relevant details, including redirect_url where you need to send the customer to, if 3-D Secure check is enabled.

Otherwise, bePaid will return 422 HTTP status code and an error message.

Example of the request to create a subscription 
{
  "card": {
    "exp_month": "01",
    "exp_year": "2026",
    "holder": "John Doe",
    "number": "4200000000000000",
    "verification_value": "123"
  },
  "customer": {
    "address": "1st Street",
    "city": "Denver",
    "country": "US",
    "email": "customer@example.com",
    "first_name": "John",
    "ip": "127.0.0.1",
    "last_name": "Doe",
    "phone": "+1-555-555-5555",
    "state": "CO",
    "zip": "92006"
  },
  "plan": {
    "currency": "USD",
    "plan": {
      "amount": 20,
      "interval": 20,
      "interval_unit": "day"
    },
    "title": "Basic plan",
    "trial": {
      "amount": 10,
      "interval": 10,
      "interval_unit": "hour"
    }
  },
  "tracking_id": "my_tracking_id"
}
Example of the response to the request to create a subscription 
{
  "id": "sbs_43cb5f79f8b56c17",
  "state": "successful",
  "tracking_id": "my_tracking_id",
  "device_id": null,
  "created_at": "2021-07-01T13:05:45.699Z",
  "renew_at": null,
  "active_to": null,
  "card": {
    "holder": "John Doe",
    "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
    "brand": "visa",
    "last_4": "0000",
    "first_1": "4",
    "bin": "420000",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "token": "1e2f9f69-a9d3-4d6d-a6c3-f029c3db70e6",
    "token_provider": null,
    "exp_month": 1,
    "exp_year": 2026
  },
  "customer": {
    "id": "cst_cebacd2a35f2041e"
  },
  "paid_billing_cycles": 0,
  "number_failed_payment_attempts": 0,
  "additional_data": {},
  "plan": {
    "id": "pln_7fd782ffa0fbc926",
    "title": "Basic plan",
    "currency": "USD",
    "language": null,
    "infinite": true,
    "billing_cycles": null,
    "trial": {
      "amount": 10,
      "interval": 10,
      "interval_unit": "hour"
    },
    "plan": {
      "amount": 20,
      "interval": 20,
      "interval_unit": "day"
    },
    "number_payment_attempts": 1,
    "test": null
  },
  "last_transaction": {
    "uid": "11749-e427d3dc44",
    "status": "successful",
    "message": "Successfully processed",
    "created_at": "2021-07-01T13:05:46.447Z"
  }
}
Example of the request with return_url and 3-D Secure enrolled card 
{
  "card": {
    "exp_month": "01",
    "exp_year": "2026",
    "holder": "John Doe",
    "number": "4012001037141112",
    "verification_value": "123"
  },
  "customer": {
    "address": "1st Street",
    "city": "Denver",
    "country": "US",
    "email": "customer@example.com",
    "first_name": "Jane",
    "ip": "127.1.2.3",
    "last_name": "Doe",
    "phone": "+1-555-555-555",
    "state": "CO",
    "zip": "92006"
  },
  "plan": {
    "currency": "USD",
    "plan": {
      "amount": "90",
      "interval": 3,
      "interval_unit": "day"
    },
    "title": "Basic plan",
    "trial": {
      "amount": "10",
      "interval": 24,
      "interval_unit": "hour"
    }
  },
  "return_url": "http://example.com/result-page"
}
Example of the response to the request with return_url and 3-D Secure enrolled card 
{
  "card": {
    "token": "159335feed5ee3facbc0d882f19d199fc5c60019f668e40fe15d6fedbd390295",
    "holder": "John Doe",
    "stamp": "lkdfsklba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
    "brand": "visa",
    "last_4": "0000",
    "first_1": "4",
    "bin": "420000",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "token_provider": null,
    "exp_month": 1,
    "exp_year": 2026
  },
  "created_at": "2015-03-18T10:06:01.406Z",
  "customer": {
    "id": "cst_5d6a3dbbfdfd29d5"
  },
  "device_id": null,
  "id": "sbs_9d0912f6b8ab65bc",
  "last_transaction": {
    "created_at": "2015-03-18T10:06:01.000Z",
    "message": null,
    "redirect_url": "https://gateway.bepaid.by/process/94-bb19e2c4bc",
    "status": "incomplete",
    "uid": "94-bb19e2c4bc"
  },
  "plan": {
    "currency": "USD",
    "id": "pln_e6851bf1a933bb3b",
    "plan": {
      "amount": 90,
      "interval": 3,
      "interval_unit": "day"
    },
    "title": "Mens Health",
    "trial": {
      "amount": 10,
      "interval": 24,
      "interval_unit": "hour"
    }
  },
  "renew_at": null,
  "active_to": null,
  "state": "redirecting",
  "tracking_id": null
}
Example of the request to create a subscription when a plan, a customer and a card were previously created 
{
  "card": {
    "token": "7982c829f83060eba2b27b0a7140c751ad02f28702a6475e901767614fe4c0e7"
    },
  "customer": {
    "id": "cst_c8dcec3e5ce21500"
  },
  "plan": {
    "id": "pln_cc22f0cda95f210f"
  },
  "tracking_id": "my_tracking_id"
}
Example of the request when a parameter is invalid or missing 
{
  "card": {
    "token": "7982c829f83060eba2b27b0a7140c751ad02f28702a6475e9"
      },
  "plan": {
    "id": "1"
  }
}
Example of the response to the request when a parameter is invalid or missing 
{
    "errors": {
        "plan": {
            "base": [
                "plan with this ID doesn't exist for this account"
            ]
        }
    },
    "message": "plan with this ID doesn't exist for this account"
}

Get subscription details

Request

To get the details of a subscription, send a GET request to https://api.bepaid.by/subscriptions/{subscription_id}, where {subscription_id} stands for the identifier of the subscription.

Response

If the subscription ID exists, bePaid will return 200 HTTP status code and the subscription details.

Example of the request to get details of the subscription with the ID sbs_43cb5f79f8b56c17 
curl -u shop_id:secret \
  https://api.bepaid.by/subscriptions/sbs_43cb5f79f8b56c17
Example of the response to the request to get details of the subscription 
{
  "id": "sbs_43cb5f79f8b56c17",
  "state": "successful",
  "tracking_id": "my_tracking_id",
  "device_id": null,
  "created_at": "2021-07-01T13:05:45.699Z",
  "renew_at": null,
  "active_to": null,
  "card": {
    "holder": "John Doe",
    "stamp": "pr334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
    "brand": "visa",
    "last_4": "0000",
    "first_1": "4",
    "bin": "420000",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "token": "1e2f9f69-a9d3-4d6d-a6c3-f029c3db70e6",
    "token_provider": null,
    "exp_month": 1,
    "exp_year": 2026
  },
  "customer": {
    "id": "cst_cebacd2a35f2041e"
  },
  "paid_billing_cycles": 0,
  "number_failed_payment_attempts": 0,
  "additional_data": {},
  "plan": {
    "id": "pln_7fd782ffa0fbc926",
    "title": "Basic plan",
    "currency": "USD",
    "language": null,
    "infinite": true,
    "billing_cycles": null,
    "trial": {
      "amount": 10,
      "interval": 10,
      "interval_unit": "hour"
    },
    "plan": {
      "amount": 20,
      "interval": 20,
      "interval_unit": "day"
    },
    "number_payment_attempts": 1,
    "test": null
  },
  "last_transaction": {
    "uid": "11749-e427d3dc44",
    "status": "successful",
    "message": "Successfully processed",
    "created_at": "2021-07-01T13:05:46.447Z"
  }
}

Cancel a subscription

Request

To cancel a subscription and to stop all further customer charges, send a POST request to https://api.bepaid.by/subscriptions/{subscription_id}/cancel, where {subscription_id} stands for the identifier of the subscription. The request should specify:

Parameter Type Description
cancel_reason * required
 string A reason why the subscription has been cancelled, for example Customer's request.

Response

If the request is processed well, bePaid will return 200 HTTP status code and a renewed array of customers.

Example of the request to cancel the subscription with the ID sbs_b1b7139d9b664293 
curl https://api.bepaid.by/subscriptions/sbs_b1b7139d9b664293/cancel \
  -u shop_id:secret \
  -X POST secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
    "cancel_reason": "Customer's request"
}
'
Example of the response to the request to cancel the subscription 
{
  "card": {
    "token": "064a120788b5847f866ff3def0c97ae12a6ff069407317fef172dcbafa3187e6",
    "holder": "John Doe",
    "stamp": "qr34ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
    "brand": "visa",
    "last_4": "0000",
    "first_1": "4",
    "bin": "420000",
    "issuer_country": null,
    "issuer_name": null,
    "product": null,
    "token_provider": null,
    "exp_month": 1,
    "exp_year": 2026
  },
  "created_at": "2015-01-27T15:59:55.609Z",
  "customer": {
    "id": "cst_e64cc8479090991e"
  },
  "id": "sbs_b1b7139d9b664293",
  "plan": {
    "currency": "USD",
    "id": "pln_068ed4bb9ce03298",
    "plan": {
      "amount": 20,
      "interval": 7,
      "interval_unit": "day"
    },
    "title": "Basic plan",
    "trial": {
      "amount": 10,
      "interval": 40,
      "interval_unit": "hour"
    }
  },
  "cancel_reason": "Customer's request",
  "cancelled_at": "2015-02-28T14:19:55.009Z",
  "renew_at": null,
  "active_to": "2015-03-28T01:54:32.684Z",
  "state": "canceled",
  "tracking_id": "my_tracking_id",
  "transaction": null
}

Automatic cancellation of subscription

In certain cases, the subscription will be automatically canceled with a failed or an error status:

  1. If the first ever charge returns a failed status, the subscription also gets a failed status.
  2. If a subsequent charge (meaning there were previously successful charges within this subscription) returns a failed status, the system will make new charge attempts until the number of attempts specified under number_payment_attempts runs out. If these attempts also fail, the subscription gets a failed status.
  3. If the first ever charge results in an error (for example, invalid card number or the currency is not supported), the subscription gets a failed status.
  4. If a subsequent charge (meaning there were previously successful charges within this subscription) results in an error, the system will make new charge attempts until the number of attempts specified under number_payment_attempts runs out. If these attempts also result in an error, the subscription gets an error status.