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 recipients are not visible to the main recipient. Use ";" (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. In order for this to work, the template must exist in the Back Office. Each e-mail template is associated with a language (or locale). To use a template, you need to make sure you pass the correct language in the locale parameter. 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	Expiry date of the order in ISO-8601 format. Cannot be earlier than the current date and exceed 90 days. If this parameter is not sent, the shop value will be applied.
locale	No	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. Allows you to set the language of the payment pages and the confirmation e-mail. If this parameter is not populated, the language will be deduced from the recipient's phone number.
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
	formAction	No
	paymentMethodToken	No
	metadata	No

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
	formAction
	paymentMethodToken
	metadata

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

EMBEDDED FORM

REST WEB SERVICES

Categories

Tags