Creating an invoice payment order
Test the Web Service Charge/CreatePaymentOrder from our playground: Charge/CreatePaymentOrder ( only for cash payment ).
- Fields for immediate payment
- Fields for payment in instalments
- Fields for payment in instalments with a personalized payment schedule
Use cases
The merchant has sent an invoice for payment to his customer. He then sends him the link to the data collection form.
The buyer will have to enter the invoice reference and fill in his personal data. The amount is automatically displayed after entering the invoice reference.
The buyer can pay in cash or in installments.
Request
Fields for immediate payment
Call the PCharge/CreatePaymentOrder service using the fields below:
PARAMETER | required | Description |
---|---|---|
channelOptions.channelType | YES | Parameter to define the channel for issuing the payment order. Must be set to INVOICE. |
channelOptions.mailOptions | YES | JSON object allowing to define the specific parameters for creating an e-mail payment order. |
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 defined, shop language will be used. For example: "fr_FR", "es_ES", "en_GB", "pt_BR" |
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 | YES | Unique reference of the invoice to be paid.the request will be refused if an invoice payment order already exists with this reference, regardless of its status (canceled or other). |
description | No | Optional description of the invoice to be paid.The maximum length is 65 characters. |
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". |
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. |
paymentMethods | No | List of payment methods to be offered to the buyer. |
metadata | No | Custom values linked to the transaction, in JSON format. |
Other optional fields are available.
See all the fields in our playground :Charge/CreatePaymentOrder(menu on left).
Fields for payment in instalments
- subject to option and/or depending on your offer
- not available for SEPA payments
- add the following fields :
PARAMETER | required | Description |
---|---|---|
transactionOptions.installmentOptions.firstAmount | YES | Indicates the amount of the first payment (expressed in the smallest unit of the currency). |
transactionOptions.installOptions.count | YES | Indicates the total number of installments. |
transactionOptions.installationOptions.period | YES | Indicates the number of days between 2 payments. |
Example query: Payment in installments.
Fields for payment in instalments with a personalized payment schedule
- subject to the "Advanced payment in instalments" option *not available for SEPA payment.
- not taking into account the value of the Capture Delay field (time to bank)
- add the following fields :
PARAMETER | required | Description |
---|---|---|
transactionOptions.installationOptions.schedules[date] | YES | Indicates the due date. The date must not be in the past. |
transactionOptions.installmentOptions.schedules[amount] | YES | Indicates the payment amount (expressed in the smallest unit of the currency). |
Example request: Payment in installments with a customized schedule.
Sample request
Immediate payment
{ "amount": 200050, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "INVOICE" }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "description" : "My custom description" }
{ "amount": 200050, "currency": "PEN", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "INVOICE" }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_PE", "description" : "My custom description" }
{ "amount": 200050, "currency": "ARS", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "INVOICE" }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_AR", "description" : "My custom description" }
{ "amount": 200050, "currency": "COP", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "INVOICE" }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_CO", "description" : "My custom description" }
/** * 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"]; ?>
Payment in installments
{ "amount": 20050, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "INVOICE", "smsOptions": { "phoneNumber": "+33611111111" } }, "transactionOptions": { "installmentOptions": { "firstAmount": 5000, "count": 3, "period": 7 } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2023-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
Result:
The first payment of 50.00 EUR is created on D+0.
The second payment of 75.25 EUR is created on D+7.
The third payment of 75.25 EUR is created on D+14.
Pay in instalments with a personalized payment plan
{ "amount": 10000, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "INVOICE", "mailOptions": { "recipient": "sample@example.com" } }, "transactionOptions": { "installmentOptions": { "schedules": [ { "date": "2023-04-01T23:59:59+00:00", "amount": 5000 }, { "date": "2023-05-01T23:59:59+00:00", "amount": 3000 }, { "date": "2023-06-01T23:59:59+00:00", "amount": 2000 } ] } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2023-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
Result:
The second payment will be made on April 1, 2023 in the amount of EUR 50.00.
The second payment will be made on May 1, 2023 in the amount of EUR 30.00.
The third payment will be made on June 1, 2023 in the amount of EUR 20.00.
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 | Payment order transmission channel. Set to INVOICE |
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. |
transactionDetails.cardDetails.manualValidation | Transaction validation mode. |
transactionDetails.cardDetails.captureDelay | Capture delay. |
dataCollectionForm | Use of the data collection form.Always set to true. |
merchantComment | Optional comment. |
description | Description of the invoice. |
customer | Object containing buyer's data. |
formAction | Allows you to define the desired type of behavior when creating the transaction. |
paymentMethodToken | Token of the payment method to be used for the payment. |
paymentMethods | List of payment methods to be offered to the buyer. |
metadata | Custom values linked to the transaction, in JSON format. |
transactionDetails.installmentDetails.firstAmount | Amount of the first payment (expressed in the smallest unit of the currency). |
transactionDetails.installationDetails.count | Total number of installments. |
transactionDetails.installationDetails.period | Number of days between 2 payments. |
transactionDetails.installmentDetails.schedules[date] | Customized due date. |
transactionDetails.installmentDetails.schedules[amount] | Personalized payment amount (expressed in the smallest unit of the currency). |
See all the fields in our playground: PaymentOrder
Example of a response
{ "webService": "Charge/CreatePaymentOrder", "version": "V4", "applicationVersion": "5.5.0", "status": "SUCCESS", "answer": { "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f", "paymentURL": "https://scelliuspaiement.labanquepostale.fr/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": "INVOICE", "mailDetails": null, "smsDetails": null, "whatsAppDetails": null, "ivrDetails": 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": null, "description": "My custom description" "_type": "V4/PaymentOrder" }, "ticket": null, "serverDate": "2020-03-31T15:06:49+00:00", "applicationProvider": "LBP", "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_815 | The description parameter is too long.The maximum length is 65 characters. |
INT_856 | The locale parameter is invalid. |
INT_858 | The taxRate parameter is invalid. |
INT_869 | The taxAmount parameter is invalid. |
INT_929 | The installmentOptions.count parameter is invalid. |
INT_930 | The installmentOptions.period parameter is invalid. |
INT_931 | The installmentOptions.schedules[] parameter is invalid. |
INT_932 | The installmentOptions.schedules[date] parameter is invalid. |
INT_933 | The format of the installmentOptions.schedules[amount] field is invalid or the field is not transmitted. |
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_1036 | The invoice reference already exists. |