Phone Booking Interface¶

Phone Booking URL request¶

The Phone Booking service allows the partner/merchant to create instances of the Phone Booking web interface. From this screen, and depending on the merchant service, the operator will be able to create credit card tokens, or send tokenization request links with an option to process initial payments.

The authentication process is the the same as the processing API’s one, using a combined header.

When the process is complete, the user will be sent back to the specified url which will contain a result parameter appended to it in order to verify that the request parameter/s has not been tampered with. Please see the post process redirection documentation.

URL syntax:	/api/{version}/merchant/moto-instance
Method:	POST

Input parameters¶

Name	Type	Details	Mandatory	Description
source	int		N	The website reference for which this token request is. (The website/s reference id/s can be checked from the user backend settings page).
expiration_date	unix timestamp		N	A unix timestamp which determines the token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token. If set as null the expiration date will be set as null and not overridden by the checkout date if provided.
language	string	[a-z]{2}	N	Sets the phone booking interface language. Supported languages are: en, fr & it. If not specified it will try to get the browser’s language, by default it will be automatically set to English if the detection fails or the browser language is not supported.
accept_until	unix timestamp		N	A unix timestamp which determines the expiration date of links generated from the phone booking interface. When this parameter is specified it is locked by default. Please refer to Lock phone booking contents section to set this parameter as unlocked and modifiable.
description	string	max length 300	N	The service/product description message which will be displayed on the SysPay payment page and/or in the API response.
phone_booking_return_url	string		N	The URL to redirect the agent to when the booking is complete.
payment_page_return_url	string		N	The URL to redirect the customer to when the booking is complete. (If the ‘send request’ method was used).
ems_url	string		N	This URL can overwrite the default EMS URL
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	N	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	N*	The check_in date of the booking. (*Required if check_out_date is provided).
booking_details.check_out_date	string	YYYY-mm-dd	N*	The check_out date of the booking. (*Required if check_in_date is provided). If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		N*	The total booking fee amount. (*Required if booking_currency is provided).
booking_details.booking_currency	string	[A-Z]{3}	N*	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform. (*Required if total_booking_amount is provided).
extra	string	max length 300	N	An extra parameter that is passed back to the you when sending a callback or redirecting a user to your page.
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements with a list of ids allowed to de-tokenize the token. It is made of your own partner id and/or another one’s
customer.lastname	string	max length 100	N	The customer last name.
customer.gender	string	[M,F]	N	The customer gender. M for male and F for female.
customer.email	string	valid email address	N	The customer email address.
customer.language	string	[a-z]{2}	N	The customer language according to (ISO-639-1). Supported languages are: en, fr, it, de, es and nl.
locked	boolean	true\|false	N	Set to false allows the user to modify the customer/transaction data. Default to false
locked_inputs	array		N	Partial form lock. Contains which inputs will be locked once the form is loaded (see Lock phone booking contents section for details)
allowed_tabs	array		N	Contains which action tabs will be locked once the form is loaded (see Lock phone booking contents and tabs section for details)

Example request¶

{
  "source": 1,
  "expiration_date": 1420464268,
  "accept_until": 1420106292,
  "phone_booking_return_url": "http://www.mysite.com/return.php",
  "payment_page_return_url": "http://www.mysite.com/ems.php",
  "authorized_detokenizers": [
    42,
    9000
  ],
  "customer": {
    "email": "test@domain.com",
    "language": "en"
  }
}

Response parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be moto_instance
id	string	Y	The instance unique identifier
action_url	string	Y	The URL to use the generated instance

Example response¶

{
  "class": "moto_instance",
  "id": "8",
  "action_url": "http://www.syspay.com/redirect/moto-instance/28",
}

Phone Booking URL request with initial payment¶

This method allows the merchant to create a token directly with an initial payment by providing the payment details within the request.

URL syntax:	/api/{version}/merchant/moto-instance
Method:	POST

Input parameters¶

