1.4. eTerminal API¶

1.4.1. Requesting an eTerminal instance¶

This method allows you to create one instance of the e-terminal. This instances can be prefilled with data related to the operation type, customer information,etc... Additionally, the e-terminal instance can be “locked” which leaves the form in a read-and-confirm only state.

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

Input parameters¶

Name	Type	Details	Mandatory	Description
website	int		N	The website shop id that the payment is for (The list of available websites can be checked from the merchant backend)
locked	boolean	true\|false	N	Set to false allows the user to modify the customer/transaction data. Default to false
type	string	ONESHOT\|SUBSCRIPTION\|PAYMENT_PLAN\|PAYMENT_MANDATE	N*	Set the operation type on the ticket. * MANDATORY if you have selected locked = true
ems_url	string		N	This URL can overwrite the default EMS URL
payment_page_redirect_url	string		N	This URL can overwrite the default Redirect URL
eterminal_redirect_url	string		N	The URL the user will be redirected once the payment is processed
customer	array		N	Customer data
description	string		N	A description for the payment
reference	string	UNIQUE, [ -~]+ (ascii printable characters)	N	The merchant reference for this operation
oneshot	array		N*	Data related to a oneshot payment. * MANDATORY if you selected type=’ONESHOT’
subscription	array		N*	Data related to a subscription. * MANDATORY if you selected type=’SUBSCRIPTION’
payment_plan	array		N*	Data related to a payment plan. * MANDATORY if you selected type=’PAYMENT_PLAN’
payment_mandate	array		N*	Data related to a payment mandate. * MANDATORY if you selected type=’PAYMENT_MANDATE’
locked_inputs	array		N	Partial form lock. Contains which inputs will be locked once the form is loaded (see next section for details)

Customer information¶

Name	Type	Details	Mandatory	Description
customer.first_name	string	alphabetic characters only - max length 100	N	Customer name
customer.last_name	string	alphabetic characters only - max length 100	N	Customer last name
customer.email	string	valid email address	N	Customer Email
customer.mobile_country	string	[A-Z]{2}	N*	Customer country phone prefix (ISO-3166-1). * MANDATORY if you send a customer.mobile_phone
customer.mobile_phone	string	[0-9_- ()]+	N	Customer mobile number (do not use any country codes, just the national number)
customer.company_name	string		N	Customer company name
customer.language	string	[a-z]{2}	N	Customers language (ISO-639-1)(used on request email/sms)
customer.address	string	max length 100	N	Customer address
customer.city	string	max length 100	N	Customer city
customer.postcode	string		N	Customer postal code
customer.country	string	[A-Z]{2}	N	Customer country (ISO-3166-1)

Type-specific parameters¶

Type: ONESHOT¶

Name	Type	Details	Mandatory	Description
oneshot.amount	Int		Y	Payment amount in cents.
oneshot.currency	string	[A-Z]{3}	Y	Transaction currency (ISO-4217).
oneshot.preauth	boolean	true\|false	N	Set the transaction as a pre-authorization.

Type: SUBSCRIPTION¶

Name	Type	Details	Mandatory	Description
subscription.trial_amount	Int		N	The amount for one trial cycle in cents
subscription.trial_cycles	int		N	Number of cycles to be in trial (in development)
subscription.trial_period	int		N	Period for one trial cycle
subscription.trial_period_unit	string	minute\|hour\|day\|week\|month	N*	Trial period unit. * Mandatory if you have selected type=’SUBSCRIPTION’ and trial period != null
subscription.billing_amount	Int		Y	The recurring billing amount in cents
subscription.billing_cycles	int		N	Billing cycles before the subscription expires. Set it to null to create a subscription without especific expiry date
subscription.billing_period	int		Y	The number of billing_period_unit a billing cycle lasts
subscription.billing_period_unit	string	day\|week\|month	Y	Billing period unit
subscription.initial_amount	Int		N	The amount of the first payment of the recurring cycles if it is different than the given billing_amount (in cents)
subscription.currency	string	[A-Z]{3}	Y	The currency of the trial/initial/billing amounts (ISO-4217)

