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 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.

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.

After you have successfully created a payment intent, you create and attach a payment method to the intent. To create a payment method, send a POST request to the v1/payment-methods endpoint of the payment methods API. In the request body, include the payment method type and card details. 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 card details used to tokenize the payment card.
	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.

Future 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. In the request body, include the payment method type and card details. 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 card details used to tokenize the payment card.

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.

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.