Ce guide fournit la documentation de référence technique de l'API et les schémas de charge utile nécessaires pour la version 2026-01-23 du paiement natif Universal Commerce Protocol (UCP).
Avant de créer vos points de terminaison, assurez-vous d'avoir consulté la présentation du paiement natif pour comprendre le processus de paiement global, les exigences d'authentification et les outils pour les développeurs.
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 maintenant" sur un produit ou sur "Paiement sur Google" dans le panier.
Requête : Google envoie les éléments de la commande et des informations d'adresse limitées sur l'acheteur, y compris la ville, l'État et le code postal.
// Request Example: Create checkout with multiple items.
{
"line_items": [
{
"item": {
// Must match ID in product feed
"id": "product_12345"
},
"quantity": 1
},
{
"item": {
// Must match ID in product feed
"id": "product_67890"
},
"quantity": 1
}
],
"context": {
"language": "en"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"line_item_ids": [
"line_1",
"line_2"
],
"destinations": [
{
"id": "addr_1",
"address_locality": "Sunnyvale",
"address_region": "CA",
"postal_code": "94089",
"address_country": "US"
}
],
"selected_destination_id": "addr_1"
}
]
}
}
Réponse : vous renvoyez la session initialisée avec les totaux, les taxes (estimées initialement) et les fonctionnalités de paiement.
// Response Example: Initialize Session with multiple items.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
"dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "extends": "dev.ucp.shopping.checkout" } ]
},
"payment_handlers": {
"com.google.pay": [
{
"id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"version": "2026-01-23",
"spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
"schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
"config": {
"api_version": 2,
"api_version_minor": 0,
"environment": "TEST",
"merchant_info": {
"merchant_name": "Example Merchant",
"merchant_id": "KWMZPRLQFTYNXSDB",
"merchant_origin": "checkout.merchant.com"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
"allowed_card_networks": [
"AMEX",
"DISCOVER",
"JCB",
"MASTERCARD",
"VISA"
],
"billing_address_required": true,
"billing_address_parameters": {
"format": "FULL",
"phone_number_required": true
}
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "example",
"gatewayMerchantId": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
}
},
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "incomplete",
"messages": [
{
"type": "error",
"code": "missing_buyer_info",
"path": "$.buyer",
"content_type": "plain",
"content": "Buyer information is required for checkout",
"severity": "recoverable"
},
{
"type": "error",
"code": "missing_fulfillment_info",
"path": "$.fulfillment.methods[0].destinations[0]",
"content_type": "plain",
"content": "Shipping address is incomplete",
"severity": "recoverable"
}
],
"currency": "USD",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000,
"image_url": "https://merchant.example.com/images/product_12345.png"
},
"quantity": 1,
"totals": [
{
"type": "subtotal",
"amount": 10000
},
{
"type": "total",
"amount": 10000
}
]
},
{
"id": "line_2",
"item": {
"id": "product_67890",
"title": "T-Shirt",
"price": 2500,
"image_url": "https://merchant.example.com/images/product_67890.png"
},
"quantity": 1,
"totals": [
{
"type": "subtotal",
"amount": 2500
},
{
"type": "total",
"amount": 2500
}
]
}
],
"totals": [
{
"type": "subtotal",
"display_text": "Subtotal", // Tax-inclusive markets: Set to "Subtotal (including taxes)".
"amount": 12500 // Tax-inclusive markets: Amount must include tax.
},
{
"type": "fulfillment",
"display_text": "Ground Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
"amount": 500
},
{
"type": "tax", // Tax-inclusive markets: Omit this entry.
"display_text": "Estimated Tax",
"amount": 100
},
{
"type": "total",
"amount": 13100
}
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": [
"line_1",
"line_2"
],
"destinations": [
{
"id": "addr_1",
"address_locality": "Sunnyvale",
"address_region": "CA",
"postal_code": "94089",
"address_country": "US"
}
],
"selected_destination_id": "addr_1",
"groups": [
{
"id": "group_1",
"line_item_ids": [
"line_1",
"line_2"
],
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
"totals": [ {"type": "total", "amount": 500} ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
"totals": [ {"type": "total", "amount": 1500} ]
}
],
"selected_option_id": "ship_ground"
}
]
}
]
},
"links": [
{
"type": "terms_of_service",
"url": "https://m.com/terms",
"title": "Terms of Service"
},
{
"type": "privacy_policy",
"url": "https://m.com/privacy",
"title": "Privacy Policy"
}
]
}
Tarification toutes taxes comprises
Pour les marchés où les taxes sont incluses dans le sous-total affiché plutôt que détaillée séparément, votre implémentation doit respecter les exigences suivantes lorsque vous fournissez des données de session de paiement :
- Inclure les taxes dans le sous-total : le champ
amountde l'entréesubtotaldoit inclure toutes les taxes applicables. - Omettre les entrées fiscales distinctes : n'incluez pas d'objet dédié avec
type: "tax"dans le tableautotals. - Fournir un texte à afficher personnalisé : vous devez inclure un attribut
display_textdans l'objet sous-total qui indique explicitement que les taxes sont incluses, par exemple"Subtotal (including taxes)". Vous devez également inclure un attributdisplay_textpour les entrées de traitement (par exemple,"Shipping").
Exemple : Tableau des totaux incluant les taxes
L'exemple suivant illustre un tableau totals pour un marchand sur un marché où les taxes sont incluses :
"totals": [
{
"type": "subtotal",
"display_text": "Subtotal (including taxes)",
"amount": 12500
},
{
"type": "fulfillment",
"display_text": "Shipping",
"amount": 399
},
{
"type": "total",
"display_text": "Total",
"amount": 12899
}
]
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 identifiants globaux (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 identifiant (par exemple, session_abc123).
Réponse : vous renvoyez l'objet de paiement complet. Pour une session à plusieurs articles créée sous la version 2026-01-23 ou ultérieure, le tableau line_items contiendra plusieurs entrées d'articles.
Mettre à jour la session de paiement
Ce point de terminaison permet de mettre à jour une session de paiement. Lorsque l'adresse de livraison est mise à jour, il doit recalculer et renvoyer les taxes et les options de livraison.
- Point de terminaison :
PUT /checkout-sessions/{id}
Mettre à jour l'adresse de livraison
- Déclencheur : l'utilisateur sélectionne ou modifie son adresse de livraison.
Requête : Google met à jour l'adresse de traitement lorsque l'utilisateur modifie son adresse de livraison.
// Request Example: Update shipping address with multiple items.
{
"line_items": [
{
// line_items id from Create Checkout response
"id": "line_1",
"item": {
"id": "product_12345"
},
"quantity": 1
},
{
// line_items id from Create Checkout response
"id": "line_2",
"item": {
"id": "product_67890"
},
"quantity": 1
}
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": [
"line_1",
"line_2"
],
"destinations": [
{
"id": "addr_1",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US"
}
],
"selected_destination_id": "addr_1",
"groups": [
{
"id": "group_1",
"selected_option_id": "ship_ground"
}
]
}
]
}
}
Réponse : vous recalculez les taxes et les options de livraison si nécessaire, puis vous renvoyez l'objet de paiement complet.
// Response Example: Updated session with new address for multiple items.
{
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"currency": "USD",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000,
"image_url": "https://merchant.example.com/images/product_12345.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "total", "amount": 10000 }
]
},
{
"id": "line_2",
"item": {
"id": "product_67890",
"title": "T-Shirt",
"price": 2500,
"image_url": "https://merchant.example.com/images/product_67890.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 2500 },
{ "type": "total", "amount": 2500 }
]
}
],
"totals": [
{ "type": "subtotal", "amount": 12500 },
// Shipping cost might change based on new address
{ "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
// Tax will likely change based on new address
{ "type": "tax", "amount": 1120 },
{ "type": "total", "amount": 14220 }
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1", "line_2"],
"selected_destination_id": "addr_1",
"destinations": [
{
"id": "addr_1",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1", "line_2"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 600 } ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 1600 } ]
}
]
}
]
}
]
}
// ... other fields like ucp, status, messages, links
}
Hydratation de l'objet de paiement complet
Requête : Google envoie l'objet de paiement complet avec les informations mises à jour (y compris l'adresse de traitement complète et les coordonnées de l'acheteur) lorsque l'acheteur clique sur "Payer avec GPay".
// Request Example: full checkout object hydration for multiple items.
{
"buyer": {
"first_name": "John",
"last_name": "Buyer",
"email": "johnbuyer@example.com",
"phone_number": "+18888888888"
},
"line_items": [
{
"id": "line_1",
"item": { "id": "product_12345" },
"quantity": 1
},
{
"id": "line_2",
"item": { "id": "product_67890" },
"quantity": 1
}
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1", "line_2"],
"selected_destination_id": "addr_1",
"destinations": [
{
"id": "addr_1",
"first_name": "Alice",
"last_name": "Receiver",
"street_address": "1600 Amphitheatre Pkwy",
"extended_address": "Suite #60",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US",
"phone_number": "+18888888888"
}
],
"groups": [
{
"id": "group_1",
"selected_option_id": "ship_ground"
}
]
}
]
}
}
Réponse : vous recalculez les taxes et les options de livraison si nécessaire, puis vous renvoyez l'objet de paiement complet.
// Response Example: Session after full hydration with multiple items.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
"dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "extends": "dev.ucp.shopping.checkout" } ]
},
"payment_handlers": {
"com.google.pay": [
{
"id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"version": "2026-01-23",
"spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
"schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
"config": {
"api_version": 2,
"api_version_minor": 0,
"environment": "TEST",
"merchant_info": {
"merchant_name": "Example Merchant",
"merchant_id": "KWMZPRLQFTYNXSDB",
"merchant_origin": "checkout.merchant.com"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
"allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
"billing_address_required": true,
"billing_address_parameters": {
"format": "FULL",
"phone_number_required": true
}
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "example",
"gatewayMerchantId": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
}
},
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "ready_for_complete",
"currency": "USD",
"buyer": {
"first_name": "John",
"last_name": "Buyer",
"email": "johnbuyer@example.com",
"phone_number": "+18888888888"
},
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000,
"image_url": "https://merchant.example.com/images/product_12345.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "total", "amount": 10000 }
]
},
{
"id": "line_2",
"item": {
"id": "product_67890",
"title": "T-Shirt",
"price": 2500,
"image_url": "https://merchant.example.com/images/product_67890.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 2500 },
{ "type": "total", "amount": 2500 }
]
}
],
"totals": [
{ "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
{ "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
{ "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
{ "type": "total", "display_text": "Total", "amount": 14220 }
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1", "line_2"],
"selected_destination_id": "addr_1",
"destinations": [
{
"id": "addr_1",
"first_name": "Alice",
"last_name": "Receiver",
"street_address": "1600 Amphitheatre Pkwy",
"extended_address": "Suite #60",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US",
"phone_number": "+18888888888"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1", "line_2"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 600 } ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 1600 } ]
}
]
}
]
}
]
},
"links": [
{
"type": "terms_of_service",
"url": "https://m.com/terms",
"title": "Terms of Service"
},
{
"type": "privacy_policy",
"url": "https://m.com/privacy",
"title": "Privacy Policy"
}
]
}
Finaliser la session de paiement
Ce point de terminaison permet de finaliser une session de paiement et de passer une commande. Il doit renvoyer la session de paiement terminée et inclure les informations de 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 "Payer avec GPay" et Google reçoit une réponse positive de la mise à jour de l'objet de paiement complet (hydraté).
Requête : Google envoie le mode de paiement sélectionné à partir du gestionnaire de paiement, y compris les identifiants (par exemple, les données de tokenisation Google Pay) et les signaux de risque concernant l'acheteur, afin que vous puissiez effectuer votre propre détection des fraudes. Le contenu du jeton dépend de votre fournisseur de services de paiement.
{
"payment": {
"instruments": [
{
"billing_address": {
"first_name": "John",
"last_name": "Buyer",
"street_address": "100 Main St",
"extended_address": "Apt 4B",
"address_locality": "San Francisco",
"address_region": "CA",
"postal_code": "94105",
"address_country": "US",
"phone_number": "+18888888888"
},
"credential": {
"token": "examplePaymentMethodToken",
"type": "PAYMENT_GATEWAY"
},
"display": {
"brand": "VISA",
"description": "Visa •••• 1234",
"last_digits": "1234"
},
"handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
"selected": true,
"type": "card"
}
]
},
"signals": {
"com.google.authentication_triggered": "",
"com.google.authorization_processed_with_3ds": "",
"com.google.avs_full_result": "",
"com.google.cvv_result": "",
"com.google.ip_address": "203.0.113.1",
"dev.ucp.buyer_id": "ec46fedc6aad89d3660a50a61d00b4908fd160ecf5dda6d49ed41a605c5b180a",
"dev.ucp.buyer_ip": "203.0.113.1"
}
}
Si vous avez besoin d'informations obligatoires pour finaliser le paiement qui n'ont pas été fournies lors de la session de paiement, vous pouvez empêcher la finalisation de la transaction et demander ces informations en renvoyant un état incomplet dans la réponse.
Si Google peut recueillir les informations manquantes à l'aide de champs définis par l'UCP (par exemple, l'adresse e-mail de l'acheteur), définissez status sur incomplete et incluez un ou plusieurs messages dans le tableau messages avec severity défini sur recoverable pour indiquer les informations manquantes.
{
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "incomplete",
"messages": [
{
"type": "error",
"code": "missing_buyer_info",
"severity": "recoverable",
"content": "Buyer email is required"
},
{
"type": "error",
"code": "missing_fulfillment_info",
"severity": "recoverable",
"content": "Select delivery window for your purchase"
}
]
}
Voici la marche à suivre dès que vous recevez un mode de paiement Google Pay :
- Valider le gestionnaire : vérifiez que
handler_idcorrespond au gestionnaire de paiement Google Pay défini dans votre configuration. - Extraire le jeton : récupérez le jeton de mode de paiement généré à partir de
payment.instruments[0].credential.token. - Traiter le paiement : utilisez le jeton et les détails de la transaction pour finaliser le paiement. Pour obtenir des informations détaillées sur les spécifications et la gestion de la tokenisation, consultez la documentation de l'API Google Pay.
Réponse : si la transaction peut être finalisée et que vous avez traité le paiement, renvoyez l'objet de paiement complet indiquant que la commande est terminée, en incluant le mode de paiement confirmé (en renvoyant les métadonnées du mode de paiement et l'adresse de facturation, sans le jeton credential sensible ni signals), l'ID de la commande ainsi que l'URL du lien permanent vers celle-ci.
{
"ucp": {
"version": "2026-01-23",
"capabilities": [...]
},
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"payment": {
"instruments": [
{
"id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
"handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"type": "card",
"selected": true,
"display": {
"brand": "VISA",
"description": "Visa •••• 1234",
"last_digits": "1234"
},
"billing_address": {
"first_name": "John",
"last_name": "Buyer",
"street_address": "100 Main St",
"extended_address": "Apt 4B",
"address_locality": "San Francisco",
"address_region": "CA",
"postal_code": "94105",
"address_country": "US",
"phone_number": "+18888888888"
}
}
]
},
"order": {
"id": "ORD1773956535.2727807",
// Example customer-facing order number
"label": "#100",
"permalink_url": "https://merchant.example.com/orders/789"
}
}
Annuler la 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.
Gestion des erreurs
Pour obtenir des instructions complètes sur la mise en forme des messages d'erreur et sur la distinction entre les erreurs de protocole et de logique métier, consultez la présentation des codes d'erreur.
Erreur irrécupérable
Pour la version 2026-01-23, si une erreur de logique métier irrécupérable empêche la création de la session de paiement (par exemple, si tous les articles sont non disponibles), renvoyez un code HTTP 200 OK.
Dans la version 2026-01-23, vous devez signaler l'échec définitif en omettant l'ID de session de paiement et en spécifiant "severity": "unrecoverable" dans le tableau messages. Cela indique à Google que la requête était valide, mais qu'une règle de gestion a bloqué la création de la session.
HTTP/1.1 200 OK
Content-Type: application/json
{
"ucp": {
"version": "2026-01-23"
},
"messages": [
{
"type": "error",
"code": "out_of_stock",
"content": "All requested items are currently out of stock",
"severity": "unrecoverable"
}
],
"continue_url": "https://merchant.com/"
}