Server-to-server token creation request

This method allows you to initiate a token creation by providing the payment method details within the request.

If the interactive paramater is set to true, the operation may require a redirection to complete the operation. So the response will include a redirect URL, to which the customer has to be redirected in order to provide the payment method details. When the process is complete, your customer will be sent back to your return_url which the responses will be appended to. In order to verify that these parameters have not been tampered with, see the Post process redirection documentation. A server-to-server notification will also be sent to your ems_url, see the EMS documentation.

URL syntax: /api/v2/merchant/token
Method: POST

Request parameters

Name	Type	Details	Mandatory	Description
flow	string	API	Y	The payment method details will be sent directly with the API call.
source	int		N	The ID reference for which this request is. This data is provided by SysPay.
accept_until	unix timestamp		N	This unix timestamp determines the date and time the customer is allowed to complete the operation requested.
description	string	Max length 300	N	This message which will be displayed on the SysPay hosted page.
interactive	boolean		Y	This parameter specifies if the payment method holder is involved and request could be completed by him/her (if applicable)
return_url	string		N	This parameter overrides the default return_url configuration in your SysPay settings.
ems_url	string		N	This parameter overrides the default ems_url configuration in your SysPay settings.
extra	string	Max length 300	N	An extra parameter that is passed back to you when sending a redirect or event message.
mandate	boolean		N	This parameter will determine if the token can be used to make future payments/rebills (defaults to true if payment capabilities are activated).
mandate_currency	string	[A-Z]3	N*	The currency that will be used to make future payments. (ISO-4217). * Required if `mandate` is set to true and not initial payment required as the mandate currency will be the payment currency.
customer	array	Customer	N*	The customer’s details. * Required if the `interactive` is set to true.
payment_method	array		Y	Payment method details. See section below.

Parameters relative to Hospitality business

Name	Type	Details	Mandatory	Description
booking_details	array	Booking details	Y	The booking details.
expiration_date	unix timestamp		N	This unix timestamp determines the token expiration date. After this date, the payment method details will not be anymore visible on SysPay interfaces. If no `expiration_date` is provided, the `booking_details.check_out_date` plus an interval amount will be used as the expiration date of the token. If set as null, the payment method details will not be visible at all.

`payment_method` parameter

This API method allows you to create token only on cards by providing raw card data or using our Client-side card tokenisation service.

Using raw card data

Name	Type	Details	Mandatory	Description
type	string	CREDITCARD	Y	The type of payment object to be passed in the api call.
cardholder	string	Max length 100	Y	Cardholder name. Please note that non-alphabetic characters other than `@ . - _ ‘` will be stripped out. Names containing digits will be rejected by validation.
number	string	[0-9]19	Y	Valid credit card number, only digits.
exp_month	string	[0-9]2	Y	Credit card expire month (ex: 05).
exp_year	string	[0-9]4	Y	Credit card expire year (ex: 2015).
cvc	int	[0-9]4	N*	Credit card verification code. The CVC is always required if `interactive` is true or if `interactive` is false and your API settings do not allow you to process payments or create mandates without providing it.

Using our Client-side card tokenisation service

Name	Type	Details	Mandatory	Description
type	string	CREDITCARD	Y	The type of payment object to be passed in the api call.
token_key	string		Y	The token value provided by the JS tokenizer service.

Using an existing SysPay Token

Name	Type	Details	Mandatory	Description
type	string	CREDITCARD	Y	The type of payment object to be passed in the api call.
token_id	int		Y	The SysPay token ID .
cvc	int	[0-9]4	N*	Credit card verification code. The CVC is always required if `interactive` is true or if `interactive` is false and your API settings do not allow you to process payments or create mandates without providing it.

Example request

{
  "flow": "API",
  "interactive": false,
  "source": null,
  "notify": null,
  "accept_until": 1712524868,
  "customer": {
    "reference": "ref-65ea2fc46ecff",
    "email": "john.doe+65ea2fc46ecff@gmail.com",
    "firstname": "John",
    "lastname": "Doe",
    "language": "en",
    "ip": "77.9.116.75",
    "billing_address": {
      "address1": "55 rue du Faubourg Saint-Honoré",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR"
    }
  },
  "return_url": "http://www.mysite.com/return.php",
  "ems_url": "http://www.mysite.com/ems.php",
  "mandate": true,
  "mandate_currency": "EUR",
  "description": "Booking 65ea2fc470382 from 2024-03-30 to 2024-04-06.",
  "extra": {
    "internalKey1": "internalValue1",
    "internalKey2": "internalValue2"
  },
  "expiration_date": "1712438468",
  "booking_details": {
    "type": "HOTEL",
    "check_in_date": "2024-03-30",
    "check_out_date": "2024-04-06",
    "booking_id": "65ea2fc470382",
    "total_booking_amount": 100000,
    "booking_currency": "EUR"
  },
  "payment_method": {
    "type": "CREDITCARD",
    "number": "4221709846468008",
    "cardholder": "Card Holder Name",
    "exp_month": "01",
    "exp_year": "2025",
    "cvc": "123"
  }
}

