Creating a payment intent

Partial authorization allows you to send a request to authorize the total balance due using one payment method, and then authorize and capture the remaining balance using another payment method. The supported payment methods for partial authorization are gift cards and payment cards. Typically, gift cards are used first to reduce the total balance due, and then a payment card is used to pay the remaining balance.

For a partial authorization transaction, the customer manually enters the gift card details into the card input fields for authorization. For example, your customer has check balance for $50.00 and is planning on using two payment methods: a gift card and a payment card. Your customer plans to use the gift card first and then if needed, pay the remaining balance with a payment card. The balance on the gift card is unknown.

To create a payment intent, send a POST request to the /v1/payment-intents endpoint of the payment intents API. Include the Toast-Restaurant-External-ID as a header parameter in the request to specify the GUID of the Toast POS location that you are creating a payment intent for. In the request body, include the paymentMethodOptions.{type}.partialAuthorization object and include the payment method types you are going to allow partial authorization for. Set the value to true to allow partial authorization for each configured payment method.

Note

You can set multiple paymentMethodOptions.{type}.partialAuthorization values as you may not know what payment method the guest may use first to complete the payment.

The available payment method types are:

  • cardPresent

  • giftCard

  • giftCardPresent

Note

card is not available as a configurable payment method type. The card payment method type cannot be used for partial authorization.

Example request body

{
    "amount": 5000, 1
    "currency": "USD",
    "externalReferenceId": "6df3fe87-5d64-4d1f-97d3-6c4e1b767c17",
    "method": "INSTANT",
    "statementDescriptor": "TOAST",
    "paymentMethodOptions": {
        "giftCard": {
            "requestPartialAuthorization": true 2
        },
        "cardPresent": {
            "requestPartialAuthorization": false 
        },
        "giftCardPresent": {
            "requestPartialAuthorization": false 3
        }
    }
}

1

The payment amount in minor units represented as a positive integer. The minimum amount is 0.01 (represented as .01). In this example, 5000 represents fifty USD and zero cents.

2

Indicates that the payment method can be used for partial authorization. If the value is set to true and the payment method does not cover the full check balance, the Toast platform is authorized to capture the partial amount.

3

Indicates that the payment method cannot be used for partial authorization. If the value is set to false and the payment method does not cover the full check balance, the Toast platform is not authorized to capture the partial amount.


Example response body

{
    "id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c", 
    "externalReferenceId": "6df3fe87-5d64-4d1f-97d3-6c4e1b767c17", 
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov", 
    "amount": 5000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD", 
    "creationDate": "2023-09-29T16:42:36.239579Z", 
    "usage": null, 
    "customerId": null, 
    "amountDetails": {
        "tip": 0
    }, 
    "email": "john.smith@email.com", 
    "latestPayment": null, 
    "offSession": false,  
    "standingInstructionType": null, 
    "mandateId": null 
}