lyra.com
Search
Categories
Tags
Europe (English)
France
Spain
Europe (English)
India
Home
Implementation
Embedded form
Hosted payment page
REST payment API
Webservices implementation guide
File exchange payment
Mobile payment
Marketplace
Helpers and tools
Free payment plugins
Snippets
Back Office
Back Office Expert
Back Office Merchant
Guides
Help
FAQ
Support

Creating a payment order by e-mail

  • Request
  • Response
  • Error handling
  • Use cases

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:

  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.

{
    "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 Expert 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.

{
    "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.

Recruitment

Head Office :

LYRA NETWORK
109, rue de l’innovation
31670 Labège
FRANCE