Card Present

Collecting Card Present Payments

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. New terminal_reader API documentation can be found here.

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.

Integrating Card Present into your UI

Ready to design a card-present payment flow for your software? Let’s walk through a step-by-step practical example of how to integrate with card present payments into your user interface.

In this example, Piece of Cake Management Software, a company specializing in building software for bakeries across North America, is expanding its payments solution to offer card present.

In the software, there is a checkout flow where the merchant selects which products were sold. When it's time to collect payment from the customer, the software should give the merchant the option to select which payment method they will use. In this case, card-present needs to be added as a payment method.

The merchant selects card-present as the payment method. Next, the system prompts the merchant to select the device they wish to process the payment with. If the merchant only has one device, this step can be skipped. The Terminal Reader id serves as the unique identifier for the device, but it is recommended to display this alongside the description (e.g., front desk) if one exists, to create a more user-friendly experience.

Once the merchant has selected their device, they are allowed to Collect Payment. This action prompts the customer to complete the transaction on the device.

If the software also handles reporting, it should ensure to consume and display the final transaction result.