Create a payment method

Creates a payment method.

SecurityOAuth2 or OAuth2
Request
header Parameters
Toast-Idempotency-Key
required
string <UUID>

An integration generated universally unique identifier (UUID) that is used to recognize retries of the same request.

Toast-Session-Secret
required
string <string>

A unique and randomized identifier for the payment or setup intent.

Request Body schema: application/json
object
object (Card)

Card creation attributes.

type
string

The type of payment method.

  • CARD - Payment card, including Apple Pay and Google Pay digital wallets. Use card.wallet.type to indicate the wallet type.
  • CARD_PRESENT - This is reserved for future use.
  • GIFT_CARD - This is reserved for future use.
  • GIFT_CARD_PRESENT - This is reserved for future use.
  • US_BANK_ACCOUNT - Reserved for future use. US bank account payment method for ACH transactions. Provide account details via the usBankAccount field.
Enum: "CARD" "CARD_PRESENT" "GIFT_CARD" "GIFT_CARD_PRESENT" "US_BANK_ACCOUNT"
usage
string or null

Field used to determine if the logged-in customer will save the payment method for future usage. The value is ON_SESSION for cards saved during checkout. The value is NULL if the card will not be saved for future usage.

  • ON_SESSION - Saves the payment method for future customer-initiated transactions.
  • OFF_SESSION - Saves the payment method for future merchant-initiated transactions.
  • ON_AND_OFF_SESSION - Saves the payment method for future customer or merchant-initiated transactions.
Enum: "ON_SESSION" "OFF_SESSION" "ON_AND_OFF_SESSION"
Responses
200

Succesful operation. Payment method created.

400

Invalid request, card data, or session.

403

Your Toast API client does not have permission to create the payment method.

409

Payment method not found or hasn't been scoped to payment or setup intent.

500

Internal server error.

post/v1/payment-methods
Request samples
application/json
{
  • "type": "CARD",
  • "card": {
    },
  • "billingDetails": {
    },
  • "usage": "ON_SESSION"
}
Response samples
application/json
{
  • "id": "string",
  • "type": "CARD",
  • "billingDetails": {
    },
  • "usage": "ON_SESSION",
  • "card": {
    }
}