Name	Type	Details	Mandatory	Description
source	int		N	The website reference for which this token request is. (The website/s reference id/s can be checked from the user backend settings page).
expiration_date	unix timestamp		N	A unix timestamp which determines the token expiration date. The token will not be usable after this date. If no expiration_date is provided but the check_out_date is set on the request, the check_out_date plus an interval amount is specified as the expiration_date of the token. If set as null the expiration date will be set as null and not overridden by the checkout date if provided.
language	string	[a-z]{2}	N	Sets the phone booking interface language. Supported languages are: en, fr & it. If not specified it will try to get the browser’s language, by default it will be automatically set to English if the detection fails or the browser language is not supported.
accept_until	unix timestamp		N	A unix timestamp which determines the expiration date of links generated from the phone booking interface. When this parameter is specified it is locked by default. Please refer to Lock phone booking contents section to set this parameter as unlocked and modifiable.
description	string	max length 300	N	The service/product description message which will be displayed on the SysPay payment page and/or in the API response.
phone_booking_return_url	string		N	The URL to redirect the agent to when the booking is complete.
payment_page_return_url	string		N	The URL to redirect the customer to when the booking is complete. (If the ‘send request’ method was used).
booking_details.type	string	HOTEL	Y	The type of the booking.
booking_details.booking_id	string	max length 100	N	The partner reference of the booking.
booking_details.check_in_date	string	YYYY-mm-dd	N*	The check_in date of the booking. (*Required if check_out_date is provided).
booking_details.check_out_date	string	YYYY-mm-dd	N*	The check_out date of the booking. (*Required if check_in_date is provided). If no expiration_date is provided for the token the check_out_date plus an interval amount is specified as the expiration_date of the token. The interval amount is configured within the API settings. For more information please contact customer service.
booking_details.total_booking_amount	int		N*	The total booking fee amount. (*Required if booking_currency is provided).
booking_details.booking_currency	string	[A-Z]{3}	N*	The booking currency (ISO-4217), saved for information purposes only. Please note that this currency does not effect payment and mandate creations processed on the SysPay platform. (*Required if total_booking_amount is provided).
extra	string	max length 300	N	An extra parameter that is passed back to the you when sending a callback or redirecting a user to your page.
authorized_detokenizers	array	2 elements max.	N	An array of 0 to 2 elements with a list of ids allowed to de-tokenize the token. It is made of your own partner id and/or another one’s
customer.lastname	string	max length 100	N	The customer last name.
customer.gender	string	[M,F]	N	The customer gender. M for male and F for female.
customer.email	string	valid email address	N	The customer email address.
customer.language	string	[a-z]{2}	N	The customer language according to (ISO-639-1). Supported languages are: en, fr, it, de, es and nl.
locked	boolean	true\|false	N	Set to false allows the user to modify the customer/transaction data. Default to false
locked_inputs	array		N	Partial form lock. Contains which inputs will be locked once the form is loaded (see Lock phone booking contents section for details)
allowed_tabs	array		N	Contains which action tabs will be locked once the form is loaded (see Lock phone booking contents and tabs section for details)
payment.reference	string	UNIQUE,[ -~]+ (ascii printable characters)	Y	The merchant payment identifier for the request. This must be unique for each payment.
payment.amount	int		Y	The payment amount in cents (500 XXX = 5.00 XXX). Please check the allowed amount from the currency settings found in the user backend.
payment.currency	string	[A-Z]{3}	Y	The currency in which the payment should be processed. The passed currency should follow the (ISO-4217) standard. The list of currencies you are allowed to process can be checked from the settings page in the user backend.
payment.preauth	boolean	true\|false	N	This parameter determines whether the payment request should be fully processed or only authorized. If set to true the pre-auth radio button is set as selected. The pre-auth will need to be captured (see Capture a pre-authorization) or voided (see Void a pre-authorization) later. (Defaults to false).

Example request¶

{
  "source": 1,
  "expiration_date": 1520464268,
  "accept_until": 1520243892,
  "description": "Shopping basket payment",
  "phone_booking_return_url": "http://www.mysite.com/return.php",
  "payment_page_return_url": "http://www.mysite.com/ems.php",
  "customer": {
    "email": "test@domain.com",
    "language": "en"
  },
  "authorized_detokenizers": [
    42,
    9000
  ],
  "payment": {
    "reference": "Unique-111111",
    "amount": 5000,
    "currency": "EUR"
  }
}

Response parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be moto_instance
id	string	Y	The instance unique identifier
action_url	string	Y	The URL to use the generated instance

Example response¶

{
  "class": "moto_instance",
  "id": "8",
  "action_url": "http://www.syspay.com/redirect/moto-instance/28",
}

Lock phone booking contents and tabs¶

Sometimes you might need to provide a partially locked phone booking 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’ and ‘allowed_tabs’ json object.

This objects contains mostly the same parameters as the phone booking 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.

The ‘allowed_tabs’ parameter will prevent the user to use non authorized phone booking functionalities. By default the tabs non mentioned on the array will be active.

Input parameters (‘locked_inputs’)¶

