Creating a payment method

The next step is to create a payment method to attach to the payment intent. In this example, a gift card is used first as the payment method.

Note

There is no limit on the number of gift cards that can be used to pay a check balance. Your integration is responsible for setting a limit on the number of payment methods that can be used.

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. 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", 1
   "usage": null, 2
   "giftCard": { 3
       "giftCardAccountNumber": 4
             "[contents omitted]",
       "pin": "[contents omitted]", 5
       "encryptionScheme": { 6
           "type": "DUKPT_AES_128", 7
           "iv": "abcdef1234567890", 8
           "ksn": "550C170000000173000001A2" 9
       }
  }
}

1

The type of payment method. The value is: GIFT_CARD.

2

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.

3

The payment method details for a GIFT_CARD transaction.

4

The unique Base64 encoded identifier of the encrypted Gift Card Account Number (GAN).

5

The Base64 encoded 3-4 digit code used to authorize purchases or check balances.

6

Information about how the payment method was encrypted.

7

The type of encryption mechanism used to protect customer payment card data. Available values are:

  • DUKPT_2K_TDEA_128

  • DUKPT_AES_128

  • RSA_OAEP_SHA1

8

The initialization vector (IV) starting value used for DUKPT AES encrypted payment card data.

9

The key serial number (KSN) used in DUKPT transactions. The KSN includes the key set identifier (KSI) which is used for secure transactions. The KSN identifies the payment terminal (device) and transaction count.


Example response body

{
   "id": "f43c0c7f-ff56-4a23-99fa-354b82045a09", 1
   "type": "GIFT_CARD", 
   "giftCard": {   2
       "firstSix": "415150",
       "lastFour": "0008"
   }
}

1

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.

2

The payment method details for a GIFT_CARD transaction.