• France
status page
Merchant Back Office
assistance
FAQContact support
Search
Categories
Tags
English
French
English
Homepage
Use cases
Create a payment
Create an installment payment
Create a multi-card (split) payment
Create a payment by Alias (Token)
Create a payment link
Create a recurring payment
Manage subscriptions
Manage your transactions (refund, cancel...)
Analyze your reports
API docs
Embedded Form
REST API
Hosted payment
Mobile payment
File exchange
Logos
Push mail
Snippets
Payment methods
Plugins
Guides
Merchant Back Office
Functional guides

Creating a payment order by e-mail

  • Request
  • Sample query
  • Response
  • Error handling

Test the Charge/CreatePaymentOrder Web Service via our playground: Charge/CreatePaymentOrder.

Request for an immediate payment

PARAMETER required Description
channelOptions.channelType YES Parameter to define the channel for issuing the payment order. Must be set to MAIL.
channelOptions.mailOptions YES JSON object allowing to define the specific parameters for creating an e-mail payment order.
channelOptions.mailOptions.recipient YES Recipient's e-mail address.
channelOptions.mailOptions.bcc No List of additional recipients.These addressees are not visible to the main recipient. Use the semicolon ";" as a separator between each address.
channelOptions.mailOptions.subject No Allows you to customize the e-mail subject. This parameter is mandatory unless you specify a valid template name in the channelOptions.mailOptions.template parameter.
channelOptions.mailOptions.body No Allows you to customize the e-mail body. If the parameter is left blank, the default template will be applied.
channelOptions.mailOptions.template No Name of the template to be used to generate the email. The template must exist in the Back Office for this to work. Each email template is associated with a language (or locale). To use a template you need to make sure you pass the correct language in the local setting. If the template is not found an error will be returned. If you have set a value in the subject and body parameters, the template will be ignored.
expirationDate No Validity date of the order in ISO-8601 format. Cannot be earlier than the current date and cannot exceed 90 days. If this parameter is not sent, the value applied de shop default value will be used. Ex : 2021-10-05T21:59:59+00:00
locale No Code representing the name of the language consisting of the language code (ISO 639-1) followed by the country code (ISO 3166 alpha-2), separated by the character "_". It allows you to define the language of the payment pages and the confirmation e-mail. If this parameter is not specified, the language of the shop will be used. For example: "fr_FR", "es_ES", "en_GB", "pt_BR"
merchantComment No Optional comment for the user of theMerchant Back Office. It can be found from the menu :Management>Payment orders: or by displaying the order details in the Information tab of the fieldIdentifiant utilisateur source, or by viewing the columnInformations utilisateur.
amount YES Amount to be paid, expressed in its smallest currency unit (cent for euro).
currency YES Currency of payment. ISO 4217 alpha-3 code. Ex: "EUR" for euro.
orderId No Order reference.
taxAmount No Amount of taxes for the entire order, expressed in its smallest monetary unit (cent for euro).
taxRate No Tax rate applied to the entire order. The value must be the applied percentage (21 for 21%).
transactionOptions.cardOptions.manualValidation No Specifies whether the transaction is validated manually.Possible values: "YES" or "NO".
transactionOptions.cardOptions.captureDelay No Indicates the delay (in days) before the bank capture.
strongAuthentication No Enables or disables strong authentication during payment. Possible values: "ENABLED", "DISABLED", CHALLENGE_REQUESTED, CHALLENGE_MANDATE, NO_PREFERENCE or "AUTO".
paymentReceiptEmail No The e-mail address that will be used for sending the payment ticket to the buyer. Requires the activation of the “Payment confirmation e-mail sent to the buyer” notification rule.
dataCollectionForm No Use of the data collection form.Possible values: "true" or "false".
customer No Object containing buyer's data.
formAction No Allows you to define the desired type of behavior when creating the transaction.
paymentMethodToken No Token of the payment method to be used for the payment.
paymentMethods No List of payment methods to be offered to the buyer.
metadata No Custom values linked to the transaction, in JSON format.