Name	Type	Mandatory	Description
description	boolean	N	Lock the description input
operation	boolean	N	Lock the transaction operation content. Locking an operation when there is a payment object will only allow the user to process a payment or a preauth while not passing a payment object will only allow the user to process a card verification.
payment_amount	boolean	N	Lock the amount input. Setting the amount as locked with no payment object will only allow the user to process a card verification.
reference	boolean	N	Lock the reference input
booking_dates	boolean	N	Lock the check-in and check-out date inputs
accept_until	boolean	N	Lock the option expiration input
payment_currency	boolean	N	Lock the currency input
payment_type	boolean	N	Lock the transaction type input (direct payment or preauthorization)
customer_gender	boolean	N	Lock the Mr/Mrs input
customer_lastname	boolean	N	Lock the lastname input
customer_email	boolean	N	Lock the email input
customer_language	boolean	N	Lock the language dropdown

Input parameters (‘allowed_tabs’)¶

Name	Type	Mandatory	Description
direct_processing	boolean	N	Lock or allow the payment method details form
email_request	boolean	N	Lock or allow the email request tab
secure_link	boolean	N	Lock or allow the secure link tab

Example request:¶

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

{
  "source":1,
  "expiration_date":1420464268,
  "description":"Shopping basket payment",
  "phone_booking_return_url":"http://www.mysite.com/return.php",
  "payment_page_return_url":"http://www.mysite.com/ems.php",
  "authorized_detokenizers":[
    42,
    9000
    ],
  "customer":{
    "email":"test@domain.com",
    "language":"en"
  },
  "payment": {
    "reference": "SYSPEXP",
    "amount": 1200,
    "currency": "GBP",
  },
  "locked_inputs": {
    "customer_email": true,
    "customer_language": true
  },
  "allowed_tabs": {
    "email_request": false
  }
}

Retrieving the token linked to a phone booking¶

Usually, you would retrieve the token information using its id with the relevant webservice, however when it’s being created from the phone booking module, you won’t know about its id.

You can use this webservice to find the token related to a phone booking.

URL syntax:	/api/{version}/merchant/moto-instance/{moto_instance_id}/token
Method:	GET

URL parameters¶

Name	Type	Details	Mandatory	Description
moto_instance_id	string		Y	The phone booking instance id as returned when you created it

Response parameters¶

Name	Type	Mandatory	Description
class	string	Y	The type of object which is being returned. In this case it will be token.
id	int	Y	The SysPay reference of the returned token.
status	string	Y	The token status. see status.
action_url	string	N	The url where the customer should be redirected to in order to access the hosted page and input his/her the card details.
extra	string	N	The extra parameter which was passed to the request.
booking_details	object	Y	The booking details. see booking_details.
creation_date	unix timestamp	Y	The creation date of the token.
expiration_date	unix timestamp	Y	The expiration date of the token. The token will not be usable after this date.
accept_until	unix timestamp	N	A unix timestamp which determines the date and time the customer is allowed to complete the transaction.This parameter will only be returned on BUYER flow.
customer	object	Y	The customer details. see customer.
payment_method	object	Y	The payment method details. see payment_method. When using the hosted flow, this will initially be null until the customer fills in his payment method data.
moto_instance_id	int	N	The moto_instance reference. Only provided if the token was created via a Phone Booking token request. See Phone Booking Interface
mandate	object	N	The mandate details. Will only be returned if a mandate was automatically created. see mandate.
payment	object	N	The payment details. Will only be returned if an initial payment has been requested together with the token creation. see payment.
risk	object	N	The risk of the token. see risk.

Example response¶

{
   "class":"token",
   "id":7,
   "status":"ACTIVE",
   "action_url":null,
   "expiration_date":1421426671,
   "moto_instance_id": "55818247f792ecbf44000005",
   "customer":{
      "class":"customer",
      "email":"test@domain.com",
      "language":"en"
   },
   "payment_method":{
      "class":"payment_method",
      "type":"CREDITCARD",
      "display":"4111-11xx-xxxx-1111",
      "validation_status": "VALID",
      "invalid_reason": null,
      "details":{
         "class":"payment_method_details",
         "holder":"Card Holder Name",
         "scheme": "VISA",
         "exp_month":"01",
         "exp_year":"2015"
      }
   }
}

Navigation

Table Of Contents

Phone Booking Interface¶

Phone Booking URL request¶

Input parameters¶

Example request¶

Response parameters¶

Example response¶

Phone Booking URL request with initial payment¶

Input parameters¶

Example request¶

Response parameters¶

Example response¶

Lock phone booking contents and tabs¶

Input parameters (‘locked_inputs’)¶

Input parameters (‘allowed_tabs’)¶

Example request:¶

Retrieving the token linked to a phone booking¶

URL parameters¶

Response parameters¶

Example response¶

Navigation