Type: PAYMENT_PLAN¶

Name	Type	Details	Mandatory	Description
payment_plan.total_amount	Int		Y	The total amount in cents to split into multiple payments
payment_plan.currency	string	[A-Z]{3}	Y	Transaction currency (ISO-4217)
payment_plan.billing_cycles	int		Y	The number of recurring payments to take
payment_plan.billing_period	int		Y	The number of billing_period_unit a billing cycle lasts
payment_plan.billing_period_unit	string	day\|week\|month	Y	Billing period time unit

Type: PAYMENT_MANDATE¶

Name	Type	Details	Mandatory	Description
payment_mandate.currency	string	[A-Z]{3}	Y	Transaction currency (ISO-4217)
payment_mandate.initial_charge	int		N	Payment amount in cents(if there’s an initial charge).
payment_mandate.preauth	boolean	true\|false	N	Set the transaction as a pre-authorization.

Example request: One off payment¶

This example will initiate an eTerminal instance for a single 12.00 GBP payment:

{
    "locked": false,
    "type": "ONESHOT",
    "website": 110,
    "ems_url": "https://wwwinitial-charge/notify",
    "payment_page_redirect_url": "http://www.myshop.com/redirect",
    "eterminal_redirect_url": "http://backend.myshop.com/redirect",
    "description": "Ms Hudson Monthly Payment",
    "reference": "sh10001",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "oneshot":{
        "amount": 1200,
        "currency": "GBP"
    }
}

Example request: Subscription¶

This example will initiate an eTerminal instance for a subscription with:

a 1.00 GBP trial for 7 days
followed by an initial payment of 100.00 GBP for a period of 1 month
followed by recurring payments of 15.00 GBP every month

{
    "locked": true,
    "type": "SUBSCRIPTION",
    "website": 110,
    "ems_url": "https://www.myshop.com/notify",
    "payment_page_redirect_url": "http://www.myshop.com/redirect",
    "eterminal_redirect_url": "http://backend.myshop.com/redirect",
    "description": "Mysteries TV channel subscription",
    "reference": "sh10002",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "subscription": {
        "trial_amount": 100,
        "trial_period": 7,
        "trial_period_unit": "day",
        "billing_amount": 1500,
        "billing_period": 1,
        "billing_period_unit": "month",
        "initial_amount": 10000,
        "currency": "GBP"
    }
}

Example request: Payment Plan¶

This example will initiate an eTerminal instance for a 300.00 GBP payment plan, split in 12 monthly payments:

{
    "locked": false,
    "type": "PAYMENT_PLAN",
    "website": 110,
    "ems_url": "https://www.myshop.com/notify",
    "payment_page_redirect_url": "http://www.myshop.com/redirect",
    "eterminal_redirect_url": "http://backend.myshop.com/redirect",
    "description": "New car payment plan",
    "reference": "sh10003",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "payment_plan": {
        "total_amount": 30000,
        "billing_cycles": 12,
        "billing_period": 1,
        "billing_period_unit": "month",
        "currency": "GBP"
    }
}

Example request: Payment Mandate¶

This example will initiate an eTerminal instance with a payment mandate request with an initial charge of 12.00 GBP:

{
    "locked": true,
    "type": "PAYMENT_MANDATE",
    "website": 110,
    "ems_url": "http://www.myshop.com",
    "payment_page_redirect_url": "http://www.myshop.com",
    "eterminal_redirect_url": "http://www.myppredirecturl.com",
    "description": "Studio in Pink Hotel room",
    "reference": "sh10004",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "payment_mandate": {
        "currency": "GBP",
        "initial_charge": 1200
    }
}

Response parameters¶

Name	Type	Mandatory	Description
eterminal.url	string	Y	Url to access the E-terminal

Example response¶

{
    "data": {
        "eterminal": {
            "url": "https://www.syspay.com/eterminal/ckrwsv5jxzrgkn3nqx6k6sjqngqgfg3s"
        }
    }
}

1.4.2. Locking the form inputs¶

