Server-to-server payment request

This method allows you to initiate a payment 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.

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	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 a token will be created and then can be used to make future payments/rebills. * Defaults to true if payment capabilities are activated.
reference	string	UNIQUE, [ -~] + (max: 85 ascii printable characters)	Y	Your own payment identifier for the request.
amount	int		Y	The payment amount in cents (500 XXX = 5.00 XXX).
currency	string	[A-Z] 3	Y	The currency in which the payment should be processed. The payment currency (ISO-4217). This will also be the default currency for the created mandate.
preauth	boolean		N*	This parameter determines whether the payment request should be fully processed or only authorized. * Defaults to false.
capture_date	unix timestamp		N	This parameter determines when the pre-authorization will be automatically captured (if applicable).
recipient_map	array		N	See Paying out to other accounts section.
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.
device	array	Device	N*	Extra parameters for improved 3D Secure Assessment. * Required if you’re not using our client-side tokenization solution and therefore not providing a payment_method.token_key and if interactive as true
cryptocurrency_type	string	CBDC | STABLECOIN | BLOCKCHAIN | NFT | OTHER	N	Allows to indicate payment as crypto conversion.

payment_method parameter

This API method allows you to request payment on card by providing raw data, using our Client-side card tokenisation service, IDEAL, ANCV or OPENBANKING.

Using raw card data

Name	Type	Details	Mandatory	Description
type	string	CREDITCARD	Y	The type of payment method 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 method 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.

IDEAL payment_method specific parameters

Name	Type	Details	Mandatory	Description
type	string	IDEAL	Y	The type of payment method to be passed in the api call.
bank_id	int		Y	The iDeal bank ID. See Get a list of iDeal banks API method.

Note: IDEAL only supports one-shot payment and requires payment method holder interaction so interactive must be set as true and mandate as false if you would like to process with this payment method.

ANCV payment_method specific parameters

Name	Type	Details	Mandatory	Description
type	string	ANCV_CVCO	Y	The type of payment method to be passed in the api call.
beneficiary_id	int		N*	Data provided by the ANCV account holder. * If set and valid, the buyer receives a notification on its app and payment is pending until the buyer will finalize it. If provided and not valid, the payment will be marked as ERROR. If not provided, you will find in the payment response parameter qr_code, the base64 encoded image data to be displayed and scanned by the ANCV account holder to finalize it.

Note: ANCV only supports one-shot payment and requires payment method holder interaction so interactive must be set as true and mandate as false if you would like to process with this payment method.

OPENBANKING payment_method specific parameters

Name	Type	Details	Mandatory	Description
type	string	OPENBANKING	Y	The type of payment method to be passed in the api call.

Note: OPENBANKING only supports one-shot payment and requires payment method holder interaction so interactive must be set as true and mandate as false if you would like to process with this payment method.

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

