L'intégration native vous oblige à créer une API RESTful que Google peut appeler pour créer et gérer des sessions de paiement.
Voici le flux global :
- Créer une session de paiement : l'utilisateur et, éventuellement, un agent sont dans une boucle pour ajouter des articles à la session.
- Transfert vers une UI Google : une fois que l'utilisateur a décidé de passer à la caisse, l'agent (s'il est engagé) transmet le contrôle à une UI Google (en transmettant les données de la session de paiement).
- Paiement manuel : l'utilisateur interagit désormais uniquement avec l'UI Google pour renseigner les informations sensibles de traitement et de paiement, puis envoyer la commande. L'agent n'est pas impliqué dans cette partie, ce qui garantit le déterminisme.
- Finalisation et retour : l'interface utilisateur Google affiche une page "Merci" pour confirmer la commande. L'utilisateur peut également être redirigé vers l'agent, qui a peut-être déjà été informé de l'achat effectué.
Les étapes suivantes décrivent les points de terminaison d'API que vous devrez implémenter et leurs comportements.
1. Créer une session de paiement
Ce point de terminaison permet de créer une session de paiement contenant les produits qu'un utilisateur souhaite acheter.
- Point de terminaison :
POST /checkout-sessions - Déclencheur : l'utilisateur clique sur "Acheter" pour un produit.
Demande : Google envoie les éléments de campagne et la devise.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Réponse : vous renvoyez la session initialisée avec les totaux, les taxes (initialement estimées) et les capacités de paiement. Vous devez inclure des liens vers vos conditions d'utilisation et vos règles de confidentialité, qui seront affichés sous le bouton de paiement.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [
{
"name": "dev.ucp.shopping.checkout",
"version": "2026-01-11"
},
{
"name": "dev.ucp.shopping.fulfillment",
"version": "2026-01-11"
}
]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "incomplete",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000
},
"quantity": 1,
"base_amount": 10000,
"subtotal": 10000,
"total": 10000
}
],
"totals": [
{ "type": "subtotal", "amount": 10000 }, // in cents
{ "type": "tax", "amount": 0 },
{ "type": "total", "amount": 10000 }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"config": {
"api_version": 2,
"api_version_minor": 0,
"merchant_info": {
"merchant_id": "12345678901234567890",
"merchant_name": "Example Merchant"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD"]
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"gateway_merchant_id": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
},
"links": [
{ "type": "privacy_policy", "url": "https://m.com/privacy" },
{ "type": "terms_of_service", "url": "https://m.com/terms" }
]
}
2. Obtenir une session de paiement
Ce point de terminaison permet de récupérer une session de paiement.
- Point de terminaison :
GET /checkout-sessions/{id}
Requête : Google envoie l'ID de la session de paiement. Si vous utilisez des ID mondiaux (par exemple, gid://merchant.example.com/Checkout/session_abc123), notez que l'ID dans le chemin de la requête ne sera que le dernier composant de cet ID (par exemple,
session_abc123).
Réponse : vous renvoyez l'objet de paiement complet.
3. Mettre à jour la session de paiement
Ce point de terminaison permet de mettre à jour une session de paiement. Lorsque l'adresse de livraison est modifiée, il doit recalculer et renvoyer les taxes et les options de livraison.
- Point de terminaison :
PUT /checkout-sessions/{id} - Déclencheur : l'utilisateur sélectionne ou modifie son adresse de livraison, met à jour sa sélection de livraison ou modifie ses informations de paiement.
Demande : Google envoie l'objet de paiement complet avec les informations mises à jour.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"buyer": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"selected_destination_id": "dest_1"
}
]
},
"payment": {
"selected_instrument_id": "pi_gpay_5678",
"instruments": [
{
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"rich_text_description": "Google Pay •••• 5678"
}
]
}
// ... other fields (line_items, currency, etc.)
}
Réponse : vous recalculez les taxes et les options de livraison si nécessaire, puis renvoyez l'objet de paiement complet.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
{ "type": "tax", "amount": 850 },
{ "type": "total", "amount": 11350 }
],
// ... other fields (line_items, currency, etc.)
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1"],
"selected_destination_id": "dest_1",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"total": 500
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"total": 1500
}
]
}
]
}
]
}
}
4. Finaliser une session de paiement
Ce point de terminaison permet de finaliser une session de paiement et de passer une commande. Elle doit renvoyer la session de paiement finalisée et inclure les informations de la commande. Le traitement du paiement doit commencer après la réception de cet appel.
- Point de terminaison :
POST /checkout-sessions/{id}/complete - Déclencheur : l'utilisateur clique sur "Passer la commande".
Demande : Google envoie le jeton de paiement (blob chiffré) du fournisseur (par exemple, Google Pay) et des signaux de risque concernant l'acheteur pour vous permettre de détecter vous-même les fraudes.
{
"payment_data": {
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"billing_address": {
"postal_code": "94043",
"address_country": "US"
},
"credential": {
"type": "PAYMENT_GATEWAY",
"token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
}
}
}
Réponse : vous renvoyez l'objet de paiement complet indiquant que la commande est terminée, y compris l'ID de la commande et l'URL du lien permanent vers la commande.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [...]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"order_id": "gid://merchant.example.com/Order/789",
"order_permalink_url": "https://merchant.example.com/orders/789"
}
5. Annuler une session de paiement
Ce point de terminaison annule une session de paiement.
- Point de terminaison :
POST /checkout-sessions/{id}/cancel
Requête : Google envoie l'ID de la session de paiement.
Réponse : vous renvoyez l'objet de paiement complet avec l'état mis à jour sur canceled.