Card Present

If you are already acquainted with collecting card-not-present transactions using Tilled, the process for card-present transactions will be quite similar. If not, you can learn more about collecting payments in our payment intent documentation.

Here are the steps to collect a card-present transaction:

1. Retrieve a List of Terminals:

   • When a merchant orders a card-present reader, Tilled associates the device's serial number with the merchant and assigns a terminal ID.
   • Before processing a payment, retrieve a list of available terminals associated with the merchant. This allows you to specify the device from which the payment will be collected.
   • Make a GET request to: https://sandbox-app.tilled.com/v1/terminal-readers
   • Example:

     1curl --location --request GET 'https://sandbox-app.tilled.com/v1/terminal-readers?limit=30&offset=0' \
     2--header 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
     3--header 'tilled-api-key: {{SECRET_KEY}}'
     

2. Create a Payment Method:

   • To confirm the payment_intent, attach a payment_method. This payment_method should have the type set to 'card_present' and the [terminal_id] of the device from which the payment will be collected.
   • Make a POST request to https://sandbox-app.tilled.com/v1/payment_methods
   • Example:

     1curl --location --request POST 'https://sandbox-app.tilled.com/v1/payment-methods' \
     2--header 'tilled-api-key: {{SECRET_KEY}}' \
     3--header 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
     4--header 'Content-Type: application/json' \
     5--data '{
     6    "type": "card_present",
     7    "terminal_reader_id": "term_xxxxxxxxx"
     8}'
     

3. Collect the Payment:

   • Similar to creating a card-not-present transaction, start by creating a payment intent.
   • Specify [card_present] as the value for the payment_method_type property and include the payment_method_id from the response in step 2.
   • When you confirm the payment_intent, this will put the payment_intent into a status of requires_action, indicating that the payment_intent has been pushed to the terminal, and the customer will be prompted to complete the payment.
   • Make a POST request to Tilled/v1/payment_intents
   • Example:

      1curl --location --request POST 'https://sandbox-app.tilled.com/v1/payment-intents' \
      2--header 'Content-Type: application/json' \
      3--header 'tilled-api-key: {{SECRET_KEY}}' \
      4--header 'tilled-account: {{MERCHANT_ACCOUNT_ID}}' \
      5--data '{
      6    "amount" : 10003,
      7    "currency": "usd",
      8    "payment_method_types": [ "card_present" ],
      9    "payment_method_id": "{{PAYMENT_METHOD_ID}}",
     10    "confirm": true
     11}'
     

4. Receive the Transaction Response:

   • Create a webhook (learn more in our Webhooks Documentation) for payment_intent_events, and we will send updates regarding the success of the payment intent and the associated transaction details.