1.3. eMerchant Subscription API

The SysPay Merchant Subscription API allows you to define plans and subscribe users to it. Once subscribed, the subscription lifecycle will be handled by SysPay according to the merchant’s plan definition.

1.3.1. Definitions

• A plan is the pricing definition for a merchant product made of recurring or split payments.
• A subscription is a plan that a customer has subscribed to

A plan is defined by the following criteria:

• A type, which is either ‘SUBSCRIPTION’ or ‘INSTALMENT’.

SUBSCRIPTION-related parameters

• An optional trial phase with its specific price, that can be repeated multiple times.
• A recurring billing phase, that can be repeated a specific number of times, or until cancellation.
• An optional initial amount, should it differ from the standard billing amount.
• A retry map, that defines how to deal with failed billing attempts. If a payment fails, retries will be made according to this map.

INSTALMENT-related parameters

• A total amount
• A number of billing periods
• An optional initial amount, should it differ from the standard billing amount.
• A retry map, that defines how to deal with failed billing attempts. If a payment fails, retries will be made according to this map.

We will automatically split the total amount based on the initial amount and the number of periods. If the total amount given is 100 EUR, the initial amount is 10 EUR and the billing periods are 4, the payments will be 10 EUR followed by 3 payments of 90 EUR.

The plan can be either defined on-the-fly when subscribing a customer or by creating a reusable plan. Except for case-by-case plans, we recommend you to use pre-defined plans. This will make it easier for you to manage (e.g. cancel all subscriptions linked to a specific plan) or to report on (e.g. retrieve all users in trial mode for a specific plan)

A subscription is defined by the following criteria:

• A user
• The plan that this subscription is linked to
• A rebillable payment method used to pay this subscription.

1.3.2. Subscription lifecycle

A subscription follows a simple lifecycle that goes through the following phases:

• NEW: The subscription has been created but the customer has not made his first payment yet
• TRIAL: The subscription is in one of his trial periods (optional)
• BILLING: The subsription is in the standard billing cycle
• RETRY: The last payment attempt failed and the next billing cycle has not started yet. SysPay is currently trying to re-process the last payment.
• LAST: This is the last billing cycle and the subscription will be ended when it is complete
• CLOSED: The subscription has been ended or cancelled.

Subscription related events (EMS)

A subscription will receive events whenever:

• A subscription is created (see Subscription event)
• A subscription status or phase has changed (see Subscription event)
• A payment is taken (see Payment event)

Notes:

• For SUBSCRIPTION plans, the subscription will be ended one billing period after the last payment is taken (because you want to know when to stop the access to some service, for example)
• For INSTALMENT plans, the subscription will be ended as soon as the last payment is taken (because you want to know when the whole total amount has been cashed)

1.3.3. Create a plan

This method allows you to define a plan that you will be able to subscribe users to.

URL syntax:/api/{version}/merchant/plan Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
name	string	w{1,100}	Y	Your name for this plan (e.g your own product reference)
type	string	SUBSCRIPTION|INSTALMENT	Y	The plan type
description	string	[ws]{1,300}	N	A description for this plan
currency	string	[A-Z]{3}	Y	The currency of the trial/initial/billing amounts (ISO-4217)
trial_amount	int		N	The trial amount in cents. When given, trial_period, trial_period_unit and trial_cycles must be provided. If the given amount is ‘0’, the trial period will be applied but no payment will be taken (SUBSCRIPTION only)
trial_period	int		N	The number of trial_period_unit a trial cycle lasts (SUBSCRIPTION only)
trial_period_unit	string	enum	N	One of minute, hour, day, week, month, year (SUBSCRIPTION only)
trial_cycles	int		N	The number of times to repeat the trial phase (typically, 1) (SUBSCRIPTION only)
billing_amount	int		Y	The recurring billing amount in cents (SUBSCRIPTION only)
billing_period	int		Y	The number of billing_period_unit a billing cycle lasts
billing_period_unit	string	enum	Y	One of day, week, month, year
billing_cycles	int		Y	The number of recurring payments to take. 0 will be until cancellation. For INSTALMENTs, the number of cycles cannot be 0
initial_amount	int		N	The amount of the first payment of the recurring cycles if it is different than the given billing_amount
total_amount	int		Y	The total amount in cents to split into multiple payments (INSTALMENT only)
retry_map_id	int		N	The custom retry map to use (you need to contact us to setup custom retry maps)
default_capture_delay	int		N	The default delay in seconds for a payment to be captured, as part of the plan. This may be overridden at subscription level

Example requests

Subscription

The following request will create a subscription plan with:

• A 12 hour trial of 1 EUR
• Followed by a payment of 15 EUR every month
• An initial payment of 50 EUR

