Modifier un ordre de paiement
Testez le web service Charge/PaymentOrder/Update depuis notre playground: Charge/PaymentOrder/Update.
Cas d'utilisation
Le marchand souhaite modifier le contenu d'un ordre de paiement (montant, message, etc..).
Le Web Service Charge/PaymentOrder/Update permet de modifier uniquement les ordres de paiement créés avec le Web Service Charge/CreatePaymentOrder.
Seuls les ordres de paiement en cours (statut RUNNING) peuvent faire l'objet d'une modification. Le canal de diffusion ne peut pas être modifié.
Requête
| Paramètre | Requis | Description |
|---|---|---|
| paymentOrderId | Oui | ID de l'ordre de paiement à modifier. |
| channelOptions.channelType | Oui | Paramètre permettant de définir le canal d'émission de l'ordre de paiement. |
| channelOptions.mailOptions | Non | Objet json permettant de définir les paramètres spécifiques à la création d'un ordre de paiement par mail. Requis si l'ordre de paiement à modifier est de type MAIL. |
| channelOptions.mailOptions.recipient | Non | Adresse e-mail du destinataire. Requis si l'ordre de paiement à modifier est de type MAIL. |
| channelOptions.mailOptions.bcc | Non | Liste des destinataires supplémentaires. Ces destinataires ne sont pas visibles par le destinataire principal (recipient). Utilisez le point-virgule “;” comme séparateur entre chaque adresse. |
| channelOptions.mailOptions.subject | Non | Permet de personnaliser l’objet de l’e-mail. Ce paramètre est obligatoire sauf si vous spécifiez un nom de template valide dans le paramètre channelOptions.mailOptions.template. |
| channelOptions.mailOptions.body | Non | Permet de personnaliser le corps de l’e-mail envoyé. Si le paramètre est laissé vide, le template par défaut sera appliqué. |
| channelOptions.mailOptions.template | Non | Nom du modèle à utiliser pour générer l’e-mail. Il est nécessaire que le modèle existe dans le Back Office pour que cela fonctionne.Chaque modèle d’e-mail est associé à une langue (ou locale). Pour utiliser un modèle vous devez vous assurer de transmettre la bonne langue dans le paramètre locale. Si le modèle n’est pas trouvé une erreur sera retournée. Si vous avez défini une valeur dans les paramètres subject et body, elles seront ignorées et remplacées par celles du template. |
| channelOptions.smsOptions | Non | Objet json permettant de définir les paramètres spécifiques à la création d'un ordre de paiement par sms. Requis si l'ordre de paiement à modifier est de type SMS. |
| channelOptions.smsOptions.phoneNumber | Non | Numéro de téléphone mobile du destinataire. Requis si l'ordre de paiement à modifier est de type SMS. |
| channelOptions.smsOptions.message | Non | Permet de personnaliser le corps du messsage envoyé. Si le paramètre est laissé vide, le message par défaut sera appliqué. |
| channelOptions.whatsAppOptions | Non | Objet json permettant de définir les paramètres spécifiques à la création d'un ordre de paiement WhatsApp. Requis si l'ordre de paiement à modifier est de type WHATSAPP. |
| channelOptions.whatsAppOptions.phoneNumber | Non | Numéro de téléphone du destinataire. Requis si l'ordre de paiement à modifier est de type WHATSAPP. |
| expirationDate | Non | Date de validité de l'ordre au format ISO-8601. Ne peut pas être antérieure à la date courante et ne peut pas dépasser 90 jours. Si ce paramètre n'est pas envoyé, la valeur appliquée sera celle de la boutique. Ex : 2021-10-05T21:59:59+00:00 |
| locale | Non | Code représentant le nom de la langue et composé du code de la langue (ISO 639-1) suivi du code du pays (ISO 3166 alpha-2), séparés par le caractère "_". Permet de définir la langue des pages de paiement et du mail de confirmation. Si ce paramètre n'est pas renseigné, la langue sera déduite à partir du numéro de téléphone du destinataire. |
| merchantComment | Non | Commentaire facultatif destiné à l'utilisateur du Identifiant utilisateur source, soit en consultant la colonne Informations utilisateur. |
| amount | Oui | Montant à payer, exprimé dans sa plus petite unité monétaire (le centime pour l'euro). |
| currency | Oui | Devise du paiement. Code ISO 4217 alpha-3. Ex: "EUR" pour l'euro. |
| orderId | Non | Référence de la commande. |
| taxAmount | Non | Montant des taxes pour l’ensemble de la commande, exprimé dans sa plus petite unité monétaire (le centime pour l'euro). |
| taxRate | Non | Taux de taxe appliqué sur l’ensemble de la commande. La valeur doit être le pourcentage à appliquer (21 pour 21%). |
| transactionOptions.cardOptions.manualValidation | Non | Permet de préciser si la validation de la transaction est manuelle. Valeurs possibles: "YES" ou "NO". |
| transactionOptions.cardOptions.captureDelay | Non | Indique le délai, en nombre de jours, avant remise en banque. |
| strongAuthentication | Non | Permet d’activer ou de désactiver l’authentification forte lors du paiement. Valeurs possibles : "ENABLED", "DISABLED" ou "AUTO". |
| paymentReceiptEmail | Non | Adresse e-mail qui sera utilisée pour l'envoi du ticket de paiement à l'acheteur. |
| dataCollectionForm | Non | Utilisation du formulaire de collecte de données. Valeurs possibles: "true" ou "false". |
| customer | Non | Objet contenant les données de l'acheteur. |
| formAction | Non | Permet de définir le type de comportement souhaité lors de la création de la transaction. |
| paymentMethodToken | Non | Alias du moyen de paiement à utiliser pour le paiement. |
| metadata | Non | Valeurs personnalisées rattachées à la transaction, au format json. |
Exemple requête
/doc/fr-FR/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/PaymentOrder/Update
{
"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"];
?>Réponse
L'objet answser contiendra les paramètres ci-dessous:
| Paramètre | Description |
|---|---|
| paymentOrderId | ID de l'ordre de paiement. |
| paymentURL | URL de paiement. |
| paymentOrderStatus | Statut de l'ordre de paiement. |
| creationDate | Date et heure de création de l'ordre de paiement. |
| updateDate | Date et heure de modification de l'ordre de paiement. |
| channelDetails.channelType | Canal de transmission de l'ordre de paiement. |
| channelDetails.mailDetails.recipient | Adresse e-mail du destinataire. Présent uniquement si channelDetails.channelType est valorisé à MAIL. |
| channelDetails.mailDetails.subject | Objet de l'e-mail envoyé. Présent uniquement si channelDetails.channelType est valorisé à MAIL. |
| channelDetails.mailDetails.body | Corps de l'e-mail envoyé. Présent uniquement si channelDetails.channelType est valorisé à MAIL. |
| channelDetails.mailDetails.template | Nom du template utilisé. Présent uniquement si channelDetails.channelType est valorisé à MAIL. |
| channelDetails.mailDetails.bcc | Liste des destinataires en copie cachée. Présent uniquement si channelDetails.channelType est valorisé à MAIL. |
| channelDetails.smsDetails.phoneNumber | Numéro de téléphone du destinataire avec le préfixe internationnal. Présent uniquement si channelDetails.channelType est valorisé à SMS. |
| channelDetails.smsDetails.message | Corps du message envoyé. Présent uniquement si channelDetails.channelType est valorisé à SMS. |
| channelDetails.whatsAppDetails.phoneNumber | Numéro de téléphone du destinataire avec le préfixe internationnal. Présent uniquement si channelDetails.channelType est valorisé à WHATSAPP. |
| message | Message comportant le lien de paiement, rédigé dans la locale. |
| amount | Montant à payer, exprimé dans sa plus petite unité monétaire. |
| currency | Devise du paiement. Code ISO 4217 alpha-3. |
| locale | Code représentant le nom de la langue et composé du code de la langue (ISO 639-1) suivi du code du pays (ISO 3166 alpha-2), séparés par le caractère "_". |
| strongAuthentication | Préférence du marchand concernant l'authentification forte. |
| orderId | Référence de la commande. |
| paymentReceiptEmail | Adresse email qui sera utilisée pour l'envoi du ticket de paiement à l'acheteur. |
| taxAmount | Montant des taxes pour l’ensemble de la commande, exprimé dans sa plus petite unité monétaire. |
| taxRate | Taux de taxe appliqué sur l’ensemble de la commande. |
| expirationDate | Date de validité de l'ordre au format ISO-8601. |
| dataCollectionForm | Utilisation du formulaire de collecte de données. |
| merchantComment | Commentaire facultatif. |
| transactionDetails.cardDetails.manualValidation | Mode de validation de la transaction. |
| transactionDetails.cardDetails.captureDelay | Délai de capture. |
| customer | Non |
| formAction | Non |
| paymentMethodToken | Non |
| metadata | Non |
Exemple de réponse
{
"webService": "Charge/PaymentOrder/Update",
"version": "V4",
"applicationVersion": "5.5.0",
"status": "SUCCESS",
"answer": {
"paymentOrderId": "d63e7f507a6f4dfa86cb40a833ecfd85",
"paymentURL": "https://secure.systempay.fr/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.systempay.fr/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.systempay.fr/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": "NPS",
"metadata": null,
"_type": "V4/WebService/Response"
}
}Gestion des erreurs
Le Web Service Charge/createPaymentOrder retournera une erreur dans les cas suivants:
| Code | Description |
|---|---|
| INT_009 | Le format du champ amount est invalide ou le champ n'est pas transmis. |
| INT_010 | Le format du champ currency est invalide ou le champ n'est pas transmis. |
| INT_050 | Le paramètre strongAuthentication est invalide. |
| INT_836 | L'objet smsOptions est manquant. |
| INT_837 | Le paramètre channelOptions.whatsAppOptions.phoneNumber est manquant. |
| INT_838 | Le paramètre channelOptions.smsOptions.phoneNumber est manquant. |
| INT_839 | L'objet whatsAppOptions est manquant. |
| INT_841 | L'objet mailOptions est manquant. |
| INT_850 | Le paramètre channelOptions.mailOptions.recipient est manquant. |
| INT_856 | Le paramètre locale est invalide. |
| INT_858 | Le paramètre taxRate est invalide. |
| INT_869 | Le paramètre taxAmount est invalide. |
| INT_902 | Le format du champ paymentOrderId est invalide ou le champ n'est pas transmis. |
| PSP_519 | Devise inconnue. |
| PSP_606 | Devise non supportée par le contrat. |
| PSP_1000 | L'ordre de paiement n'existe pas. |
| PSP_1001 | Impossible de joindre la passerelle WhatsApp. |
| PSP_1002 | Le numéro de téléphone du destinataire n’est pas associé à un compte WhatsApp. |
| PSP_1003 | Configuration WhatsApp absente. |
| PSP_1004 | Modèle WhatsApp non disponible pour la locale demandée. |
| PSP_1005 | Modification impossible sur un ordre de paiement payé. |
| PSP_1006 | Modification impossible sur un ordre de paiement expiré. |
| PSP_1007 | La date d'expiration de l'ordre de paiement ne peut etre antérieure à la date courante ni excédée 90 jours. |
| PSP_1011 | Le mode (TEST ou PRODUCTION) de l'ordre de paiement ne correspond pas à celui de la requête. |
| PSP_1015 | Aucun formulaire de collecte de données pour cette boutique. |
| PSP_1017 | Le canal de diffusion ne peut pas être modifié. |
| PSP_1018 | Le formulaire de collecte de données ne peut être utilisé pour la devise demandée. |
| PSP_1022 | Le template spécifié dans la requête n'existe pas pour la locale demandée. |