Creating a payment method

Note

If you use the payment methods API to create a payment method, you must integrate and support your chosen payment method types, such as Apple Pay and Google Pay. The hosted checkout iframe automatically integrates all Toast platform supported payment method types.

After you have successfully created the payment intent, the next step is to create and attach a payment method to the intent. A payment method is any method that your customer can use to pay for a product or service. You can create payment methods for the following transaction types:

You can create a payment method using the createPaymentMethod SDK function or you can choose to create a payment method by sending a POST request to the /v1/payment-methods endpoint of the payment methods API. You create a payment method using the payment methods API if you want to take payments using the Toast platform, but do not want to use the iframe to capture customer payment card data.

Important

If you choose to create a payment method using the payment methods API, this puts your integration and the customer’s card data under PCI scope.

Compliance with PCI DSS and all other regulations or laws is solely your responsibility. The information provided is for informational purposes only and should not be relied upon or used as a substitute for consultation with a Qualified Security Assessor or other legal advisor. Please consult a professional advisor for a qualified opinion on the applicability of requirements to your business operations.

Card (keyed-in and saved card) transactions

Note

To create a payment method for a saved card, you must have included the customerId in the request to create a payment intent.

A CARD transaction is a transaction where the payment card is not physically present at the time of payment. An example of a CARD transaction is an online order made through the hosted checkout iframe. Keyed-in and saved card transactions are a type of CARD transaction.

To create a payment method for a CARD transaction, send a POST request to the /v1/payment-methods endpoint of the payment methods 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 method for. In the request body, set the type value to CARD and include the Card object, which contains information about the payment card. Set the usage value to ON_SESSION if the customer wants to save the payment method for future use.

Include the following header parameters:

Toast-Session-Secret: The unique and randomized identifier for the payment or setup intent. This is returned in the response to create a payment or setup intent.
Toast-Idempotency-Key: An integration-generated universally unique identifier (UUID) that is used to recognize retries of the same request.

Example request body

{
    "type": "CARD", 
    "card": { 
      "number": "4242424242424242", 
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "ON_SESSION" 
}

	The type of payment method created. The value is: `CARD`.
	The payment method details for a `CARD` transaction.
	The primary account number (PAN) of the card, which the API validates using the ISO-standard Luhn algorithm.
	Used to determine if the customer will save the payment method for future use. If the customer wants to save the payment card, set the value to `ON_SESSION`. If the customer does not want to save the payment card for future use, set the value to `null`.

Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 
    "type": "CARD", 
    "usage": "ON_SESSION",
    "card": {
        "firstSix": "411111",
        "lastFour": "1111",
        "expiry": {
            "month": "12",
            "year": "27"
        },
        "brand": "VISA",
        "type": "VISA", 
        "fingerprint": "e19f9942-942b-4716-a45c-6ee69225970d", 
        "funding": "Debit",

        [contents omitted]
    }
}

	The identifier of the payment method. Include the `id`, which is the identifier of the payment method in the request to confirm a payment intent. For more information, see Confirming a payment intent.
	The payment method details for a `CARD` transaction.

Future merchant-initiated transactions

Some CARD transactions are merchant-initiated transactions. For more information, see Merchant-initiated transactions. To create a payment method for future merchant-initiated transactions, send a POST request to the /v1/payment-methods endpoint of the payment methods API to create a payment method. 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 method for. In the request body, set the type value to CARD and include the Card object, which contains information about the payment card. Set the usage value to OFF_SESSION to use for future merchant-initiated transactions or ON_AND_OFF_SESSION if the customer wants to save the payment method to use for both customer and merchant-initiated transactions.

Include the following header parameters:

Toast-Session-Secret: A unique and randomized identifier for the payment or setup intent.
Toast-Idempotency-Key: An integration generated universally unique identifier (UUID) that is used to recognize retries of the same request.

Example request body