Sometimes you will need to provide a partially locked eterminal form. To achieve this goal, the API allow you to manually select which inputs will be locked once the form is loaded through the ‘locked_inputs’ json object.

This object contains mostly the same parameters as the eterminal json, but theyre all boolean format. Just define which inputs do you want to lock, and set them to true. Do not use together with the normal locked: true parameter, becasue this one will override any partial lock the user could perform.

Please notice that any locked input on transaction data will require their corresponding value to be defined on the transaction JSON, even if the element is not mandatory.

Input parameters¶

Name	Type	Mandatory	Description
type	boolean	N	Lock the transaction type dropdown
description	boolean	N	Lock the description input
reference	boolean	N	Lock the reference input
customer	array	N	Contains locked inputs related to customer area
oneshot	array	N	Contains locked inputs related to oneshot transaction area
subscription	array	N	Contains locked inputs related to subscription transaction area
payment_plan	array	N	Contains locked inputs related to payment plan transaction area
payment_mandate	array	N	Contains locked inputs related to payment mandate transaction area

Customer information¶

Name	Type	Mandatory	Description
customer.first_name	boolean	N	Lock the first name input
customer.last_name	boolean	N	Lock the last name input
customer.email	boolean	N	Lock the email input
customer.mobile_country	boolean	N	Lock the mobile prefix dropdown
customer.mobile_phone	boolean	N	Lock the phone number input
customer.company_name	boolean	N	Lock the company name input
customer.language	boolean	N	Lock the language dropdown
customer.address	boolean	N	Lock the address input
customer.city	boolean	N	Lock the city input
customer.postcode	boolean	N	Lock the postcode input
customer.country	boolean	N	Lock the country dropdown

Type-specific parameters¶

Type: ONESHOT¶

Name	Type	Mandatory	Description
oneshot.amount	boolean	N	Lock the amount input
oneshot.currency	boolean	N	Lock the currency dropdown
oneshot.pay_mode	boolean	N	Lock the payment mode (direct/preauth) dropdown

Type: SUBSCRIPTION¶

Name	Type	Mandatory	Description
subscription.trial_amount	boolean	N	Lock the trial amount input
subscription.trial_period	boolean	N	Lock the trial period input
subscription.trial_period_unit	boolean	N	Lock the trial period unit dropdown
subscription.billing_amount	boolean	N	Lock the billing amount input
subscription.billing_cycles	boolean	N	Lock the billing cycles input
subscription.billing_period	boolean	N	Lock the billing period input
subscription.billing_period_unit	boolean	N	Lock the billing period unit dropdown
subscription.initial_amount	boolean	N	Lock the initial amount input
subscription.currency	boolean	N	Lock the currency dropdown
subscription.trial_check	boolean	N	Lock the trial checkbox input
subscription.expires_check	boolean	N	Lock the expires checkbox input

Type: PAYMENT_PLAN¶

Name	Type	Mandatory	Description
payment_plan.total_amount	boolean	N	Lock the amount input
payment_plan.currency	boolean	N	Lock the currency dropdown
payment_plan.billing_cycles	boolean	N	Lock the billing cycles input
payment_plan.billing_period	boolean	N	Lock the billing period input
payment_plan.billing_period_unit	boolean	N	Lock the billing period unit dropdown

Type: PAYMENT_MANDATE¶

Name	Type	Mandatory	Description
payment_mandate.currency	boolean	N	Lock the currency dropdown
payment_mandate.initial_charge	boolean	N	Lock the initial_charge dropdown
payment_mandate.amount	boolean	N	Lock the amount input

Example request: One off payment¶

This example will initiate an eTerminal instance for a single 12.00 GBP payment:

{
    "type": "ONESHOT",
    "website": 110,
    "ems_url": "https://wwwinitial-charge/notify",
    "payment_page_redirect_url": "http://www.myshop.com/redirect",
    "eterminal_redirect_url": "http://backend.myshop.com/redirect",
    "description": "Ms Hudson Monthly Payment",
    "reference": "sh10001",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "oneshot":{
        "amount": 1200,
        "currency": "GBP"
    },
    "locked_inputs":{
        "customer":{
          "first_name": true,
          "last_name": true
        },
        "oneshot": {
          "amount": true
        }
    }
}

