Traiter une commande avec règlement
Par défaut, une commande effectuée via l’API Paiements hébergés est un achat dans lequel l’autorisation et le règlement sont combinés dans la même transaction. Toutefois, votre modèle d’affaires peut vous obliger à autoriser d’abord une transaction, puis à la régler à une date ultérieure, par exemple une fois que vous avez expédié des marchandises. Dans ce cas, vous envoyez deux requêtes distinctes à l’API.
Traiter une commande avec autorisation uniquement
Pour traiter une demande d’autorisation uniquement, vous utilisez le point d’extrémité standard /orders, mais le corps de la requête doit contenir un ensemble extendedOptions précisant que la requête n’est que pour autorisation seulement.
POST /hosted/v1/orders
Exemple de requête
curl -X POST -H "Content-Type: application/json" \
-u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \
https://api.test.netbanx.com/hosted/v1/orders \
-d ’{
"merchantRefNum" : "ABCDE12345",
"currencyCode" : "GBP",
"totalAmount" : 1000,
"extendedOptions" : [
{
"key" : "authType",
"value" : "auth"
}]
}’
Exemples de réponse
Une requête réussie se traduira par une réponse similaire à la suivante :
{
"currencyCode" : "GBP",
"id" : "25TWPTLHRR81AIG1LF",
"link" : [
{
"rel" : "hosted_payment",
"uri" : "https://api.test.netbanx.com/hosted/v1/payment/53616c7465645f5fc96311a769ed171ce70fac1483fa7f6d9ecfb6d427c1e12c6fc573a35f13e0ea"
},
{
"rel" : "self",
"uri" : "https://jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e@api.test.netbanx.com/hosted/v1/orders/25TWPTLHRR81AIG1LF"
}
],
"merchantRefNum" : "ABCDE12345",
"mode" : "live",
"totalAmount" : 1000,
"type" : "order"
}
Votre système doit prendre en compte l’URL hosted_payment de la réponse à la commande et l’utiliser pour rediriger votre client vers la page de paiement hébergée, où il peut saisir les données de son paiement.
REMARQUE : Le client doit remplir et soumettre le formulaire de détails de paiement avant que la commande ne puisse être réglée. Vous pouvez utiliser l’un des numéros de carte de test, comme 4530910000012345, pour effectuer cette étape.
Si vous recherchez la commande, vous obtiendrez une réponse avec la structure suivante, qui indique qu’il s’agit d’une transaction avec autorisation seulement, comme l’indique la transaction authType étant auth :
{
"link" : [
{
"rel" : "hosted_payment",
"uri" : "https://api.test.netbanx.com/hosted/v1/payment/53616c7465645f5ffeb47c2287dbf903bbb4627b16929a27b8d09b37db190a0f6ce44f8ea1461be2"
},
{
"rel" : "self",
"uri" : "https://jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e@api.test.netbanx.com/hosted/v1/orders/25TWPTLHRR81AIG1LF"
}
],
"currencyCode" : "GBP",
"transaction" : {
"status" : "pending",
"lastUpdate" : "2012-05-14T15:12:18",
"authType" : "auth",
"merchantRefNum" : "ABCDE12345",
"associatedTransactions" : [],
"currencyCode" : "GBP",
"refunded" : false,
"amount" : 1000,
"paymentType" : "card",
"settled" : false
},
"totalAmount" : 1000,
"id" : "25TWPTLHRR81AIG1LF",
"merchantRefNum" : "ABCDE12345"
}
Voir notre rubrique Référence de l’API pour une liste de tous les attributs et types JSON disponibles pour l’objet de commande. Les paramètres de requête et de réponse sont énumérés.
Régler une commande avec autorisation seulement
POST /hosted/v1/orders/order_id/settlement
Une fois que vous avez fourni les biens ou les services, vous pouvez régler l’autorisation.
Pour régler une autorisation, utilisez l’identifiant de commande reçu dans la réponse de commande (25TWPTLHRR81AIG1LF dans cet exemple) et envoyez une demande de règlement au point d’extrémité décrit ci-dessous.
- Si vous omettez le paramètre amount, le plein montant de l’autorisation sera réglé.
- Si vous incluez le paramètre amount, vous pouvez spécifier le montant à régler par avec l’autorisation.
Exemple de requête
curl -X POST \
-H "Content-Type: application/json" \
-u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \
https://api.test.netbanx.com/hosted/v1/orders/25TWPTLHRR81AIG1LF/settlement \
-d ’{ "amount": 500, "merchantRefNum": "ABCDE12345" }’
Si votre demande de règlement est valide, vous recevrez une réponse avec la structure suivante, indiquant que la demande de règlement a été traitée avec succès :
Exemples de réponse
{
"currencyCode" : "GBP",
"id" : "25TWPTLHRR81AIG1LF",
"merchantRefNum" : "ABCDE12345",
"mode" : "live",
"totalAmount" : 500,
"authType" : "settlement"
}
Caractéristiques de la commande en option
Vous pouvez éventuellement ajouter les caractéristiques suivantes à une commande en utilisant les paramètres de l’objet Commande :
- Notifications par courriel au client
- Notifications par courriel au marchand
- Emplacement
Notifications par courriel au client
Les notifications par courriel au client sont entièrement localisées et personnalisées; veuillez contacter les services au marchand pour de plus amples renseignements.
Pour envoyer un courrier électronique de notification au client, transmettez le paramètre customerNotificationEmail lors de l’étape de création de la commande comme suit :
{
"customerNotificationEmail" : "jane.smythe@emailhost.com"
}
Pour éviter l’envoi d’une notification par courriel au client, envoyez le champ suppressCustomerEmail (extendedOption) avec la valeur définie sur true.
Notifications par courriel au marchand
Pour envoyer un courrier électronique de notification au marchand, transmettez le paramètre merchantNotificationEmail lors de l’étape de création de la commande comme suit :
{
"merchantNotificationEmail" : "merchant@emailhost.com"
}
Emplacement
L’API Paiements hébergés prend en charge la localisation des pages et des courriels contenant des informations sur les paiements et les reçus. Le système tente d’établir la meilleure correspondance possible avec les informations contenues dans le paramètre locale.
REMARQUE : Si le paramètre locale n’est pas transmis, ou si un code ISO 639-1 non pris en charge est envoyé à l’API, la valeur par défaut dans la configuration de l’intégration du marchand est utilisée.
Pour ajouter des informations sur la l’emplacement à la commande, transmettez le paramètre locale comme suit :
{
"locale" : "en_GB"
}
Les valeurs du paramètre locale suivantes sont prises en charge.
- en_US
- en_GB
- fr_FR
- fr_CA