Response parameters

The response in this case is a Token object.

Example response on request with raw card data provided and 'false' interactive flag

{
  "class": "token",
  "id": "83372",
  "status": "ACTIVE",
  "action_url": null,
  "booking_id": "65ea2fc470382",
  "check_in_date": "2024-03-30",
  "check_out_date": "2024-04-06",
  "booking_details": {
    "class": "booking_details",
    "type": "HOTEL",
    "booking_id": "65ea2fc470382",
    "check_in_date": "2024-03-30",
    "check_out_date": "2024-04-06",
    "total_booking_amount": "100000",
    "booking_currency": "EUR"
  },
  "creation_date": "1709846470",
  "expiration_date": "1712438468",
  "description": "Booking 65ea2fc470382 from 2024-03-30 to 2024-04-06.",
  "extra": "Array",
  "customer": {
    "class": "customer",
    "email": "john.doe+65ea2fc46ecff@gmail.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address": {
      "class": "billing_address",
      "address1": "55 rue du Faubourg Saint-Honoré",
      "address2": null,
      "address3": null,
      "city": "Paris",
      "country": "FR",
      "postal_code": "75008"
    }
  },
  "payment_method": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "validation_status": "NOT_VALIDATED",
    "validation_date": null,
    "invalid_reason": null,
    "display": "4221-70xx-xxxx-8008",
    "details": {
      "class": "payment_method_details",
      "fingerprint": "a3bb29a5-e480-43e4-bca6-625c8e2b128f",
      "holder": "Card Holder Name",
      "scheme": null,
      "exp_month": "01",
      "exp_year": "2025"
    }
  },
  "moto_instance_id": null,
  "mandate": {
    "class": "mandate",
    "status": "ACTIVE",
    "currency": "EUR",
    "end_reason": null,
    "start_date": 1709846470,
    "end_date": null
  },
  "payment": null
}

Example response on request with raw card data provided and 'true' interactive flag

{
  "class": "token",
  "id": "83373",
  "status": "REDIRECT",
  "action_url": "https://process-secpay-sandbox.syspay.com/3ds/go?transaction_id=188637&account_id=45&checksum=b4bb3cbace15b400e5b332bd2527715b",
  "booking_id": "65ea304e7d75e",
  "check_in_date": "2024-03-30",
  "check_out_date": "2024-04-06",
  "booking_details": {
    "class": "booking_details",
    "type": "HOTEL",
    "booking_id": "65ea304e7d75e",
    "check_in_date": "2024-03-30",
    "check_out_date": "2024-04-06",
    "total_booking_amount": "100000",
    "booking_currency": "EUR"
  },
  "creation_date": "1709846608",
  "expiration_date": "1712438606",
  "description": "Booking 65ea304e7d75e from 2024-03-30 to 2024-04-06.",
  "extra": "Array",
  "customer": {
    "class": "customer",
    "email": "john.doe+65ea304e7c783@gmail.com",
    "language": "en",
    "firstname": "John",
    "lastname": "Doe",
    "billing_address": {
      "class": "billing_address",
      "address1": "55 rue du Faubourg Saint-Honoré",
      "address2": null,
      "address3": null,
      "city": "Paris",
      "country": "FR",
      "postal_code": "75008"
    }
  },
  "payment_method": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "validation_status": "NOT_VALIDATED",
    "validation_date": null,
    "invalid_reason": null,
    "display": "4331-70xx-xxxx-6000",
    "details": {
      "class": "payment_method_details",
      "fingerprint": "0fb913e7-62a1-417c-b93a-452ccf565abb",
      "holder": "Card Holder Name",
      "scheme": null,
      "exp_month": "01",
      "exp_year": "2028"
    }
  },
  "moto_instance_id": null,
  "mandate": {
    "class": "mandate",
    "status": "PENDING",
    "currency": "EUR",
    "end_reason": null,
    "start_date": null,
    "end_date": null
  },
  "payment": null
}

Server-to-server token creation request

Request parameters​

Parameters relative to Hospitality business​

payment_method parameter​

Using raw card data​

Using our Client-side card tokenisation service​

Using an existing SysPay Token​

Example request​

Response parameters​

Example response on request with raw card data provided and 'false' interactive flag​

Example response on request with raw card data provided and 'true' interactive flag​