Creating a payment order by e-mail
Test the Charge/CreatePaymentOrder Web Service via your playground: Charge/CreatePaymentOrder .
Request
| Parameter | Required | DESCRIPTION |
|---|---|---|
| channelOptions.channelType | Yes | Parameter allowing 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 for generating the e-mail. Il est nécessaire que le modèle existe dans le Back Office pour que cela fonctionne Chaque modèle d’e-mail est associé à une langue (ou locale).Pour utiliser un modèle vous devez vous assurer de transmettre la bonne langue dans le paramètre locale If the model is not found, an error will be returned. If you have defined a value in the subject and body parameters, the template will be ignored. |
| expirationDate | No | Date de validité de l'ordre au format ISO-8601. Ne peut pas être antérieure à la date courante et ne peut pas dépasser 90 jours. Si ce paramètre n'est pas envoyé, la valeur appliquée sera celle de la boutique. Ex : 2021-10-05T21:59:59+00:00 |
| locale | No | Code representing the name of the language and composed of the language code (ISO 639-1) followed by the country code (ISO 3166 alpha-2), separated by the character "_". Allows you to define the language of the payment pages and the confirmation email. If this parameter is not defined, shop language will be used. For example: "fr_FR", "es_CO", "en_EN", "pt_BR" |
| merchantComment | No | Optional comment. |
| amount | Yes | Amount to be paid, expressed in its smallest currency unit (cent for euro). |
| currency | Yes | Payment currency ISO 4217 alpha-3 code Eg: "EUR" for the 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. |
| metadata | No | Custom values linked to the transaction, in JSON format. |
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 | 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. |
| metadata | Custom values linked to the transaction, in JSON format. |
Example of a response
{
"webService": "Charge/CreatePaymentOrder",
"version": "V4",
"applicationVersion": "5.5.0",
"status": "SUCCESS",
"answer": {
"paymentOrderId": "fd8f6060f824427ba687d0161e46af8f",
"paymentURL": "https://secure.lyra.com/t/328zq5so",
"paymentOrderStatus": "RUNNING",
"creationDate": "2020-03-31T15:06:49+00:00",
"updateDate": null,
"amount": 200050,
"currency": "EUR",
"locale": "en_GB",
"strongAuthentication": "AUTO",
"orderId": "myOrderId-999999",
"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.lyra.com/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": "sample@example.com",
"bcc": null,
"_type": "V4/MailDetails"
},
"smsDetails": null,
"whatsAppDetails": 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.lyra.com/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": "PAYZEN",
"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. |
Use cases
3 use cases are available:
- Send an e-mail using the "default" template defined by the payment gateway.
- Send an e-mail using a custom template, defined in the Merchant Back Office.
- 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.
{
"amount": 200050,
"currency": "EUR",
"orderId": "myOrderId-999999",
"channelOptions": {
"channelType": "MAIL",
"mailOptions": {
"recipient": "sample@example.com"
}
},
"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"
}
},
"paymentReceiptEmail": "sample@example.com",
"expirationDate": "2020-04-20T20:13:26+02:00",
"locale": "es_PE",
"dataCollectionForm": "false"
}
{
"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"
}
/**
* I initialize the PHP SDK
*/
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';
/**
* Initialize the SDK
* see keys.php
*/
$client = new Lyra\Client();
/**
* I create a formToken
*/
$store = array("amount" => 250,
"currency" => "EUR",
"orderId" => uniqid("MyOrderId"),
"customer" => array(
"email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);
/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
/* an error occurs, I throw an exception */
display_error($response);
$error = $response['answer'];
throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']);
}
/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];
?>
/**
* I initialize the PHP SDK
*/
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';
/**
* Initialize the SDK
* see keys.php
*/
$client = new Lyra\Client();
/**
* I create a formToken
*/
$store = array("amount" => 250,
"currency" => "EUR",
"orderId" => uniqid("MyOrderId"),
"customer" => array(
"email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);
/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
/* an error occurs, I throw an exception */
display_error($response);
$error = $response['answer'];
throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']);
}
/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];
?>
Example of a query using a custom e-mail template
The Merchant has created a custom template in a specific locale via the
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.
{
"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"
}
/**
* I initialize the PHP SDK
*/
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';
/**
* Initialize the SDK
* see keys.php
*/
$client = new Lyra\Client();
/**
* I create a formToken
*/
$store = array("amount" => 250,
"currency" => "EUR",
"orderId" => uniqid("MyOrderId"),
"customer" => array(
"email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);
/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
/* an error occurs, I throw an exception */
display_error($response);
$error = $response['answer'];
throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']);
}
/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];
?>
/**
* I initialize the PHP SDK
*/
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';
/**
* Initialize the SDK
* see keys.php
*/
$client = new Lyra\Client();
/**
* I create a formToken
*/
$store = array("amount" => 250,
"currency" => "EUR",
"orderId" => uniqid("MyOrderId"),
"customer" => array(
"email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);
/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
/* an error occurs, I throw an exception */
display_error($response);
$error = $response['answer'];
throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']);
}
/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];
?>
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 payment order creation. Allows to specify the start of the payment order validity period. |
| %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.
{
"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"
}
/**
* I initialize the PHP SDK
*/
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';
/**
* Initialize the SDK
* see keys.php
*/
$client = new Lyra\Client();
/**
* I create a formToken
*/
$store = array("amount" => 250,
"currency" => "EUR",
"orderId" => uniqid("MyOrderId"),
"customer" => array(
"email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);
/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
/* an error occurs, I throw an exception */
display_error($response);
$error = $response['answer'];
throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']);
}
/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];
?>
/**
* I initialize the PHP SDK
*/
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';
/**
* Initialize the SDK
* see keys.php
*/
$client = new Lyra\Client();
/**
* I create a formToken
*/
$store = array("amount" => 250,
"currency" => "EUR",
"orderId" => uniqid("MyOrderId"),
"customer" => array(
"email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);
/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
/* an error occurs, I throw an exception */
display_error($response);
$error = $response['answer'];
throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']);
}
/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];
?>
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.
