Subscription plans

A subscription plan instructs YurtaPay how often and how much to charge a customer. Merchants are free to create an unlimited number of subscription plans for their shops.

Each plan has a unique ID which should be submitted in requests.

Create a plan

Request

To create a subscription plan, send a POST request to https://api.yurtapay.kz/plans with the following parameters:

test

boolean
true or false. The plan will be a test one if set to true.

title

required

string
Subscription title.

currency

required

string
Currency in ISO-4217 format, for example, USD.

object
Plan parameters.

amount required	integer Amount of plan in minimal units.
interval required	integer Interval of plan.
interval_unit required	string Interval unit of plan (`hour`, `day` or `month`).

object

amount	integer Trial period amount in minimal units. Works only together with `trial.interval`.
interval	integer Interval of trial period (integer). Works only together with `trial.amount`.
interval_unit	string Interval unit of trial period (`hour`, `day` or `month`). Works only with `trial.interval_unit`.
as_first_payment	boolean `true` or `false`. If `true`, the system considers the payment for the trial period as the first payment, which allows using all the rules for debiting funds, including recovery after payment errors after the trial period. This increases the risk of using stolen and single-use cards to pay for the trial period. If `false`, then in case of an error in the payment made after the end of the trial period, new attempts to debit funds will not be provided. Default: `false`.

array
Array of customer fields. The fields specified in the array are displayed on the payment page and are required to be filled in.

first_name	string Customer's first name.
last_name	string Customer's last name.
email	string Customer's email.
phone	string Customer's phone number.
birth_date	string Customer's date of birth in the ISO 8601 format `YYYY-MM-DD`.
country	string Customer's country in ISO 3166-1 Alpha-2 format.
state	string Customer's state or region. See details here.
city	string Customer's city.
address	string Customer's address.
zip	string Customer's postal code.

language

string
The payment page language, when paying for the plan. English (en) is set by default. Possible values of language parameter.

infinite

boolean
true or false. Set to true if billing cycles are infinite. Default: true

billing_cycles

integer
Billing cycles number. It is ignored if the infinite parameter is set to true.

number_payment_attempts

integer
Number of failed payment attempts before cancelling a subscription. Default: 3.

If the charge attempt fails, but there were previously successful charges within this subscription, the system will keep making payment attempts the following day:

- at 3 AM if "prevent_payments_at_night":false,
- at 8 AM if "prevent_payments_at_night":true

The attempts will be made until the payment is succesful or until the specified number of attempts runs out.

If the charge results in an error, but there were previously successful charges from this card within this plan, the next attempt will be made at the beginning of each following hour (with the exception of 8:00 PM —8:00 AM period if "prevent_payments_at_night": true) until the specified number of attempts runs out.

prevent_payments_at_night

boolean
true or false. If true, subscription payments are processed only during the period from 8:00 AM to 8:00 PM in the time zone set for the system. false is set by default.

Example of the requests for creating a plan with infinite billing cycles

curl https://api.yurtapay.kz/plans \
  -X POST -u shop_id:secret_key \
  -H "Content-Type: application/json" \
  -d \
'
{
  "test": true,
  "title": "Basic plan",
  "currency": "USD",
  "plan": {
    "amount": 20,
    "interval": 20,
    "interval_unit": "day"
  },
  "trial": {
    "amount": 10,
    "interval": 10,
    "interval_unit": "hour"
  },
  "visible_fields": ["first_name", "last_name"],
  "language": "en",
  "infinite": true,
  "billing_cycles": null,
  "number_payment_attempts": 3,
}
'

Example of the requests for creating a plan with finite billing cycles

  {
    "test": true,
    "title": "Basic plan",
    "currency": "USD",
    "plan": {
      "amount": 20,
      "interval": 20,
      "interval_unit": "day"
    },
    "trial": {
      "amount": 10,
      "interval": 10,
      "interval_unit": "hour"
    },
    "language": "en",
    "infinite": false,
    "billing_cycles": 12,
    "number_payment_attempts": 3
  }

Response

If credentials and parameters are valid, YurtaPay will return 201 HTTP status code and a new plan object with all the relevant details. Otherwise, YurtaPay will return 422 HTTP status code and an error message.

Response example

{
    "id": "pln_a134847c902551de",
    "title": "Basic plan",
    "currency": "USD",
    "language": "en",
    "plan": {
        "amount": 20,
        "interval": 20,
        "interval_unit": "day"
    },
    "trial": {
        "amount": 10,
        "interval": 10,
        "interval_unit": "hour"
    },
    "number_payment_attempts": 3,
    "test": true
}

Example of the response to the request when a parameter is invalid or not included

{
    "errors": {
        "title": [
            "can't be blank"
        ]
    },
    "message": "Title can't be blank"
}

Get a payment link for a plan

To get a payment for a plan, route the customer's browser via a GET or POST request to https://api.yurtapay.kz/plans/{plan_id}/pay, where {plan_id} stands for the identifier of the plan.

Get subscription plan details

To get details of a subscription plan, send a GET request to https://api.yurtapay.kz/plans/{plan_id}, where {plan_id} stands for the identifier of the plan.

If the plan ID exists, YurtaPay will return 200 HTTP status code and the plan details.

Example of the request to get details of the plan with the ID pln_a134847c902551de

curl -u shop_id:secret \
  https://api.yurtapay.kz/plans/pln_a134847c902551de

Response example

{
    "id": "pln_a134847c902551de",
    "title": "Basic plan",
    "currency": "USD",
    "language": "en",
    "plan": {
        "amount": 20,
        "interval": 20,
        "interval_unit": "day"
    },
    "trial": {
        "amount": 10,
        "interval": 10,
        "interval_unit": "hour"
    },
    "number_payment_attempts": 3,
    "test": true
}

Get a list of plans

To get a list of all plans, send a GET request to https://api.yurtapay.kz/plans.

If there are plans, YurtaPay will return 200 HTTP status code and an array of plans.

Example of the request with a list of plans

curl -u shop_id:secret \
  https://api.yurtapay.kz/plans

Response example

[
    {
        "id": "pln_2b0c211f50deb72c",
        "title": "Basic plan",
        "currency": "USD",
        "language": "en",
        "plan": {
            "amount": 20,
            "interval": 7,
            "interval_unit": "day"
        },
        "trial": {
            "amount": 10,
            "interval": 40,
            "interval_unit": "hour"
        },
        "number_payment_attempts": 3,
        "test": true
    },
    {
        "id": "pln_75eca73bfdcf143a",
        "title": "Pro plan",
        "currency": "USD",
        "language": "fr",
        "plan": {
            "amount": 30,
            "interval": 7,
            "interval_unit": "day"
        },
        "trial": {
            "amount": 10,
            "interval": 40,
            "interval_unit": "hour"
        },
        "number_payment_attempts": 5,
        "test": true
    }
]