Updating a payment order
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. |