Hosted token creation with initial payment request
This method allows you to initiate an hosted token creation request with an initial payment.
By default, the response includes a redirect URL, to which the customer has to be redirected in order to provide the payment method details. This method 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
| Name | Type | Details | Mandatory | Description |
|---|---|---|---|---|
| flow | string | BUYER | Y | The customer will provide the payment method details on the SysPay hosted page. |
| 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. |
| 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. | |
| notify | string | N | If 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_retries | int | N | The 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. | |
| 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). | |
| customer | array | Customer | N | The customer’s details. |
| payment | array | Payment | Y | The initial payment’s details. |
| payment_method_options | array | Payment Method Options | N | Extra parameters to override payment method options |
Note: The payment methods displayed on our hosted page depends on methods activated and configured on your SysPay Merchant account. By default, only CREDITCARD tokenization on VISA and Master Card card is activated. Please note that the methods displayed may also depends on your request parameters:
| Payment Method | Request parameter | Value | Method displayed ? | Comment |
|---|---|---|---|---|
| CREDITCARD | mandate | true | Y | This method support future debits once tokenized. |
| CREDITCARD | mandate | false | Y | This method supports one time only payments. |
| SEPA | mandate | true | Y | This method support future debits once tokenized. |
| SEPA | mandate | false | Y | This method supports one time only payments. |
| IDEAL | mandate | true | Y | This method support future debits once tokenized. |
| IDEAL | mandate | false | Y | This method supports one time only payments. |
| SOFORT | mandate | true | N | This method does not support tokenization. |
| SOFORT | mandate | false | Y | This method only supports one time only payments. |
| ANCV | mandate | true | N | This method does not support tokenization. |
| ANCV | mandate | false | Y | This method only supports one time only payments. |
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. |
Example request
{
"flow": "BUYER",
"source": null,
"notify": null,
"accept_until": 1712521972,
"customer": {
"reference": "ref-65ea2474778a2",
"email": "john.doe+65ea2474778a2@gmail.com",
"firstname": "John",
"lastname": "Doe",
"language": "en",
"ip": "184.40.204.126",
"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,
"description": "Booking 65ea2474792c8 from 2024-03-30 to 2024-04-06.",
"extra": {
"internalKey1": "internalValue1",
"internalKey2": "internalValue2"
},
"expiration_date": "1712435572",
"booking_details": {
"type": "HOTEL",
"check_in_date": "2024-03-30",
"check_out_date": "2024-04-06",
"booking_id": "65ea2474792c8",
"total_booking_amount": 100000,
"booking_currency": "EUR"
},
"payment": {
"reference": "65ea2474792d8",
"amount": 10000,
"currency": "EUR",
"preauth": false
}
}
Response parameters
The response in this case is a Token object.
Example response
{
"class": "token",
"id": "83350",
"status": "REDIRECT",
"action_url": "https://receptio-sandbox.syspay.com/redirect/payment/246772/d364347d1300c03641c9621e6eda59d81ad4a31f/HOSTED?_locale=en",
"booking_id": "65ea2474792c8",
"check_in_date": "2024-03-30",
"check_out_date": "2024-04-06",
"booking_details": {
"class": "booking_details",
"type": "HOTEL",
"booking_id": "65ea2474792c8",
"check_in_date": "2024-03-30",
"check_out_date": "2024-04-06",
"total_booking_amount": "100000",
"booking_currency": "EUR"
},
"creation_date": "1709843573",
"expiration_date": "1712435572",
"accept_until": "1712521972",
"description": "Booking 65ea2474792c8 from 2024-03-30 to 2024-04-06.",
"extra": "Array",
"customer": {
"class": "customer",
"email": "john.doe+65ea2474778a2@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": {
"class": "payment",
"id": 246772,
"reference": "65ea2474792d8",
"amount": 10000,
"currency": "EUR",
"status": "OPEN",
"preauth_expiration_date": null,
"action_url": "https://receptio-sandbox.syspay.com/redirect/payment/246772/d364347d1300c03641c9621e6eda59d81ad4a31f/HOSTED?_locale=en",
"flow": "BUYER",
"processing_time": null,
"source": 2544,
"contract": null,
"descriptor": null,
"extra": "Array",
"description": "Booking 65ea2474792c8 from 2024-03-30 to 2024-04-06.",
"account_id": 23918,
"merchant_id": 2744,
"merchant_login": "23918001",
"settlement_date": null,
"failure_category": null,
"chip_and_pin_status": null,
"capture_date": null,
"token": {
"class": "reference",
"id": 83350,
"type": "token",
"link": "https://app-sandbox.syspay.com/api/v2/merchant/token/83350"
},
"customer": {
"class": "customer",
"email": "john.doe+65ea2474778a2@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,
"processor_reference": null,
"qr_code": null
}
}