{
    "name": "Some Product",
    "type": "SUBSCRIPTION",
    "description": "1 EUR trial, 15 EUR monthly with an extra 35 EUR of setup fees",
    "currency": "EUR",
    "trial_amount": 100,
    "trial_period": 12,
    "trial_period_unit": "hour",
    "trial_cycles": 1,
    "billing_amount": 1500,
    "billing_period": 1,
    "billing_period_unit": "month",
    "initial_amount": 5000,
    "default_capture_delay": 100
}

Instalment plan

The following request will create an instalment plan for a total of 100 EUR with:

• 3 split payments
• 40 EUR taken immediately
• 2*30 EUR taken the following months

{
    "name": "Some Product",
    "type": "INSTALMENT",
    "description": "100 EUR worth of unicorn ground meat, paid in 3 times (40 EUR then 2*30 EUR)",
    "currency": "EUR",
    "total_amount": 10000,
    "billing_period": 1,
    "billing_period_unit": "month",
    "billing_cycles": 3,
    "initial_amount": 4000,
    "default_capture_delay": 100
}

Response parameters

The returned parameters are the same ones given for the request, with the 3 extra properties:

Name	Type	Mandatory	Description
plan.id	int	Y	The SysPay id for your plan
plan.created	int	Y	A unix timestamp giving the plan creation date
plan.status	string	Y	The plan status (ACTIVE / DISABLED / DELETED)

Example response

{
    "data": {
        "plan": {
            "id": 42,
            "created": 1386575309,
            "status": "ACTIVE",
            "name": "Some Product",
            "description": "1 EUR trial, 15 EUR monthly with an extra 35 EUR of setup fees",
            "currency": "EUR",
            "trial_amount": 100,
            "trial_period": 12,
            "trial_period_unit": "hour",
            "trial_cycles": 1,
            "billing_amount": 1500,
            "billing_period": 1,
            "billing_period_unit": "month",
            "initial_amount": 5000
        }
    }
}

1.3.4. Update a plan

This method allows you to update some properties of an existing subscription plan. This will affect all subscriptions linked to this plan. Updating instalment plans is currently not supported.

URL syntax:/api/{version}/merchant/plan/{id} Method:PUT

Input parameters

Name	Type	Details	Mandatory	Description
trial_amount	int		N	The trial amount in cents. If the given amount is ‘0’, the trial period will be applied but no payment will be taken
billing_amount	int		N	The recurring billing amount in cents
initial_amount	int		N	The amount of the first payment of the recurring cycles if it is different than the given billing_amount
default_capture_delay	int		N	The default delay in seconds for a payment to be captured, as part of the plan. This may be overridden at subscription level

Example requests

Plan update

The following request will update a subscription plan:

{
    "trial_amount": 100,
    "billing_amount": 1500,
    "initial_amount": 5000,
    "default_capture_delay": 500
}

Response parameters

The returned parameters are the same ones as the create plan request.

Example response

{
    "data": {
        "plan": {
            "id": 42,
            "created": 1386575309,
            "status": "ACTIVE",
            "name": "Some Product",
            "description": "1 EUR trial, 15 EUR monthly with an extra 35 EUR of setup fees",
            "currency": "EUR",
            "trial_amount": 100,
            "trial_period": 12,
            "trial_period_unit": "hour",
            "trial_cycles": 1,
            "billing_amount": 1500,
            "billing_period": 1,
            "billing_period_unit": "month",
            "initial_amount": 5000
        }
    }
}

1.3.5. Subscribe a customer to a plan (hosted flow)

You can either subscribe a customer to an existing plan (recommended) or create a new plan on-the-fly (which can also be re-used later if needed).

The flow is very similar to the hosted payment page one. A call to this service, if successfull, will give you back a URL to redirect the customer to. He will then be able to choose amongst the available payment methods and return to your site afterwards.

URL syntax:/api/{version}/merchant/subcription Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
flow	string	HOSTED	Y	The flow to use (hosted or server-2-server)
subscription.redirect_url	string		N	This URL can overwrite the default Redirect URL
subscription.ems_url	string		N	This URL can overwrite the default EMS URL
subscription.plan_id	int		N	The plan id to subscribe the user to. If not given, you must provide the plan specifications in the plan property
subscription.plan	object		N	The plan specification, mandatory if the plan_id is not given. This object has the same properties as the one used for the plan creation
subscription.reference	string	UNIQUE, [ -~]+ (ascii printable characters)	N	Your own reference for this subscription
subscription.extra	string	max length 300	N	Extra parameters to be sent back to you on redirect/EMS calls
subscription.website_id	int		N	The Syspay website reference which the customer makes the payment for (The list of available websites can be checked from the merchant backend)
subscription.capture_delay	int		N	The delay in seconds for the payment to be captured, where 0 implies a Rebill and a larger value represents a Pre-Auth Rebill
customer.email	string	valid email address	Y	Customer email address
customer.language	string	[a-z]{2}	N	Customer language (ISO-639-1) (defaults to en)

