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 open payment orders (status RUNNING ) can be modified. The broadcast 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 | A json object to define the specific parameters for creating a payment order by email. Required if the payment order to be modified is of type MAIL. |
channelOptions.mailOptions.recipient | No | Recipient's email address. Required if the payment order to be modified is of type MAIL. |
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 to be used to generate the email. The template must exist in the Back Office. Each email template is associated with a language (or locale). To use a template you need to make sure you pass the correct language in the local setting. If the template is not found an error will be returned. If you have set a value in the subject and body parameters, they will be ignored and replaced with those of the template. |
channelOptions.smsOptions | No | A json object used to define the specific parameters for creating an sms payment order. Required if the payment order to be modified is of type SMS. |
channelOptions.smsOptions.phoneNumber | No | Recipient's cell phone number. Required if the payment order to be modified is of type SMS. |
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 to define the specific parameters for creating a WhatsApp payment order. Required if the payment order to be modified is of type WHATSAPP. |
channelOptions.whatsAppOptions.phoneNumber | No | Recipient's phone number. Required if the payment order to be modified is of type WHATSAPP. |
expirationDate | No | Validity date of the order in ISO-8601 format. Cannot be earlier than the current date and cannot exceed 90 days. If this parameter is not sent, the value applied de shop default value will be used. 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 filled in, the language will be deduced from the recipient's phone number. |
merchantComment | No | Optional comment for the user of theIdentifiant utilisateur source , or by viewing the columnInformations utilisateur . |
amount | YES | Amount to be paid, expressed in its smallest currency unit (cent for euro). |
currency | YES | Currency of payment. ISO 4217 alpha-3 code. Ex: "EUR" for 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 | Allows you to enable or disable 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
/doc/en-EN/rest/V4.0/api/kb/authentication.html
https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44
https://api.systempay.fr/api-payment/V4/Charge/PaymentOrder/Update
{ "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 email sent. Present only if channelDetails.channelType is set to MAIL. |
channelDetails.mailDetails.body | Body of the sent email. 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 | Optional 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.systempay.fr/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.systempay.fr/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.systempay.fr/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": "NPS", "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. |