Skip to main content

Hosted token creation request

This method allows you to initiate an hosted token creation.

By default, the response includes a redirect URL, to which the customer has to be redirected in order to provide the payment method details. However this method also provides you the option of sending directly the action_url to the customer email using notify parameter.

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​

NameTypeDetailsMandatoryDescription
flowstringBUYERYThe customer will provide the payment method details on the SysPay hosted page.
sourceintNThe ID reference for which this request is. This data is provided by SysPay.
accept_untilunix timestampNThis unix timestamp determines the date and time the customer is allowed to complete the operation requested.
descriptionstringMax length 300NThis message which will be displayed on the SysPay hosted page.
return_urlstringNThis parameter overrides the default return_url configuration in your SysPay settings.
ems_urlstringNThis parameter overrides the default ems_url configuration in your SysPay settings.
notifystringEMAILNIf the notify parameter is set to null or not provided, the API response will include an URL of a SysPay hosted page, to which the customer has to be redirected to complete operation. However if this parameter is set to EMAIL, an email will be sent directly to the customer.email including the URL to complete the operation.
allowed_retriesintNThe number of attempts a user has to try to enter the valid payment method details. This parameter can only be accepted if configured on your API. Please contact your SysPay account manager if you require this feature.
extrastringMax length 300NAn extra parameter that is passed back to you when sending a redirect or event message.
mandatebooleanNThis parameter will determine if the token can be used to make future payments/rebills (defaults to true if payment capabilities are activated).
mandate_currencystring[A-Z]3N*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.
customerarrayCustomerNThe customer’s details.

Note: The tokenization methods displayed on our page depends on methods activated and configured on your SysPay Merchant account. By default, only CREDITCARD tokenization on VISA and Mastercard cards is activated. Please note that the methods displayed may also depends on your request parameters:

Tokenization MethodRequest parameterValueMethod displayed ?Comment
CREDITCARDmandatetrueYThis method support future debits once tokenized.
CREDITCARDmandatefalseYThis method supports tokenization only.
SEPAmandatetrueYThis method support future debits once tokenized.
SEPAmandatefalseNThis method does not support tokenization only.

Parameters relative to Hospitality business​

NameTypeDetailsMandatoryDescription
booking_detailsarrayBooking detailsYThe booking details.
expiration_dateunix timestampNThis 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.

Example request​

{
  "flow": "BUYER",
  "source": null,
  "notify": null,
  "accept_until": 1714401765,
  "customer": {
    "reference": "ref-6606d36546d7a",
    "email": "john.doe+6606d36546d7a@gmail.com",
    "firstname": "John",
    "lastname": "Doe",
    "language": "en",
    "ip": "132.15.11.248",
    "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 6606d36548c37 from 2024-04-21 to 2024-04-28.",
  "extra": {
    "internalKey1": "internalValue1",
    "internalKey2": "internalValue2"
  },
  "expiration_date": "1714315365",
  "booking_details": {
    "type": "HOTEL",
    "check_in_date": "2024-04-21",
    "check_out_date": "2024-04-28",
    "booking_id": "6606d36548c37",
    "total_booking_amount": 100000,
    "booking_currency": "EUR"
  }
}

Response parameters​

The response in this case is a Token object.

Example response​

{
  "class": "token",
  "id": "83650",
  "status": "REDIRECT",
  "action_url": "https://receptio-sandbox.syspay.com/redirect/billing-agreement/247222/9bbd0ac691b24b5e8f76742b1de8af1c63eddf1c?_locale=en",
  "booking_id": "6606d36548c37",
  "check_in_date": "2024-04-21",
  "check_out_date": "2024-04-28",
  "booking_details": {
    "class": "booking_details",
    "type": "HOTEL",
    "booking_id": "6606d36548c37",
    "check_in_date": "2024-04-21",
    "check_out_date": "2024-04-28",
    "total_booking_amount": "100000",
    "booking_currency": "EUR"
  },
  "creation_date": "1711723378",
  "expiration_date": "1714315365",
  "accept_until": "1714401765",
  "description": "Booking 6606d36548c37 from 2024-04-21 to 2024-04-28.",
  "extra": "Array",
  "customer": {
    "class": "customer",
    "email": "john.doe+6606d36546d7a@gmail.com",
    "language": "en",
    "firstname": null,
    "lastname": null,
    "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": null,
  "moto_instance_id": null,
  "mandate": {
    "class": "mandate",
    "status": "PENDING",
    "currency": "EUR",
    "end_reason": null,
    "start_date": null,
    "end_date": null
  },
  "payment": null
}