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 Demo PSP back office or be subscribed in a shop notification settings on e-mails about processed transactions. Additionally, Demo PSP 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. Demo PSP was unable to collect the subscription overdue balance.
`error`	An error occurred when Demo PSP 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.begateway.com/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 Demo PSP. 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, Demo PSP 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, Demo PSP will return 422 HTTP status code and an error message.

Example of the request to create a subscription

curl https://api.begateway.com/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.begateway.com/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.begateway.com/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.begateway.com/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 Demo PSP. 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, Demo PSP 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, Demo PSP 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, Demo PSP 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": "420000000000000000",
    "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://demo-gateway.begateway.com/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.begateway.com/subscriptions/{subscription_id}, where {subscription_id} stands for the identifier of the subscription.

Response

If the subscription ID exists, Demo PSP 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.begateway.com/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.begateway.com/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, Demo PSP 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.begateway.com/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:

If the first ever charge returns a failed status, the subscription also gets a failed status.
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.
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.
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.