Creating a WhatsApp 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 WHATSAPP.
channelOptions.whatsAppOptions	YES	A JSON object allowing to set the specific parameters for creating a WhatsApp payment order.
channelOptions.whatsAppOptions.phoneNumber	YES	Recipient's phone number.
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

/en/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44

https://api.lyra.com/api-payment/V4/Charge/CreatePaymentOrder

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

{
    "amount": 200050,
    "currency": "PEN",
    "orderId": "myOrderId-999999",    
    "channelOptions": {
      "channelType": "WHATSAPP",
      "whatsAppOptions": {
        "phoneNumber": "+51987654321"
      }
    },
    "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": "WHATSAPP",
      "whatsAppOptions": {
        "phoneNumber": "+5491112345678"
      }
    },
    "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": "WHATSAPP",
      "whatsAppOptions": {
        "phoneNumber": "+573191234567"
      }
    },
    "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": "WHATSAPP",
      "whatsAppOptions": {
    	"phoneNumber":"+5511123456789"    
      }
    },
    "paymentReceiptEmail": "sample@example.com",
    "expirationDate": "2020-04-20T20:13:26+02:00", 
    "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.whatsAppDetails.phoneNumber	Recipient's phone number with the international access code.
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.lyra.com/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": null,
        "amount": 10000,
        "currency": "EUR",
        "locale": "fr_FR",
        "strongAuthentication": "AUTO",
        "orderId": "myOrderId-1234",
        "channelDetails": {
            "channelType": "WHATSAPP",
            "mailDetails": null,
            "smsDetails": null,
            "whatsAppDetails": {
                "phoneNumber": "+3361111111",
                "_type": "V4/WhatsAppDetails"
            },
            "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": "Bonjour, voici un ordre de paiement envoyé par DEMO STORE d'un montant de 2000.50 EUR valable jusqu'au 23/04/2020. Pour confirmer, veuillez suivre le lien : https://secure.lyra.com/t/xdt0bcmo",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+00:00",
    "applicationProvider": "LYRA",
    "metadata": null,
    "_type": "V4/WebService/Response"
}

{
    "webService": "Charge/CreatePaymentOrder",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f",
        "paymentURL": "https://secure.lyra.com/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": "WHATSAPP",
            "mailDetails": null,
            "smsDetails": null,
            "whatsAppDetails": {
                "phoneNumber": "+51987654321",                
                "_type": "V4/WhatsAppDetails"
            },
            "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 sent by DEMO STORE of EUR 2,000.50 valid until 23/04/2020. To confirm, please click on the link below : https://secure.lyra.com/t/xdt0bcmo",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+00:00",
    "applicationProvider": "LYRA",
    "metadata": null,
    "_type": "V4/WebService/Response"
}


}

{
    "webService": "Charge/CreatePaymentOrder",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f",
        "paymentURL": "https://secure.lyra.com/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": null,
        "amount": 200050,
        "currency": "EUR",
        "locale": "es_ES",
        "strongAuthentication": "AUTO",
        "orderId": "myOrderId-999999",
        "channelDetails": {
            "channelType": "WHATSAPP",
            "mailDetails": null,
            "smsDetails": null,
            "whatsAppDetails": {
                "phoneNumber": "+51987654321",                
                "_type": "V4/WhatsAppDetails"
            },
            "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": "Hola, este mensaje contiene una solicitud de pago enviada por DEMO STORE por un monto de 2.000,50 ARS, válida hasta el 23/04/2020. Para confirmar el pago, haga clic en el enlace siguiente : https://secure.lyra.com/t/xdt0bcmo",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+00:00",
    "applicationProvider": "LYRA",
    "metadata": null,
    "_type": "V4/WebService/Response"
}


}

{
    "webService": "Charge/CreatePaymentOrder",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f",
        "paymentURL": "https://secure.lyra.com/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": null,
        "amount": 200050,
        "currency": "EUR",
        "locale": "es_ES",
        "strongAuthentication": "AUTO",
        "orderId": "myOrderId-999999",
        "channelDetails": {
            "channelType": "WHATSAPP",
            "mailDetails": null,
            "smsDetails": null,
            "whatsAppDetails": {
                "phoneNumber": "+573191234567",                
                "_type": "V4/WhatsAppDetails"
            },
            "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": "Hola, este mensaje contiene una solicitud de pago enviada por DEMO STORE por un monto de 2.000,50 COP, válida hasta el 23/04/2020. Para confirmar el pago, haga clic en el enlace siguiente : https://secure.lyra.com/t/xdt0bcmo",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+00:00",
    "applicationProvider": "LYRA",
    "metadata": null,
    "_type": "V4/WebService/Response"
}


}

{
    "webService": "Charge/CreatePaymentOrder",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f",
        "paymentURL": "https://secure.lyra.com/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": null,
        "amount": 200050,
        "currency": "EUR",
        "locale": "es_ES",
        "strongAuthentication": "AUTO",
        "orderId": "myOrderId-999999",
        "channelDetails": {
            "channelType": "WHATSAPP",
            "mailDetails": null,
            "smsDetails": null,
            "whatsAppDetails": {
                "phoneNumber": "+5491112345678",                
                "_type": "V4/WhatsAppDetails"
            },
            "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": "Hola, este mensaje contiene una solicitud de pago por un importe de 2.000,50 PEN, válida hasta el 23/04/2020. Para confirmar el pago, haga clic en el enlace siguiente : https://secure.lyra.com/t/xdt0bcmo",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+00:00",
    "applicationProvider": "LYRA",
    "metadata": null,
    "_type": "V4/WebService/Response"
}


}

{
    "webService": "Charge/CreatePaymentOrder",    
    "version": "V4",
    "applicationVersion": "5.5.0",
    "status": "SUCCESS",
    "answer": {
        "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f",
        "paymentURL": "https://secure.lyra.com/t/328zq5so",
        "paymentOrderStatus": "RUNNING",
        "creationDate": "2020-03-31T15:06:49+00:00",
        "updateDate": null,
        "amount": 200050,
        "currency": "EUR",
        "locale": "pt_BR",
        "strongAuthentication": "AUTO",
        "orderId": "myOrderId-999999",
        "channelDetails": {
            "channelType": "WHATSAPP",
            "mailDetails": null,
            "smsDetails": null,
            "whatsAppDetails": {
                "phoneNumber": "+5511123456789",
                "_type": "V4/WhatsAppDetails"
            },
            "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": "Caro cliente, este mensagem contém uma ordem de pagamento enviada por DEMO STORE no valor de 2000.50 BRL válida até 23/04/2020. Para confirmar o pagamento, favor clicar sobre o link seguinte : https://secure.lyra.com/t/xdt0bcmo",
        "_type": "V4/PaymentOrder"
    },
    "ticket": null,
    "serverDate": "2020-03-31T15:06:49+00:00",
    "applicationProvider": "LYRA",
    "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_837	The channelOptions.whatsAppOptions.phoneNumber parameter is missing.
INT_839	The whatsAppOptions object 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_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_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.

Categories