Example request (existing plan)

{
    "flow": "HOSTED",
    "subscription": {
        "plan_id": 42,
        "reference": "52a7026d09420",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
        "redirect_url": "https://mydomain.tld/some/custom/redirect",
        "ems_url": "https://mydomain.tld/some/custom/callback",
        "capture_delay": 71
    },
    "customer": {
        "email": "test@domain.com",
        "language": "en"
    }
}

Example request (new plan)

{
    "flow": "HOSTED",
    "redirect_url": "https://mydomain.tld/some/custom/redirect",
    "ems_url": "https://mydomain.tld/some/custom/callback",
    "subscription": {
        "plan": {
            "name": "Some Custom Plan",
            "type": "SUBSCRIPTION",
            "currency": "EUR",
            "trial_amount": 100,
            "trial_period": 12,
            "trial_period_unit": "hour",
            "trial_cycles": 1,
            "billing_amount": 1500,
            "billing_period": 1,
            "billing_period_unit": "month",
            "initial_amount": 5000
        },
        "reference": "52a7026d09420",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
    },
    "customer": {
        "email": "test@domain.com",
        "language": "en"
    }
}

Response parameters

Name	Type	Always There	Description
redirect	string	Y	The URL you should redirect the customer to in order to start the subscription.
subscription	object	Y	A subscription object, containing the newly created subscription in a PENDING status
subscription.id	int	Y	The SysPay subscription id
subscription.plan_id	int	Y	The plan this subscription is linked to. (This could be an unknown id to you if the plan was created on the fly)
subscription.plan_type	string	Y	The subscription’s plan type (SUBSCRIPTION / INSTALMENT)
subscription.created	unix timestamp	Y	The subscription’s creation date
subscription.ems_url	string	N	The URL that is used to notify about events related to this subscription.
subscription.capture_delay	int	Y	The delay in seconds for the payment to be captured, where 0 implies a Rebill and a larger value represents a Pre-Auth Rebill
subscription.reference	string	N	Your own reference for this subscription
subscription.status	string	Y	The subscription status (PENDING) (see Subscription statuses)
subscription.phase	string	Y	The phase the subscription is in (NEW) (see Subscription phases)
subscription.customer	object	Y	The customer information
subscription.customer.id	int	Y	The Syspay reference for this customer
subscription.customer.firstname	string	N	The customer’s first name
subscription.customer.lastname	string	N	The customer’s last name
subscription.customer.email	string	N	The customer’s email address
subscription.extra	string	N	The extra parameter received upon request
subscription.start_date	unix timestamp	N	The subscription start date, if it has already been started
subscription.end_date	unix timestamp	N	The subscription end date, if the subscription is over
subscription.end_reason	int	N	The end reason for the subscription, if it is over (it could be cancelled by the merchant, stopped because of fraud or expiration of the payment method, etc...) (see Subscription end reasons)
subscription.next_event	object	N	Information about the next scheduled event for this subscription
subscription.next_event.event_type	string	Y	The next event type (subscription events)
subscription.next_event.scheduled_date	unix timestamp	Y	The event’s scheduled date/time

Example response

{
    "data": {
        "redirect": "https://app.syspay.com/subscription-init-page",
        "subscription": {
            "id": 4242,
            "plan_id": 42,
            "plan_type": "SUBSCRIPTION",
            "created": 1403105197,
            "ems_url": "https://mydomain.tld/some/custom/callback",
            "capture_delay": 0,
            "reference": "52a7026d09420",
            "status": "PENDING",
            "phase": "NEW",
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "customer": {
                "email": "test@domain.com",
                "language": "fr"
            },
            "next_event": {
                "event_type": "INITIAL",
                "scheduled_date": 1403105797
            }
        }
    }
}

1.3.6. Subscribe a customer to a plan (server-2-server flow)

Instead of redirecting the customer to our payment page, you could collect the payment method information (e.g. the credit card details) on your own page and forward them directly to us.

Input parameters

The changes to the hosted flow are:

• The flow parameter (API)
• A method parameter must be provided to specify the payment method used. Currently only creditcard (CREDITCARD) based subscriptions are supported. See below.
• The payment method details must be passed. This differs depending on the payment method used. See below.
• The customer object must be passed an ip parameter.
• Depending on the payment method, the subscription will be immediately active, or you could have to redirect the customer to a given URL in order to complete the payment (for example if the initial payment requires a 3DS verification)

Method-specific parameters

Method: CREDITCARD

Name	Type	Details	Mandatory	Description
creditcard.cardholder	string	max length 100	Y	Cardholder name
creditcard.number	string	[0-9]{12,19}	Y	Valid credit card number, only digits
creditcard.cvc	int	[0-9]{3,4}	Y	Credit card verification code
creditcard.exp_month	string	[0-9]{2}	Y	Credit card expire month (ex: 05)
creditcard.exp_year	string	[0-9]{4}	Y	Credit card expire year (ex: 2015)

