Creating a payment method

Similar to a payment intent, you can use the createPaymentMethod SDK function or 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 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", 1
    "card": { 2
      "number": "4242424242424242", 3
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "OFF_SESSION" 4
}

1

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

2

The card details used to tokenize the payment card.

3

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

4

Used to determine if the customer will save the payment method for future use. Set the value to ON_SESSION to save the payment card for future customer use. 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": "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]
    }
}

Future merchant-initiated transactions

To create a payment method for merchant-initiated transactions, you can use the createPaymentMethod SDK function or 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 OFF_SESSION to use for future 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: 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", 1
    "card": { 2
      "number": "4242424242424242", 3
      "cvv": "123",
      "expiry": { 
        "month": "12",
        "year": "27"
      }
    },
    "billingDetails": {
       "postalCode": "02118"
    },
    "usage": "OFF_SESSION" 4
}

1

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

2

The card details used to tokenize the payment card.

3

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

4

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 have included the customerId in the request body to create a setup intent to set the usage value to ON_SESSION.

    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 setup intent to set the usage to ON_AND_OFF_SESSION.


Example response body

{
    "id": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5", 1
    "type": "CARD",
    "usage": "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]
    }
}

1

The identifier of the payment method.