Hosted payment request

This method allows you to initiate an hosted payment request.

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.

Note: This method will also create a token if you request mandate creation.

• URL syntax: /api/v2/merchant/payment
• 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	EMAIL	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
payment_method	array		N	Payment method details. See section below.
cryptocurrency_type	string	CBDC | STABLECOIN | BLOCKCHAIN | NFT | OTHER	N	Allows to indicate payment as crypto conversion.

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.
OPENBANKING	mandate	false	Y	This method only supports one time only payments.

payment_method parameter

Using this parameter you will be able to prefill card data form on the SysPay hosted page with the data of 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 .

Example request

{
  "flow": "BUYER",
  "source": null,
  "notify": null,
  "accept_until": 1717319970,
  "customer": {
    "reference": "ref-66335aa2947ab",
    "email": "john.doe+66335aa2947ab@gmail.com",
    "firstname": "John",
    "lastname": "Doe",
    "language": "en",
    "ip": "184.141.232.199",
    "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,
  "reference": "66335aa2947bb",
  "amount": 10000,
  "currency": "EUR",
  "preauth": false
}

Response parameters

The response in this case is a Payment object.

Example response

{
  "class": "payment",
  "id": 247838,
  "reference": "66335aa2947bb",
  "amount": 10000,
  "currency": "EUR",
  "status": "OPEN",
  "preauth_expiration_date": null,
  "action_url": "https://receptio-sandbox.syspay.com/redirect/payment/247838/22584bb901a7b08e45145746126c4d6024debfe3/HOSTED?_locale=en",
  "flow": "BUYER",
  "processing_time": null,
  "source": 2544,
  "contract": null,
  "descriptor": null,
  "extra": null,
  "description": null,
  "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": "token",
    "id": "84082",
    "status": "REDIRECT",
    "action_url": "https://receptio-sandbox.syspay.com/redirect/payment/247838/22584bb901a7b08e45145746126c4d6024debfe3/HOSTED?_locale=en",
    "booking_details": null,
    "creation_date": "1714641571",
    "expiration_date": null,
    "accept_until": "1717319970",
    "description": null,
    "extra": null,
    "customer": {
      "class": "customer",
      "email": "john.doe+66335aa2947ab@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": "reference",
      "id": 247838,
      "type": "payment",
      "link": "https://app-sandbox.syspay.com/api/v2/merchant/payment/247838"
    }
  },
  "customer": {
    "class": "customer",
    "email": "john.doe+66335aa2947ab@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
}