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 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, 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	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" 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
	formAction	No
	paymentMethodToken	No
	metadata	No

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

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.

EMBEDDED FORM

REST WEB SERVICES

Categories

Tags