Verwenden von Zahlungsposten für flexible Zahlungen

Erfahren Sie, wie Sie Zahlungsposten mit komplexen Zahlungen, wie Mehrfacherfassung und Übererfassung, verwenden können.

Sie können Posten für Zahlungen für komplexe Zahlungen verwenden, z.B. für Zahlungen mit Mehrfacherfassung und Übererfassung.

Multicapture

Sie können Zahlungsposten bei Mehrfacherfassungen verwenden.

Hinweis

Mehrfacherfassung wird für Klarna oder PayPal nicht unterstützt.

Einen nicht erfassten PaymentIntent erstellen und bestätigen

Hinweis

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Geben Sie bei der Erstellung des PaymentIntent die capture_method als manual an und verwenden Sie den Parameter if_available, um Mehrfacherfassung für diese Zahlung anzufordern. Der erstellte PaymentIntent ermöglicht mehrere Erfassungen, sofern die Zahlungsmethode dies unterstützt.

In der Antwort enthält das Feld amount_details die in PaymentIntent angegebenen Einzelposten.

{
  "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"
          }
        }
      }
    ]
  }
  ...
}

PaymentIntent erfassen

Sie können amount_details beim ersten Erfassen hinzufügen, auch wenn sie bei der Erstellung nicht angegeben wurden.
Wenn Sie bei der Erstellung amount_details angegeben haben, müssen Sie entweder amount_details übergeben oder sie bei der ersten Erfassung deaktivieren.

Dieselben Regeln gelten für amount_details[line_items]. Sie können sie beim ersten Erfassen hinzufügen, wenn Sie sie nicht bei der Erstellung angegeben haben, müssen sie jedoch einbeziehen oder explizit entfernen, falls sie bei der Erstellung vorhanden waren.

In der Antwort enthält das Feld amount_details die bei der ersten Erfassung angegebenen Einzelposten.

{
  "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"
  ...
}

Der PaymentIntent verbleibt im Status requires_capture. An dieser Stelle können Sie entweder:

Erfassen Sie den PaymentIntent weiterhin mehrfach bis zum vollen Betrag des PaymentIntent.
Versetzen Sie PaymentIntent in den Status succeeded, indem Sie final_capture auf true setzen oder eine Erfassung ohne den final_capture-Parameter durchführen (weil final_capture standardmäßig auf true gesetzt ist).

Wenn frühere Erfassungen amount_details oder amount_details[line_items] enthielten, müssen Sie sie weiterhin in nachfolgende Erfassungen einbeziehen.
Wenn frühere Erfassungen diese Felder nicht enthielten, können Sie sie in späteren Erfassungen nicht hinzufügen.

In der Antwort enthält das Feld amount_details die Einzelposten der ersten beiden Erfassungen gemäß den folgenden Regeln:

discount_amount, tax.total_tax_amount und shipping.amount werden über alle Erfassungen hinweg summiert.
shipping.from_postal_code und shipping.to_postal_code könnten in den Erfassungen weggelassen werden, aber wenn sie bereitgestellt werden, dürfen Sie sie nicht zwischen den Erfassungen ändern.
line_items wird über alle Erfassungen hinweg aggregiert.

{
  "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"
  ...
}

Übererfassung

Sie können Zahlungsposten während Übererfassungen verwenden.

Einen nicht erfassten PaymentIntent erstellen und bestätigen

Hinweis

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Geben Sie bei der Erstellung des PaymentIntent die capture_method als manual an und verwenden Sie den Parameter if_available, um die Übererfassung für diese Zahlung anzufragen. Der erstellte PaymentIntent erlaubt die Übererfassung, wenn die Zahlungsmethode dies unterstützt.

In der Antwort enthält das Feld amount_details die in PaymentIntent angegebenen Einzelposten.

{
  "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"
            }
          }
        }
      ]
    }
  }
  ...
}

PaymentIntent erfassen

Um mehr als den aktuell autorisierten Betrag für einen PaymentIntent zu erfassen, verwenden Sie Endpunkt erfassen und geben einen amount_to_capture bis zum maximum_amount_capturable an.

Übergeben Sie bei der Erfassung einen aktualisierten amount_details Hash, der mit dem erfassten Betrag übereinstimmt.

In der Antwort enthält das Feld amount_details die Posten, die beim Erfassen angegeben wurden.

{
  "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"
  ...
}

Inkrementelle Autorisierung

Sie können Zahlungsposten während der inkrementellen Autorisierung verwenden, um zusätzliche Beträge auf einem PaymentIntent nach der ursprünglichen Autorisierung zu autorisieren.

Einen nicht erfassten PaymentIntent erstellen und bestätigen

Hinweis

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Geben Sie bei der Erstellung des PaymentIntent die capture_method als manual an und verwenden Sie den Parameter if_available, um eine inkrementelle Autorisierung für diese Zahlung anzufordern. Das erstellte PaymentIntent ermöglicht eine inkrementelle Autorisierung, wenn die Zahlungsmethode dies unterstützt.