Other optional fields are available.
See all the fields in our playground :Charge/CreatePaymentOrder(menu on left).

Sample query

Immediate payment

3 use cases are available:

  1. Send an e-mail using the "default" template defined by the payment gateway.
  2. Send an e-mail using a custom template, defined in the Merchant Back Office.
  3. Send an e-mail by customizing its content directly in the request.

Example of a query using the default template

The Merchant wishes to send a payment order using the default subject and message of the payment gateway.

To do this, do not transmit the subject , body or template fields.

/doc/en-EN/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.systempay.fr/api-payment/V4/Charge/CreatePaymentOrder
{
  "amount": 10000,
  "currency": "EUR",
  "orderId": "myOrderId-1234",
  "channelOptions": {
    "channelType": "MAIL",
    "mailOptions": {
      "recipient": "customer@example.com"
    }
  }
}
<!-- <pre data-language="json" data-market="es-PE">&#010;{&#010;    &quot;amount&quot;: 200050,&#010;    &quot;currency&quot;: &quot;PEN&quot;,&#010;    &quot;orderId&quot;: &quot;myOrderId-999999&quot;,    &#010;    &quot;channelOptions&quot;: {&#010;      &quot;channelType&quot;: &quot;MAIL&quot;,&#010;      &quot;mailOptions&quot;: {&#010;        &quot;recipient&quot;: &quot;sample@example.com&quot;&#010;      }&#010;    },&#010;    &quot;paymentReceiptEmail&quot;: &quot;sample@example.com&quot;,&#010;    &quot;expirationDate&quot;: &quot;2020-04-20T20:13:26+02:00&quot;,&#010;    &quot;locale&quot;: &quot;es_PE&quot;,&#010;    &quot;dataCollectionForm&quot;: &quot;false&quot;&#010;}&#010;</pre>
{
    "amount": 200050,
    "currency": "ARS",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "es_AR",
    "dataCollectionForm": "false"
}
{
    "amount": 200050,
    "currency": "COP",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "es_CO",
    "dataCollectionForm": "false"
}
{
    "amount": 200050,
    "currency": "BRL",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "pt_BR",
    "dataCollectionForm": "false"
}
--> 
 
 
Example of a query using a custom e-mail template
 
The Merchant has created a custom template in a specific locale via the Merchant Back Office and would like to use it.
 
To do this, use the template field to pass the name of the template to be used.
 
Do not transmit the body and subject fields, they will be ignored.
 
There is no need to transmit the local field, its value will be deduced from the model.
 
/doc/en-EN/rest/V4.0/api/kb/authentication.html
 
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
 
https://api.systempay.fr/api-payment/V4/Charge/CreatePaymentOrder
 
 
{
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "template":"template_fr"
      }
    },
    "paymentReceiptEmail" : "sample@example.com",
    "expirationDate" : "2020-04-20T20:13:26+02:00",
    "dataCollectionForm" : "false"
}
 
{
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "template":"template_en"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "dataCollectionForm": "false"
}
 
{
    "amount": 200050,
    "currency": "PEN",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "template":"template_es"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "dataCollectionForm": "false"
}
 
{
    "amount": 200050,
    "currency": "ARS",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "template":"template_es"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "dataCollectionForm": "false"
}
 
{
    "amount": 200050,
    "currency": "COP",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "template":"template_es"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "dataCollectionForm": "false"
}
 
{
    "amount": 200050,
    "currency": "BRL",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "template":"template_pt"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "dataCollectionForm": "false"
}
 
 
 
Example of a request for sending a custom message
 
The Merchant wishes to personalize the subject and body of the e-mail in their request.
 
To do this, do not transmit the template field.
 
Use the subject and body fields.
 
Variables are provided for their customization:
 
value Description
 
%url% URL of the payment order. If this variable is absent, the payment link will be added automatically at the end of the message.
 
%amount% Payment amount and currency.
 
%start_date% Date of creation of the payment order. Allows you to indicate the beginning of the validity period of the payment order.
 
%end_date% Allows to specify the end of the payment order validity period.
 