Example request: Subscription¶

This example will initiate an eTerminal instance for a subscription with:

a 1.00 GBP trial for 7 days
followed by an initial payment of 100.00 GBP for a period of 1 month
followed by recurring payments of 15.00 GBP every month

{
    "type": "SUBSCRIPTION",
    "website": 110,
    "ems_url": "https://www.myshop.com/notify",
    "payment_page_redirect_url": "http://www.myshop.com/redirect",
    "eterminal_redirect_url": "http://backend.myshop.com/redirect",
    "description": "Mysteries TV channel subscription",
    "reference": "sh10002",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "subscription": {
        "trial_amount": 100,
        "trial_period": 7,
        "trial_period_unit": "day",
        "billing_amount": 1500,
        "billing_period": 1,
        "billing_period_unit": "month",
        "initial_amount": 10000,
        "currency": "GBP"
    },
    "locked_inputs":{
        "reference": true,
        "customer":{
          "language": true,
          "email": true
        },
        "subscription": {
          "billing_amount": true,
          "billing_period": true,
          "billing_period_unit": true
        }
    }
}

Example request: Payment Plan¶

This example will initiate an eTerminal instance for a 300.00 GBP payment plan, split in 12 monthly payments:

{
    "type": "PAYMENT_PLAN",
    "website": 110,
    "ems_url": "https://www.myshop.com/notify",
    "payment_page_redirect_url": "http://www.myshop.com/redirect",
    "eterminal_redirect_url": "http://backend.myshop.com/redirect",
    "description": "New car payment plan",
    "reference": "sh10003",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "payment_plan": {
        "total_amount": 30000,
        "billing_cycles": 12,
        "billing_period": 1,
        "billing_period_unit": "month",
        "currency": "GBP"
    },
    "locked_inputs":{
        "payment_plan": {
          "total_amount": true,
          "currency": true,
          "billing_cycles": true
        }
    }
}

Example request: Payment Mandate¶

This example will initiate an eTerminal instance with a payment mandate request with an initial charge of 12.00 GBP:

{
    "type": "PAYMENT_MANDATE",
    "website": 110,
    "ems_url": "http://www.myshop.com",
    "payment_page_redirect_url": "http://www.myshop.com",
    "eterminal_redirect_url": "http://www.myppredirecturl.com",
    "description": "Studio in Pink Hotel room",
    "reference": "sh10004",
    "customer": {
        "first_name": "sherlock",
        "last_name": "holmes",
        "email": "foo@bar.com",
        "company_name": "Baker Street Detectives",
        "mobile_country": "GB",
        "mobile_phone": "2012341234",
        "language": "en",
        "address": "221 Baker Street",
        "city": "London",
        "postcode": "NW16XE",
        "country": "GB"
    },
    "payment_mandate": {
        "currency": "GBP",
        "initial_charge": 1200,
        "amount": 300
    },
    "locked_inputs":{
        "payment_mandate": {
          "initial_charge": true,
          "currency": true,
          "amount": true
        }
    }
}

Navigation

Table Of Contents

1.4. eTerminal API¶

1.4.1. Requesting an eTerminal instance¶

Input parameters¶

Customer information¶

Type-specific parameters¶

Type: ONESHOT¶

Type: SUBSCRIPTION¶

Type: PAYMENT_PLAN¶

Type: PAYMENT_MANDATE¶

Example request: One off payment¶

Example request: Subscription¶

Example request: Payment Plan¶

Example request: Payment Mandate¶

Response parameters¶

Example response¶

1.4.2. Locking the form inputs¶

Input parameters¶

Customer information¶

Type-specific parameters¶

Type: ONESHOT¶

Type: SUBSCRIPTION¶

Type: PAYMENT_PLAN¶

Type: PAYMENT_MANDATE¶

Example request: One off payment¶

Example request: Subscription¶

Example request: Payment Plan¶

Example request: Payment Mandate¶

Navigation