In der Antwort enthält das Feld amount_details die in PaymentIntent angegebenen Einzelposten.

{
  "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"
            }
          }
        }
      ]
    }
  }
  ...
}

Autorisierung erhöhen

Um zusätzliche Beträge für ein PaymentIntent über den ursprünglich autorisierten Betrag hinaus zu autorisieren, verwenden Sie den increment_authorization-Endpoint und geben Sie einen Betrag bis zur maximal zulässigen inkrementellen Autorisierung der Zahlungsmethode an.

Übergeben Sie einen aktualisierten amount_details-Hash, der dem gesamten autorisierten Betrag nach der Erhöhung entspricht.

In der Antwort enthält das Feld amount_details die Posten, die während der inkrementellen Autorisierung angegeben wurden und der autorisierte Gesamtbetrag des PaymentIntent wird aktualisiert.

{
  "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"
  ...
}

Teilautorisierung

Sie können Zahlungsposten mit Teilautorisierungen verwenden.

Einen nicht erfassten PaymentIntent erstellen und bestätigen

Hinweis

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Geben Sie beim Erstellen des PaymentIntent die capture_method als manuell an und verwenden Sie den Parameter if_available, um eine Teilautorisierung für diese Zahlung anzufordern.

Wenn Sie die Postendaten vor der Teilautorisierung angegeben haben, könnte es sein, dass die Summe der Postenbeträge nicht mit dem Gesamtbetrag auf dem PaymentIntent übereinstimmt. In diesem Fall hat der amount_details.error-Hash in der Antwort einen Code von amount_details_amount_mismatch und beinhaltet den abweichenden Betrag in der message-Eigenschaft.

Die Beispiel-Antwort unten zeigt, dass die Transaktion für 7 USD teilautorisiert wurde, was weniger ist als die ursprünglich angefragten 10 USD.

Example PaymentIntent confirmation response
{
  "id": "pi_3SpkXE2QCQbYXizB1WscY8lW",
  "object": "payment_intent",
  "amount": 700,
  "amount_capturable": 700,
  "amount_details": {
    "error": {
      "code": "amount_details_amount_mismatch",
      "message": "Invalid amount_details. The calculated amount is Sum(line_items[#].unit_cost * line_items[#].quantity + line_items[#].tax.total_tax_amount - line_items[#].discount_amount) + shipping.amount or Sum(line_items[#].unit_cost * line_items[#].quantity) + tax.total_tax_amount + shipping.amount - discount_amount which does not match the total amount charged. In this case the calculated amount 1000 is not equal to the total amount 700 on the PaymentIntent."
    },
    "line_items": {
      "object": "list",
      "data": [
        {
          "id": "uli_TnLDKPQgGwfFxD",
          "object": "payment_intent_amount_details_line_item",
          "discount_amount": null,
          "payment_method_options": null,
          "product_code": "SKU001",
          "product_name": "Product 001",
          "quantity": 1,
          "tax": null,
          "unit_cost": 800,
          "unit_of_measure": "feet"
        }
      ],
      "has_more": false,
      "url": "/v1/payment_intents/pi_3SpkXE2QCQbYXizB1WscY8lW/amount_details_line_items"
    },
    "shipping": {
      "amount": 100,
      "from_postal_code": "94110",
      "to_postal_code": "94117"
    },
    "tax": {
      "total_tax_amount": 100
    },
    "tip": {}
  },
  "status": "requires_capture"
}

PaymentIntent erfassen

Erfassen Sie den PaymentIntent und übergeben Sie aktualisierte amount_details, die dem teilautorisierten Betrag entsprechen.

Das Aktualisieren der amount_details entfernt den von der Nichtübereinstimmung verursachten Fehler-Hash aus dem PaymentIntent. Bei Kartenzahlungen versetzt das Stripe in die Lage, die Postendaten an Kartennetzwerke zu senden.

Example PaymentIntent capture response
{
  "id": "pi_3SpkXE2QCQbYXizB1WscY8lW",
  "object": "payment_intent",
  "amount": 700,
  "amount_capturable": 0,
  "amount_details": {
    "line_items": {
      "object": "list",
      "data": [
        {
          "id": "uli_TnM6fcFHBk7BMk",
          "object": "payment_intent_amount_details_line_item",
          "discount_amount": null,
          "payment_method_options": null,
          "product_code": "SKU002",
          "product_name": "Product 002",
          "quantity": 1,
          "tax": null,
          "unit_cost": 500,
          "unit_of_measure": "feet"
        }
      ],
      "has_more": false,
      "url": "/v1/payment_intents/pi_3SplOI2QCQbYXizB0DaGWmQT/amount_details_line_items"
    },
    "shipping": {
      "amount": 100,
      "from_postal_code": "94110",
      "to_postal_code": "94117"
    },
    "tax": {
      "total_tax_amount": 100
    },
    "tip": {}
  },
  "amount_received": 700,
  "status": "succeeded"
}