%shop_name% Name of your shop as defined in the Back Office.
 
%reference% Order reference.
 
%shop_url% URL of your shop.
 
%shop_contact% E-mail address of the "shop administrator", as defined in the Back Office.
 
In the response, these variables will be replaced by their value.
 
/doc/en-EN/rest/V4.0/api/kb/authentication.html
 
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
 
https://api.systempay.fr/api-payment/V4/Charge/CreatePaymentOrder
 
 
{
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "subject": "Votre commande %reference% sur %shop_name%",
        "body":"Bonjour, <br/>cet e-mail comporte un lien de paiement d'un montant de %amount% valable jusqu'au %end_date%.<br/>Pour confirmer le paiement, cliquez sur le lien suivant: %url%"		
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",  
    "dataCollectionForm": "false"
}
 
{
    "amount": 1500,
    "currency": "EUR",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "subject": "Your payment order %reference% from %shop_name%",
        "body":"Dear customer, <br/>this is a payment order of %amount% valid until %end_date%.<br/>To confirm, please click on the link below: %url%"		
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",  
    "dataCollectionForm": "false"
}
 
{
    "amount": 1500,
    "currency": "PEN",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "subject": "Su solicitud de pago %reference% por %shop_name%",
        "body":"Hola, <br/>Este correo electrónico contiene una solicitud de pago por un importe de %amount% válida hasta el %end_date%.<br/> Para confirmar el pago, haga clic en el enlace siguiente: %url%"		
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",  
    "dataCollectionForm": "false"
}
 
{
    "amount": 20000,
    "currency": "ARS",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
        "subject": "Su solicitud de pago %reference% por %shop_name%",
        "body":"Hola, <br/>Este correo electrónico contiene una solicitud de pago por un importe de %amount% válida hasta el %end_date%.<br/> Para confirmar el pago, haga clic en el enlace siguiente: %url%"		
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",  
    "dataCollectionForm": "false"
}
 
{
    "amount": 100000,
    "currency": "COP",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
	    "subject": "Su solicitud de pago %reference% por %shop_name%",
	    "body":"Hola, <br/>Este correo electrónico contiene una solicitud de pago por un importe de %amount% válida hasta el %end_date%.<br/> Para confirmar el pago, haga clic en el enlace siguiente: %url%"		
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",  
    "dataCollectionForm": "false"
}
 
{
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient":"sample@example.com",
	    "subject": "Sua oferta de pagamento %reference% por %shop_name%",
	    "body":"Caro cliente, <br/>Este e-mail contém uma ordem de pagamento no valor de %amount% válida até %end_date%.<br/> Para confirmar o pagamento, favor clicar sobre o link seguinte: %url%"		
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",  
    "dataCollectionForm": "false"
}
 
 
 
Note:
 
If the locale is specified in the request, the payment link and the order expiry date will be translated into the requested language.
 
Make sure you write the content of the e-mail in the right language.
 
Response
 
The answer object will contain the parameters below:
 
PARAMETER Description
 
paymentOrderId Payment order ID.
 
paymentURL Payment URL.
 
paymentOrderStatus Status of the payment order.
 
creationDate Date and time of payment order creation.
 
updateDate Date and time of payment order update.
 
channelDetails.channelType Transmission channel for the payment order. Set to MAIL.
 
channelDetails.mailDetails.recipient Recipient's e-mail address.
 
channelDetails.mailDetails.subject Subject of the e-mail.
 
channelDetails.mailDetails.body Body of the e-mail.
 
channelDetails.mailDetails.template Name of the used template.
 
channelDetails.mailDetails.bcc Recipient list in hidden copy.
 
MESSAGE Message with the payment link, edited in the locale.
 
amount Amount payable, expressed in the smallest monetary unit.
 
currency Payment currency.ISO 4217 alpha-3 code.
 
locale Code representing the name of the language and consisting of the language code (ISO 639-1) followed by the country code (ISO 3166 alpha-2), separated by the "_" character.
 
strongAuthentication Enables or disables strong authentication during payment.
 