Example request (existing plan)

{
    "flow": "API",
    "method": "CREDITCARD",
    "subscription": {
        "ems_url": "https://mydomain.tld/some/custom/callback",
        "plan_id": 42,
        "reference": "52a7026d09420",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
    },
    "customer": {
        "email": "test@domain.com",
        "language": "en",
        "ip": "1.2.3.4"
    },
    "creditcard": {
        "cardholder": "John Doe",
        "number": "4556253971599407",
        "cvc": 123,
        "exp_month": "05",
        "exp_year": "2015"
    }
}

Example response (immediate activation)

{
    "data": {
        "subscription": {
            "id": 4242,
            "plan_id": 42,
            "plan_type": "SUBSCRIPTION",
            "ems_url": "https://mydomain.tld/some/custom/callback",
            "reference": "52a7026d09420",
            "status": "ACTIVE",
            "phase": "TRIAL",
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "start_date": 1386631016,
            "customer": {
                "email": "test@domain.com",
                "language": "en"
            },
            "next_event": {
                "event_type": "INITIAL",
                "scheduled_date": 1403105797
            }
        }
    }
}

1.3.7. Subscribe a customer to a plan by re-using an existing subscription or billing agreement

You can subscribe customers that already have an ACTIVE or ENDED subscription or an ACTIVE billing agreement by re-using the payment method linked to them.

Input parameters

The changes to the hosted flow are:

• The flow must be API
• To re-use the payment method of an existing subscription, pass a use_subscription parameter with the subscription id to copy the payment method from.
• To re-use the payment method of an existing billing agreement, pass a use_billing_agreement parameter with the billing agreement id to copy the payment method from.
• The customer object can be passed.

Example request (existing plan)

{
    "flow": "API",
    "subscription": {
        "plan_id": 42,
        "reference": "52a7026d09420",
        "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
        "redirect_url": "https://mydomain.tld/some/custom/redirect",
        "ems_url": "https://mydomain.tld/some/custom/callback"
    },
    "customer": {
        "email": "test@domain.com",
        "language": "en"
    },
    "use_subscription": 845
}

1.3.8. Issue a manual rebill on a subscription

While a subscription is in ACTIVE or ENDED status, you can issue manual rebills or random amount (but same currency) on it. A payment object will be given back.

URL syntax:/api/{version}/merchant/subscription/{id}/rebill Method:POST

Input parameters

Name	Type	Details	Mandatory	Description
reference	string	UNIQUE, [ -~]+ (ascii printable characters)	N	Merchant payment identifier. If not provided the one used for the subscription will be used
amount	int		Y	The amount we need to bill in cents (500 XXX = 5.00 XXX)
currency	string	[A-Z]{3}	Y	The currency (ISO-4217)
description	string	max length 300	N	The product description that the customer is paying for. If not provided the one used for the plan of the subscription will be used
extra	string	max length 300	N	Extra parameter that is passed back to the merchant when sending notifications. If not provided the one used for the subscription will be used
ems_url	string		N	The notification URL for that payment. If not provided the EMS url will be the same one as the subscription’s

Example request

{
    "amount": 5000,
    "currency": "EUR",
    "reference": "83987232",
    "description": "extra credits",
    "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK"
}

1.3.9. Cancelling a subscription

You can cancel any ACTIVE subscription.

URL syntax:/api/{version}/merchant/subscription/{id}/cancel Method:POST

Input parameters

• An optional boolean now parameter can be passed to cancel the subscription immediately. It defaults to false and has the following consequences:
  • The subscription will immediately be in CLOSED status.
  • Billing retries (if the last normal billing attempt failed) will be cancelled

If this parameter is not needed, an empty body can be sent.

Example request

{
    "now": true
}

Response parameters

The response will contain the updated subscription data, including an extra end_date and end_reason parameters.

Example response

{
    "data": {
        "subscription": {
            "id": 4242,
            "plan_id": 42,
            "plan_type": "SUBSCRIPTION",
            "ems_url": "https://mydomain.tld/some/custom/callback",
            "reference": "52a7026d09420",
            "status": "ENDED",
            "phase": "CLOSED",
            "extra": "Q3VyaW9zaXR5IGlzIHRoZSBsdXN0IG9mIHRoZSBtaW5kLiAtIFRob21hcyBIb2JiZXMK",
            "start_date": 1386631016,
            "end_date": 1386641016,
            "end_reason": "UNSUBSCRIBED_MERCHANT",
            "customer": {
                "email": "test@domain.com",
                "language": "fr"
            },
            "next_event": null
        }
    }
}