{
  "flow": "API",
  "interactive": false,
  "source": null,
  "notify": null,
  "accept_until": 1712525116,
  "customer": {
    "reference": "ref-65ea30bcbff9d",
    "email": "john.doe+65ea30bcbff9d@gmail.com",
    "firstname": "John",
    "lastname": "Doe",
    "language": "en",
    "ip": "32.156.37.125",
    "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 65ea30bcc1799 from 2024-03-30 to 2024-04-06.",
  "reference": "65ea30bcc17aa",
  "amount": 10000,
  "currency": "EUR",
  "preauth": false,
  "extra": {
    "internalKey1": "internalValue1",
    "internalKey2": "internalValue2"
  },
  "booking_details": {
    "type": "HOTEL",
    "check_in_date": "2024-03-30",
    "check_out_date": "2024-04-06",
    "booking_id": "65ea30bcc1799",
    "total_booking_amount": 100000,
    "booking_currency": "EUR"
  },
  "payment_method": {
    "type": "CREDITCARD",
    "number": "4641709846716002",
    "cardholder": "Card Holder Name",
    "exp_month": "01",
    "exp_year": "2025",
    "cvc": "123"
  }
}

Response parameters

The response in this case is a Payment object and may include a Token object.

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

{
  "class": "payment",
  "id": 253411,
  "reference": "66f174d26dcde",
  "amount": 10000,
  "currency": "EUR",
  "status": "SUCCESS",
  "preauth_expiration_date": null,
  "action_url": null,
  "flow": "API",
  "processing_time": 1727100117,
  "source": 2544,
  "contract": "SysPay (8737476)",
  "descriptor": "Test Contract",
  "extra": null,
  "description": null,
  "account_id": 23918,
  "merchant_id": 2744,
  "merchant_login": "23918001",
  "settlement_date": 1727100118,
  "failure_category": null,
  "chip_and_pin_status": null,
  "capture_date": null,
  "token": {
    "class": "token",
    "id": "87708",
    "status": "EXPIRED",
    "action_url": null,
    "booking_details": null,
    "creation_date": "1727100117",
    "expiration_date": null,
    "description": null,
    "extra": null,
    "customer": {
      "class": "customer",
      "email": "john.doe+66f174d26dccf@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": "4591-72xx-xxxx-4003",
      "details": {
        "class": "payment_method_details",
        "fingerprint": "281bd74a-515e-4544-8410-936c4f7478ff",
        "holder": "Card Holder Name",
        "scheme": null,
        "exp_month": "01",
        "exp_year": "2030"
      }
    },
    "moto_instance_id": null,
    "mandate": {
      "class": "mandate",
      "status": "ACTIVE",
      "currency": "EUR",
      "end_reason": null,
      "start_date": 1727100117,
      "end_date": null
    },
    "payment": {
      "class": "reference",
      "id": 253411,
      "type": "payment",
      "link": "https://app-sandbox.syspay.com/api/v2/merchant/payment/253411"
    }
  },
  "customer": {
    "class": "customer",
    "email": "john.doe+66f174d26dccf@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": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "validation_status": "NOT_VALIDATED",
    "validation_date": null,
    "invalid_reason": null,
    "display": "4591-72xx-xxxx-4003",
    "details": {
      "class": "payment_method_details",
      "fingerprint": "281bd74a-515e-4544-8410-936c4f7478ff",
      "holder": "Card Holder Name",
      "scheme": null,
      "exp_month": "01",
      "exp_year": "2030"
    }
  },
  "processor_reference": null,
  "qr_code": null
}

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

{
  "class": "payment",
  "id": 253412,
  "reference": "66f17512b5c8d",
  "amount": 10000,
  "currency": "EUR",
  "status": "OPEN",
  "preauth_expiration_date": null,
  "action_url": "https://receptio-sandbox.syspay.com/redirect/payment/253412/73176715e417fdf37e8d986099a4f6960962ef7b/HOSTED?_locale=en",
  "flow": "API",
  "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": "87709",
    "status": "REDIRECT",
    "action_url": "https://receptio-sandbox.syspay.com/redirect/payment/253412/73176715e417fdf37e8d986099a4f6960962ef7b/HOSTED?_locale=en",
    "booking_details": null,
    "creation_date": "1727100181",
    "expiration_date": null,
    "description": null,
    "extra": null,
    "customer": {
      "class": "customer",
      "email": "john.doe+66f17512b5c7d@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": "4791-72xx-xxxx-8006",
      "details": {
        "class": "payment_method_details",
        "fingerprint": "922a8d9a-2355-4d62-bf7b-2769bef609b2",
        "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": {
      "class": "reference",
      "id": 253412,
      "type": "payment",
      "link": "https://app-sandbox.syspay.com/api/v2/merchant/payment/253412"
    }
  },
  "customer": {
    "class": "customer",
    "email": "john.doe+66f17512b5c7d@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": {
    "class": "payment_method",
    "type": "CREDITCARD",
    "validation_status": "NOT_VALIDATED",
    "validation_date": null,
    "invalid_reason": null,
    "display": "4791-72xx-xxxx-8006",
    "details": {
      "class": "payment_method_details",
      "fingerprint": "922a8d9a-2355-4d62-bf7b-2769bef609b2",
      "holder": "Card Holder Name",
      "scheme": null,
      "exp_month": "01",
      "exp_year": "2028"
    }
  },
  "processor_reference": null,
  "qr_code": null
}