Generating a payment link
Test the Charge/CreatePaymentOrder web service via our playground: Charge/CreatePaymentOrder.
Use cases
The Merchant wishes to generate a payment URL in order to send a commercial proposal.
With this solution, he/she can fully customize the message and add an attachment, such as a quote.
They can also retrieve the content of the message generated by the gateway in order to use it in the message that will be sent to the Buyer.
The message is sent by the Merchant.
Request for an immediate payment
Call the PCharge/CreatePaymentOrder service using the fields below:
PARAMETER | required | Description |
---|---|---|
channelOptions.channelType | No | Parameter to define the channel for sending the payment order. Can be set to URL or not sent. |
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 consisting of the language code (ISO 639-1) followed by the country code (ISO 3166 alpha-2), separated by the character "_". It allows you to define the language of the payment pages and the confirmation e-mail. If this parameter is not specified, the language of the shop 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 | 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", CHALLENGE_REQUESTED, CHALLENGE_MANDATE, NO_PREFERENCE or "AUTO". |
paymentReceiptEmail | No | The e-mail address that will be used for sending the payment ticket to the buyer. Requires the activation of the “Payment confirmation e-mail sent to the buyer” notification rule. |
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. |
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).
Sample query
Immediate payment
{ "amount": 10000, "currency": "EUR", "orderId": "myOrderId-1234", "channelOptions": { "channelType": "URL" } }
{ "amount": 200050, "currency": "PEN", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "URL" }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_PE", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "ARS", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "URL" }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_AR", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "COP", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "URL" }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_CO", "dataCollectionForm": "false" }
/** * 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 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 | Distribution channel of the payment order. |
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 | 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. |
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://sogecommerce.societegenerale.eu/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-1234", "channelDetails": { "channelType": "URL", "mailDetails": null, "smsDetails": null, "whatsAppDetails": 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": "I pay EUR 2,000.50 via secure payment before 23/04/2020 (if the link does not work, copy the URL : https://sogecommerce.societegenerale.eu/t/xdt0bcmo ).", "_type": "V4/PaymentOrder" }, "ticket": null, "serverDate": "2020-03-31T15:06:49+00:00", "applicationProvider": "SOGECOM", "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_856 | The locale parameter is invalid. |
INT_858 | The taxRate parameter is invalid. |
INT_869 | The taxAmount parameter is invalid. |
PSP_519 | Unknown currency. |
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. |