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

Updating a payment order

  • Use cases
  • Request
  • Response
  • Error handling

Test the Charge/PaymentOrder/Update web service via our playground: Charge/PaymentOrder/Update .

Use cases

The Merchant wishes to edit the content of a payment order (amount, message, etc.).

The Charge/PaymentOrder/Update web service allows you to edit only the payment orders created with the Charge/CreatePaymentOrder web service.

Only the payment orders in progress ( RUNNING status) can be updated. The distribution channel cannot be changed.

Request

Parameter Required DESCRIPTION
paymentOrderId Yes ID of the payment order to be edited.
channelOptions.channelType Yes Parameter allowing to define the channel for issuing the payment order.
channelOptions.mailOptions No JSON object allowing to define the specific parameters for creating an e-mail payment order. Required if the payment order to be modified is of MAIL type.
channelOptions.mailOptions.recipient No Recipient's e-mail address. Required if the payment order to be modified is of MAIL type.
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, they will be ignored and replaced by those of the template.
channelOptions.smsOptions No A JSON object for defining the parameters specific to creating a payment order by SMS. Required if the payment order to be updated is of SMS type.
channelOptions.smsOptions.phoneNumber No Recipient's cell phone number. Required if the payment order to be updated is of SMS type.
channelOptions.smsOptions.message No Allows you to customize the body of the message. If the parameter is left empty, the default message will be applied.
channelOptions.whatsAppOptions No A JSON object allowing to set the specific parameters for creating a WhatsApp payment order. Required if the payment order to be updated is of WHATSAPP type.
channelOptions.whatsAppOptions.phoneNumber No Recipient's phone number. Required if the payment order to be updated is of WHATSAPP type.
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 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" or "AUTO".
paymentReceiptEmail No E-mail address that will be used to send the payment receipt to the buyer.
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.

Sample request

{
    "paymentOrderId": "d63e7f507a6f4dfa86cb40a833ecfd85",
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-05-20T20:13:26+02:00", 
    "dataCollectionForm": "true"
}
{
    "paymentOrderId": "d63e7f507a6f4dfa86cb40a833ecfd85",
    "amount": 200050,
    "currency": "PEN",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-05-20T20:13:26+02:00",
    "locale": "es_PE",
    "dataCollectionForm": "true"
}
{
    "paymentOrderId": "d63e7f507a6f4dfa86cb40a833ecfd85",
    "amount": 200050,
    "currency": "ARS",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-05-20T20:13:26+02:00",
    "locale": "es_AR",
    "dataCollectionForm": "true"
}
{
    "paymentOrderId": "d63e7f507a6f4dfa86cb40a833ecfd85",
    "amount": 200050,
    "currency": "COP",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "MAIL",
      "mailOptions": {
        "recipient": "sample@example.com"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-05-20T20:13:26+02:00",
    "locale": "es_CO",
    "dataCollectionForm": "true"
}
/**
 * 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"];

?>

Response

The answser object will contain the following parameters:

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 Distribution channel of the payment order.
channelDetails.mailDetails.recipient Recipient's e-mail address. Present only if channelDetails.channelType is set to MAIL .
channelDetails.mailDetails.subject Subject of the e-mail. Present only if channelDetails.channelType is set to MAIL .
channelDetails.mailDetails.body Body of the e-mail. Present only if channelDetails.channelType is set to MAIL .
channelDetails.mailDetails.template Name of the used template. Present only if channelDetails.channelType is set to MAIL .
channelDetails.mailDetails.bcc Recipient list in hidden copy. Present only if channelDetails.channelType is set to MAIL .
channelDetails.smsDetails.phoneNumber Recipient's phone number with the international access code. Present only if channelDetails.channelType is set to SMS .
channelDetails.smsDetails.message Body of the sent message. Present only if channelDetails.channelType is set to SMS .
channelDetails.whatsAppDetails.phoneNumber Recipient's phone number with the international access code. Present only if channelDetails.channelType is set to WHATSAPP .
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 Merchant preference for strong authentication.
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 No
formAction No
paymentMethodToken No
metadata No

Example of a response

{
    "webService": "Charge/PaymentOrder/Update",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        "paymentOrderId": "d63e7f507a6f4dfa86cb40a833ecfd85",
        "paymentURL": "https://secure.lyra.com/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": "2020-04-29T12:55:50+00:00",
        "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-05-20T18:13:26+00:00",
        "transactionDetails": {
            "cardDetails": {
                "manualValidation": "NO",
                "captureDelay": 0,
                "_type": "V4/CardDetails"
            },
            "_type": "V4/PaymentOrderTransactionDetails"
        },
        "dataCollectionForm": true,
        "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-04-29T12:55:50+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_836 The smsOptions object is missing.
INT_837 The channelOptions.whatsAppOptions.phoneNumber parameter is missing.
INT_838 The channelOptions.smsOptions.phoneNumber parameter is missing.
INT_839 The whatsAppOptions object is missing.
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.
INT_902 The format of the paymentOrderId field is invalid or the field is not transmitted.
PSP_519 Unknown currency.
PSP_606 Currency not supported by the MID.
PSP_1000 The payment order does not exist.
PSP_1001 Unable to reach the WhatsApp gateway.
PSP_1002 The recipient's phone number is not associated with a WhatsApp account.
PSP_1003 WhatsApp configuration missing.
PSP_1004 The WhatsApp template is not available for the requested locale.
PSP_1005 Update not possible for a paid payment order.
PSP_1006 Update not possible for an expired payment order.
PSP_1007 The expiry date of the payment order cannot be earlier than the current date or exceed 90 days.
PSP_1011 The mode (TEST or PRODUCTION) of the payment order does not match the request mode.
PSP_1015 No data collection form for this shop.
PSP_1017 The distribution channel cannot be changed.
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.
Recruitment

Head Office :

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