orderId Order reference.
 
paymentReceiptEmail E-mail address that will be used to send the payment receipt to the buyer.
 
taxAmount Amount of taxes for the entire order, expressed in its smallest monetary unit.
 
taxRate Tax rate applied to the entire order.
 
expirationDate Expiry date of the order in ISO-8601 format.
 
dataCollectionForm Use of the data collection form.
 
merchantComment Optional comment.
 
transactionDetails.cardDetails.manualValidation Transaction validation mode.
 
transactionDetails.cardDetails.captureDelay Capture delay.
 
customer Object containing buyer's data.
 
formAction Allows you to define the desired type of behavior when creating the transaction.
 
paymentMethodToken Token of the payment method to be used for the payment.
 
paymentMethods List of payment methods to be offered to the buyer.
 
metadata Custom values linked to the transaction, in JSON format.
 
See all the fields in our playground: PaymentOrder
 
Example of a response
 
{
    "webService": "Charge/CreatePaymentOrder",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f",
        "paymentURL": "https://secure.systempay.fr/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": null,
        "amount": 10000,
        "currency": "EUR",
        "locale": "en_GB",
        "strongAuthentication": "AUTO",
        "orderId": "myOrderId-1234",
        "channelDetails": {
            "channelType": "MAIL",
            "mailDetails": {
                "subject": "Your payment order",
                "body": "<b>Message sent by DEMO STORE</b> <p>Dear customer,</p> <p>This e-mail is a payment order of EUR 2,000.50 valid until 01/04/2020. To confirm, please click on the link below : </p> <p>https://secure.systempay.fr/t/w5izg024</p> <p>In case of problems, or if this message is not correctly displayed, please contact support@demostore.com.</p>",
                "template": null,
                "recipient": "customer@example.com",
                "bcc": null,
                "_type": "V4/MailDetails"
            },
            "smsDetails": null,
            "whatsAppDetails": null,
            "ivrDetails": null,
            "_type": "V4/ChannelDetails"
        },
        "paymentReceiptEmail": "sample@example.com",
        "taxRate": null,
        "taxAmount": null,
        "expirationDate": "2020-04-20T18:13:26+00:00",
        "transactionDetails": {
            "cardDetails": {
                "manualValidation": "NO",
                "captureDelay": 0,
                "_type": "V4/CardDetails"
            },
            "_type": "V4/PaymentOrderTransactionDetails"
        },
        "dataCollectionForm": false,
        "merchantComment": null,
        "message": "<b>Message sent by DEMO STORE</b> <p>Dear customer,</p> <p>This e-mail is a payment order of EUR 2,000.50 valid until 01/04/2020. To confirm, please click on the link below : </p> <p>https://secure.systempay.fr/t/w5izg024</p> <p>In case of problems, or if this message is not correctly displayed, please contact support@demostore.com.</p>",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+00:00",
    "applicationProvider": "NPS",
    "metadata": null,
    "_type": "V4/WebService/Response"
}


}
 
Error handling
 
The Charge/createPaymentOrder  web service will return an error in the following cases:
 
Code Description
 
INT_009 The format of the amount field is invalid or the field is not transmitted.
 
INT_010 The format of the currency field is invalid or the field is not transmitted.
 
INT_050 The strongAuthentication parameter is invalid.
 
INT_841 The mailOptions object is missing.
 
INT_850 The channelOptions.mailOptions.recipient parameter is missing.
 
INT_856 The locale parameter is invalid.
 
INT_858 The taxRate parameter is invalid.
 
INT_869 The taxAmount parameter is invalid.
 
PSP_519 Unknown currency.
 
PSP_606 Currency not supported by the MID.
 
PSP_1007 The expiry date of the payment order cannot be earlier than the current date or exceed 90 days.
 
PSP_1015 No data collection form for this shop.
 
PSP_1018 The data collection form cannot be used for the requested currency.
 
PSP_1022 The template specified in the request does not exist for the requested locale.
© 2024 {'|'} All rights reserved to Systempaylegal
2.92.0-doc-1.11