Utilisez des postes de paiement pour des paiements flexibles

Découvrez comment utiliser les postes de paiement avec des paiements complexes, tels que les paiements multicaptures et surcaptures.

Vous pouvez utiliser des postes de paiement pour les paiements complexes tels que les paiements multicaptures et surcaptures.

Multicapture

Vous pouvez utiliser des postes de paiement lors de multicaptures.

Remarque

La multicapture n’est pas prise en charge par Klarna ou PayPal.

Créer et confirmer un PaymentIntent non capturé

Remarque

Par défaut, la réponse de l’API n’inclut pas les postes. Pour retourner des postes, expand amount_details.line_items.

Spécifiez capture_method comme manual lors de la création du PaymentIntent et utilisez le paramètre if_available pour demander la multicapture pour ce paiement. Le PaymentIntent créé permet des captures multiples si le moyen de paiement le permet.

Dans la réponse, le champ amount_details contient les postes spécifiés dans le PaymentIntent.

{
  "amount": 4600,
  "amount_capturable": 4600,
  "amount_received": 0,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 200,
    "tax": {
      "total_tax_amount": 400
    },
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 400
    },
    "line_items": [
      {
        "product_code": "SKU001",
        "product_name": "Product 001",
        "unit_cost": 2000,
        "quantity": 1,
        "unit_of_measure": "feet",
        "payment_method_options": {
          "card": {
            "commodity_code": "123123"
          }
        }
      },
      {
        "product_code": "SKU002",
        "product_name": "Product 002",
        "unit_cost": 2000,
        "quantity": 1,
        "unit_of_measure": "gallons",
        "payment_method_options": {
          "card": {
            "commodity_code": "123123"
          }
        }
      }
    ]
  }
  ...
}

Capturer le PaymentIntent

Vous pouvez ajouter amount_details lors de la première capture même s’ils n’ont pas été spécifiés lors de la création.
Si vous avez fourni amount_details lors de la création, vous devez soit passer amount_details, soit les désactiver lors de la première capture.

Les mêmes règles s’appliquent à amount_details[line_items] : vous pouvez les ajouter lors de la première capture s’ils n’ont pas été spécifiés lors de la création, mais vous devez les inclure ou les désactiver explicitement s’ils étaient présents lors de la création.

Dans la réponse, le champ amount_details contient les postes spécifiés lors de la première capture.

{
  "amount": 4600,
  "amount_capturable": 2300,
  "amount_received": 2300,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 100,
    "tax": {
      "total_tax_amount": 200
    },
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 200
    },
    "line_items": {
      "object": "list",
      "url": "/v1/payment_intents/pi_xxxxxxxx/amount_details_line_items",
      "has_more": false,
      "data": [
        {
          "_id": "li_123",
          "product_code": "SKU001",
          "product_name": "Product 001",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "feet",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        }
      ]
    }
  },
  "status": "requires_capture"
  ...
}

Le PaymentIntent reste dans l’état requires_capture. À ce stade :

Continuez à capturer le PaymentIntent plusieurs fois jusqu’à ce que le montant total du PaymentIntent soit atteint.
Faites passer le PaymentIntent à l’état succeeded en réglant final_capture sur true, ou en effectuant une capture sans le paramètre final_capture (parce que final_capture est réglé par défaut sur true).

Si les captures précédentes incluaient amount_details ou amount_details[line_items], vous devez continuer à les inclure dans les captures suivantes.
Si les captures précédentes n’incluaient pas ces champs, vous ne pouvez pas les ajouter dans les captures ultérieures.

Dans la réponse, le champ amount_details contient les lignes des deux premières captures, selon les règles suivantes :

discount_amount, tax.total_tax_amount et shipping.amount sont additionnés sur l’ensemble des captures.
shipping.from_postal_code et shipping.to_postal_code peuvent être omis dans les captures, mais s’ils sont fournis, vous ne devez pas les modifier d’une capture à l’autre.
les line_items seront agrégés pour l’ensemble des captures.

{
  "amount": 4600,
  "amount_capturable": 0,
  "amount_received": 4600,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 200,
    "tax": {
      "total_tax_amount": 400
    },
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 400
    },
    "line_items": {
      "object": "list",
      "url": "/v1/payment_intents/pi_xxxxxxxx/amount_details_line_items",
      "has_more": false,
      "data": [
        {
          "_id": "li_123",
          "product_code": "SKU001",
          "product_name": "Product 001",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "feet",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        },
        {
          "_id": "li_234",
          "product_code": "SKU002",
          "product_name": "Product 002",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "gallons",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        }
      ]
    }
  },
  "status": "succeeded"
  ...
}

Surcapture

Vous pouvez utiliser des postes de paiement lors de surcaptures.

Créer et confirmer un PaymentIntent non capturé

Remarque

Par défaut, la réponse de l’API n’inclut pas les postes. Pour retourner des postes, expand amount_details.line_items.

