Creating an SMS payment order

Test the Charge/CreatePaymentOrder web service via our playground: Charge/CreatePaymentOrder.

Request for an immediate payment

PARAMETER	required	Description
channelOptions.channelType	YES	Parameter to define the channel for issuing the payment order. Must be set to SMS.
channelOptions.smsOptions	YES	A JSON object for defining the parameters specific to creating a payment order by SMS.
channelOptions.smsOptions.phoneNumber	YES	Recipient's cell phone number.
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.
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 telephone number. For example: "fr_FR", "es_ES", "en_EN", "pt_BR".
merchantComment	No	Optional comment for the user of theMerchant Back Office. It can be found from the menu :Management>Payment orders: or by displaying the order details in the Information tab of the field`Identifiant utilisateur source`, or by viewing the column`Informations 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

2 use cases are available:

Send an SMS using the "default" template defined by the payment gateway.
Send an SMS by customizing its content directly in the request.

Send an SMS based on the default template

The Merchant wishes to send a payment order using the default message of the payment gateway.

To do this, do not transmit the message field.

/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/CreatePaymentOrder

{
    "amount": 10000,
    "currency": "EUR",
    "orderId": "myOrderId-1234",
    "channelOptions": {
      "channelType": "SMS",
      "smsOptions": {
        "phoneNumber": "+33611111111"
      }
    },
}

/**
 * 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"];

?>

Send a custom SMS

The Merchant wishes to personalize the SMS message in their request.

To do this, use the message field.

Several variables are provided for customizing the message content:

value	Description
%url%	URL of the payment order. If this variable is absent, the payment link will be added automatically at the end of the message.
%amount%	Payment amount and currency.
%start_date%	Date of creation of the payment order. Allows you to indicate the beginning of the validity period of the payment order.
%end_date%	Allows to specify the end of the payment order validity period.
%shop_name%	Name of your shop as defined in the Back Office.
%reference%	Order reference.
%shop_url%	URL of your shop.
%shop_contact%	E-mail address of the "shop administrator", as defined in the Back Office.

In the response, these variables will be replaced by their value.

/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/CreatePaymentOrder

{
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",
    "channelOptions": {
      "channelType": "SMS",
      "smsOptions": {
        "phoneNumber": "0611111111",        
        "message":"Bonjour, ce message comporte un lien de paiement d'un montant de %amount% valable jusqu'au %end_date%. Pour confirmer le paiement, cliquez sur le lien suivant: %url%"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2023-04-20T20:13:26+02:00", 
    "dataCollectionForm": "false"
}

{
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "SMS",
      "smsOptions": {
        "phoneNumber": "+33611111111",        
        "message":"Dear customer, <br/>this is a payment order of %amount% valid until %end_date%.<br/>To confirm, please click on the link below: %url%"		
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "es_PE",
    "dataCollectionForm": "false"
}

{
    "amount": 200050,
    "currency": "PEN",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "SMS",
      "smsOptions": {
        "phoneNumber": "+51987654321",        
        "message":"Hola, este mensaje contiene una solicitud de pago por un importe de %amount, válida hasta el %end_date%. Para confirmar el pago, haga clic en el enlace siguiente : %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": "SMS",
      "smsOptions": {
        "phoneNumber": "+5491112345678",        
        "message":"Hola, este mensaje contiene una solicitud de pago por un importe de %amount, válida hasta el %end_date%. Para confirmar el pago, haga clic en el enlace siguiente : %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": "SMS",
      "smsOptions": {
        "phoneNumber": "+573191234567",        
        "message":"Hola, este mensaje contiene una solicitud de pago por un importe de %amount, válida hasta el %end_date%. Para confirmar el pago, haga clic en el enlace siguiente : %url%"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "es_CO",
    "dataCollectionForm": "false"
}

{
    "amount": 200050,
    "currency": "EUR",
    "orderId": "myOrderId-999999",   
    "channelOptions": {
      "channelType": "SMS",
      "smsOptions": {
        "phoneNumber": "+5511123456789",        
        "message":"Caro cliente, este mensagem contém uma ordem de pagamento do valor de %amount, válida até %end_date%. Para confirmar o pagamento, favor clicar sobre o link seguinte : %url%"
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00",
    "locale": "pt_BR",
    "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.
channelDetails.smsDetails.phoneNumber	Recipient's phone number with the international access code.
channelDetails.smsDetails.message	Body of the sent message.
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://secure.systempay.fr/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": null,
        "amount": 10000,
        "currency": "EUR",
        "locale": "en_GB",
        "strongAuthentication": "AUTO",
        "orderId": "myOrderId-1234",
        "channelDetails": {
            "channelType": "SMS",
            "mailDetails": null,
            "smsDetails": {
                "phoneNumber": "+336111111111",
                "message": "Dear customer, this is a payment order of EUR 2,000.50 valid until 23/04/2020. To confirm, please click on the link below : https://secure.systempay.fr/t/xdt0bcmo",
                "_type": "V4/SMSDetails"
            },
            "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": "Dear customer, this is a payment order of EUR 2,000.50 valid until 23/04/2020. To confirm, please click on the link below : https://secure.systempay.fr/t/xdt0bcmo",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+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_838	The channelOptions.smsOptions.phoneNumber parameter is missing.
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.
PSP_1029	Wrong configuration of the SMS account.
PSP_1030	Your SMS account balance is exceeded.
PSP_1031	The phone number is invalid.

Categories

Tags