Managing payment methods

Deleting a payment method

Note

The server component of your integration makes the API request to delete a saved payment method.

If you allow customers to store payment cards, you can also allow them to remove payment cards by deleting the payment method from their customer record. Deleting a payment method from a customer record is permanent and the payment method cannot be reattached to their record. For more information on payment methods, see Creating a payment method.

There are two API requests associated with deleting a saved payment method from a customer record.

• Getting a list of payment methods attached to the customer record.

• Delete the payment method from the customer record using the customerId and paymentMethodId. The paymentMethodId is the unique identifier of the payment method.

Getting a list of payment methods attached to a customer record

To get a list of payment methods saved to a customer record, send a GET request to the v1/customers/{customerId}/payment-methods endpoint of the customers API. Include the Toast-Restaurant-External-ID as a header parameter in the request and the customerId in the request path.

Note

Customers cannot save digital wallets such as Apple Pay and Google Pay as payment methods.

Example response body

{
    "results": 1,  (1)
    "paymentMethods": [  (2)
        {
            "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", (3)
            "type": "CARD",
            "cardType": "VISA",
            "lastFour": "1111",
            "month": "12",
            "year": "27"
        }
    ]
}

• (1):

  The number of payment methods attached to the customer record.

• (2):

  The paymentMethods value that holds an array of paymentMethods objects. The paymentMethod object contains information about the payment card, the unique identifier for the payment card, card type, last four digits of the payment card, and the expiration month and year.

• (3):

  The unique identifier for the payment card. Use this id to delete a saved payment card from the customer record.

Deleting a payment method from a customer record

Note

You must use the hosted checkout - payment credentials for the server component of your integration.

To delete a payment method from a customer record, send a POST request to v1/payment-methods/{paymentMethodId}/detach endpoint of the payment methods API. Include Toast-Restaurant-External-ID as a header parameter in the request and the paymentMethodId in the request path. The paymentMethodId is the identifier for the payment card. In the request body, include the customerId.

Note

You cannot update the expiration date on a saved payment card. Your customer will need to add the payment card with the new expiration date and then delete the expired card.

Example request body

{
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002" (1)
}

• (1):

  The identifier for the customer record that identifies the customer in the Toast platform. You use the customerId to display the payment cards saved to the customer profile in your integration.

Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", (1)
    "type": "CARD",
    "card": {
        "lastFour": "1111",
        "type": "VISA",
        "expiry": {
            "month": "12",
            "year": "27"
        }
    }
}

• (1):

  The identifier for the deleted payment card.

Setting a default payment method

Note

You can set a default payment method to be preselected for customer use in the iframe by configuring your payment method configuration. For more information, see Managing payment method configurations.

As part of the hosted checkout iframe, you can automatically have your customer’s preferred saved payment card preselected for use on your checkout page. If your customer is logged into their customer profile in your integration and has set a payment method as the default, then when they checkout, their default payment method is preselected for use in the iframe.

To set a payment method as the default, the customer must have a customer record and have previously saved a payment card to their customer profile. The customer can save their payment card through either the setup intent or payment intent workflow. For information on the payment or setup intent workflows, see Payment intents or Setup intents.

To set a default payment method, send a POST request to the /v1/customers/{customerId}/payment-methods/defaults endpoint of the customers API. In the request body, include the contextName and the paymentMethodId. The contextName is the unique merchant or integration provided name that identifies the application that the payment method is being set as the default for. To get a customer’s list of payment methods, send a GET request to the /v1/customers/{id}/payment-methods endpoint of the customers API.

Example request body

{
    "paymentMethodId": "a1b2c3d4-5678-1234-8901-abcdef123456", (1)
    "contextName": "default-online-ordering" (2)
}

• (1):

  The identifier of the payment method.

• (2):

  The unique merchant or integration provided name that identifies the application context that the payment method should be set as the default for. For example, a New York cafe may use the context name of "NYC cafe checkout".

Example response body

{
    "paymentMethodId": "a1b2c3d4-5678-1234-8901-abcdef123456",
    "contextName": "default-online-ordering"
}

Getting the default payment method

To determine what payment method will be preselected for customer use during checkout, send a GET request to the /v1/customers/{id}/payment-methods/defaults/{contextName} endpoint of the customers API.

Example response body

{
    "paymentMethodId": "a1b2c3d4-5678-1234-8901-abcdef123456",
    "contextName": "default-online-ordering"
}

Deleting a default payment method

If your customer wants to delete a default payment method, send a POST request to the /v1/customers/{id}/payment-methods/defaults/{contextName} endpoint of the customers API. In the request body, include the contextName and the paymentMethodId.

No response is returned.

Example request body

{
    "paymentMethodId": "a1b2c3d4-5678-1234-8901-abcdef123456", 
    "contextName": "default-online-ordering" 
}