Spécifiez le paramètre capture_method comme manual lors de la création du PaymentIntent et utilisez le paramètre if_available pour demander une surcapture pour ce paiement. Le PaymentIntent créé autorise la surcapture si le moyen de paiement le permet.

Dans la réponse, le champ amount_details contient les postes spécifiés dans le PaymentIntent.

{
  "amount": 4600,
  "amount_capturable": 4600,
  "amount_received": 0,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 200,
    "tax": {
      "total_tax_amount": 400
    },
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 400
    },
    "line_items": {
      "object": "list",
      "url": "/v1/payment_intents/pi_xxxxxxxx/amount_details_line_items",
      "has_more": false,
      "data": [
        {
          "_id": "li_345",
          "product_code": "SKU001",
          "product_name": "Product 001",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "feet",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        },
        {
          "_id": "li_456",
          "product_code": "SKU002",
          "product_name": "Product 002",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "gallons",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        }
      ]
    }
  }
  ...
}

Capturer le PaymentIntent

Pour capturer un montant supérieur au montant actuellement autorisé sur un PaymentIntent, utilisez l’endpoint de capture et indiquez un amount_to_capture jusqu’au maximum_amount_capturable.

Transmettez un hachage amount_details mis à jour qui correspond au montant de la capture lors de la capture.

Dans la réponse, le champ amount_details contient les postes spécifiés lors de la capture.

{
  "amount": 5000,
  "amount_capturable": 0,
  "amount_received": 5000,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 200,
    "tax": {
      "total_tax_amount": 600
    },
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 600
    },
    "line_items": {
      "object": "list",
      "url": "/v1/payment_intents/pi_xxxxxxxx/amount_details_line_items",
      "has_more": false,
      "data": [
        {
          "_id": "li_567",
          "product_code": "SKU001",
          "product_name": "Product 001",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "feet",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        },
        {
          "_id": "li_678",
          "product_code": "SKU002",
          "product_name": "Product 002",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "gallons",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        }
      ]
    }
  },
  "status": "succeeded"
  ...
}

Autorisation complémentaire

Vous pouvez utiliser des postes de paiement pendant l’autorisation complémentaire pour autoriser des montants supplémentaires sur un PaymentIntent après l’autorisation initiale.

Créer et confirmer un PaymentIntent non capturé

Remarque

Par défaut, la réponse de l’API n’inclut pas les postes. Pour retourner des postes, expand amount_details.line_items.

Spécifiez le paramètre capture_method comme manual lors de la création du PaymentIntent et utilisez le paramètre if_available pour requérir une autorisation complémentaire pour ce paiement. Le PaymentIntent créé accepte l’autorisation complémentaire si le moyen de paiement le prend en charge.

Dans la réponse, le champ amount_details contient les postes spécifiés dans le PaymentIntent.

{
  "amount": 4600,
  "amount_capturable": 4600,
  "amount_received": 0,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 200,
    "tax": {
      "total_tax_amount": 400
    },
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 400
    },
    "line_items": {
      "object": "list",
      "url": "/v1/payment_intents/pi_xxxxxxxx/amount_details_line_items",
      "has_more": false,
      "data": [
        {
          "_id": "li_789",
          "product_code": "SKU001",
          "product_name": "Product 001",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "feet",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        },
        {
          "_id": "li_890",
          "product_code": "SKU002",
          "product_name": "Product 002",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "gallons",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        }
      ]
    }
  }
  ...
}

Incrémenter l’autorisation

Pour autoriser des montants supplémentaires sur un PaymentIntent au-delà du montant initialement autorisé, utilisez l’endpoint increment_authorization et fournissez un montant jusqu’au montant d’autorisation complémentaire maximum pris en charge par le moyen de paiement.

Transmettez un hachage amount_details mis à jour qui correspond au montant total autorisé après l’autorisation complémentaire.

Dans la réponse, le champ amount_details contient les éléments de poste spécifiés lors de l’autorisation complémentaire, et le montant total autorisé du PaymentIntent est mis à jour.

{
  "amount": 5000,
  "amount_capturable": 5000,
  "amount_received": 0,
  "payment_details": {
    "customer_reference": "customer_reference",
    "order_reference": "order_reference"
  },
  "amount_details": {
    "discount_amount": 200,
    "tax": {
      "total_tax_amount": 600
    },
    "shipping": {
      "from_postal_code": "94110",
      "to_postal_code": "94117",
      "amount": 600
    },
    "line_items": {
      "object": "list",
      "url": "/v1/payment_intents/pi_xxxxxxxx/amount_details_line_items",
      "has_more": false,
      "data": [
        {
          "_id": "li_901",
          "product_code": "SKU001",
          "product_name": "Product 001",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "feet",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        },
        {
          "_id": "li_012",
          "product_code": "SKU002",
          "product_name": "Product 002",
          "unit_cost": 2000,
          "quantity": 1,
          "unit_of_measure": "gallons",
          "payment_method_options": {
            "card": {
              "commodity_code": "123123"
            }
          }
        }
      ]
    }
  },
  "status": "requires_capture"
  ...
}