{
    "type": "CARD", 
    "card": { 
      "number": "4242424242424242", 
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "ON_AND_OFF_SESSION" 
}

The type of payment method created. The value is: CARD.

The payment method details for a CARD transaction.

The primary account number (PAN) of the card, which the API validates using the ISO-standard Luhn algorithm.

Used to determine if the customer will save the payment method for future use.

ON_SESSION: Stores and saves the payment method to the customer’s profile and creates a card-on-file for future customer-initiated transactions. The customer has selected the Remember this card checkbox in the hosted checkout iframe.

You must have included the customerId in the request body to create a payment intent to set the usage to ON_SESSION. The payment card must be saved to a customer record.

Note

The payment card cannot be used for merchant-initiated transactions.

OFF_SESSION: Stores the payment method and creates a card-on-file for merchant-initiated transactions. The customer has selected the I authorize this business to charge my card as outlined in the terms checkbox in the hosted checkout iframe.

Note

The payment card is not saved to the customer’s profile and cannot be selected in the hosted checkout iframe.

ON_AND_OFF_SESSION: Stores and saves the payment method to the customer’s profile and creates a card-on-file for both customer and merchant-initiated transactions. The customer has selected both the Remember this card checkbox and the I authorize this business to charge my card as outlined in the terms checkbox in the hosted checkout iframe.

You must have included the customerId in the request body to create a payment intent to set the usage to ON_AND_OFF_SESSION.

Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 
    "type": "CARD",
    "usage": "ON_AND_OFF_SESSION" 
    "card": { 
        "firstSix": "411111",
        "lastFour": "1111",
        "expiry": {
            "month": "12",
            "year": "27"
        },
        "brand": "VISA",
        "type": "VISA", 
        "fingerprint": "e19f9942-942b-4716-a45c-6ee69225970d", 
        "funding": "Debit",

        [contents omitted]
    }
}

	The identifier of the payment method. Include the `id`, which is the identifier of the payment method in the request to confirm a payment intent. For more information, see Confirming a payment intent.
	The payment method details for a `CARD` transaction.

Gift card transactions

A GIFT_CARD transaction is a transaction where the customer manually enters the gift card number in the hosted checkout iframe. An example of a GIFT_CARD transaction is an online order made through the hosted checkout iframe.

To create a payment method for a GIFT_CARD transaction, send a POST request to the /v1/payment-methods endpoint of the payment methods 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 method for. In the request body, set the type value to GIFT_CARD and include the GiftCard object, which contains information about the gift card payment method. Set the usage value to ON_SESSION if the customer wants to save the payment method for future use.

Include the following header parameters:

Toast-Session-Secret: The unique and randomized identifier for the payment or setup intent. This is returned in the response to create a payment or setup intent.
Toast-Idempotency-Key: An integration-generated universally unique identifier (UUID) that is used to recognize retries of the same request.

Example request body

{
   "type": "GIFT_CARD", 
   "usage": null, 
   "giftCard": {  
       "giftCardAccountNumber": 
             [contents omitted]",
       "pin": "[contents omitted]",
       "encryptionScheme": { 
           "type": "RSA-OAEP-SHA256", 
           "keyId": "RSA-OAEP-SHA256::keyed_card", 
           "iv": null, 
           "ksn": null 
       }
  }
}

	The type of payment method. The value is: `GIFT_CARD`.
	Used to determine if the customer will save the payment method for future use. If the customer wants to save the payment card, set the value to `ON_SESSION`. If the customer does not want to save the payment card for future use, set the value to `null`.
	The payment method details for a `GIFT_CARD` transaction.
	Details about how the payment method was encrypted.
	The type of encryption mechanism used to protect customer payment card data. The available values are: `DUKPT_2K_TDEA_128` `DUKPT_AES_128` `RSA_OAEP_SHA1`
	The key identifier generated from a public key used for RSA encryption.
	The initialization vector (IV) starting value. This value should be `null` for transactions that use the RSA encryption mechanism.
	The key serial number (KSN). This value should be `null` for transactions that use the RSA encryption mechanism.

Example response body

{
   "id": "bdb5756c-d909-41b6-8eee-604fa1fcc3c6", 
   "type": "GIFT_CARD",
   "giftCard": {  
       "firstSix": "603799",
       "lastFour": "1112"
   }
}

	The identifier of the payment method. Include the `id`, which is the identifier of the payment method in the request to confirm a payment intent. For more information, see Confirming a payment intent.
	The payment method details for a `GIFT_CARD` transaction.