Link Search Menu Expand Document

Payment Intents

Learn how to use the Payment Intents API for Tilled payments.

Use the Payment Intents API to build an integration that can handle complex payment flows. It tracks a payment from creation through checkout, and triggers additional authentication steps when required.

Building an integration with the Payment Intents API involves two actions: creating and confirming a PaymentIntent. Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment. Each PaymentIntent typically correlates with a single shopping cart or customer session in your application. The PaymentIntent encapsulates details about the transaction, such as the supported payment methods, the amount to collect, and the desired currency.

Creating a PaymentIntent

You must create the PaymentIntent on your server and pass its client secret to the client. The client confirms the payment, and your server monitors webhooks to detect when the payment successfully completes or fails.

When you create the PaymentIntent, you can specify options like amount and currency:

$ curl -X POST https://api.tilled.com/v1/payment-intents \
-H "tilled-api-key: {{SECRET_KEY}}" \
-H "tilled-account: {{MERCHANT_ACCOUNT_ID}}" \
-H "Content-Type: application/json" \
-d '{ "amount": 1099, "currency": "usd", "payment_method_types": ["card"] }'

Note: The amount is a positive integer representing how much to charge in the smallest currency unit (e.g., 1000 cents to charge $10.00).

Best practices

We recommend creating a PaymentIntent as soon as you know the amount, such as when the customer begins the checkout process, to help track your sales funnel. If the amount changes, you can update its amount. For example, if your customer backs out of the checkout process and adds new items to their cart, you may need to update the amount when they start the checkout process again.

If the checkout process is interrupted and resumes later, attempt to reuse the same PaymentIntent instead of creating a new one. Each PaymentIntent has a unique ID that you can use to retrieve it if you need it again. In the data model of your application, you can store the ID of the PaymentIntent on the customer’s shopping cart or session to facilitate retrieval. The benefit of reusing the PaymentIntent is that the object helps track any failed payment attempts for a given cart or session.

Storing information in metadata

Tilled supports adding metadata to the most common requests you make, such as processing payments. Metadata isn’t shown to customers or factored into whether or not a payment is declined or blocked by our fraud prevention system.

Through metadata, you can associate other information that’s meaningful to you with Tilled activity. Any metadata you include is viewable in the Console (e.g., when looking at the page for an individual payment), and is also available in common reports. As an example, you can attach the order ID for your store to the PaymentIntent for that order. Doing so allows you to easily reconcile payments in Tilled to orders in your system.

$ curl -X POST https://api.tilled.com/v1/payment-intents \
-H "tilled-api-key: {{SECRET_KEY}}" \
-H "tilled-account: {{MERCHANT_ACCOUNT_ID}}" \
-H "Content-Type: application/json" \
-d '{ "amount": 1099, "currency": "usd", "payment_method_types": ["card"], "metadata": { "order_id": "8831" } }'

Confirming a PaymentIntent

The API provide a lot of flexibility to handle different workflows, such as being able to add a payment_method_id within the Create PaymentIntent. You are also able to confirm at the same time as creation by passing confirm=true in the body. For PaymentIntents that have a status requires_payment_method, you must have a payment method and use the Confirm PaymentIntent API.

You can specify the PaymentIntent id in the path and the payment_method_id in the body:

$ curl -X POST https://api.tilled.com/v1/payment-intents/{{PAYMENT_INTENT_ID}}/confirm \
-H "tilled-api-key: {{SECRET_KEY}}" \
-H "tilled-account: {{MERCHANT_ACCOUNT_ID}}" \
-H "Content-Type: application/json" \
-d '{ "payment_method_id": "{{PAYMENT_METHOD_ID}}" }'

Note: To create a payment_method_id see Create a payment method for more details about tilled.js and API

Status and lifecycle

Asynchronous payment flows are complex to manage because they depend on customer interactions that happen outside of your application. PaymentIntents simplify this by keeping track of the status of the payment. They act as the single source of truth in the lifecycle of the flow.

  • requires_payment_method
    • When the PaymentIntent is created, it has a status of requires_payment_method until a payment method is attached.
    • We recommend creating the PaymentIntent as soon as you know how much you want to charge, so that Tilled can record all the attempted payments.
    • If the payment fails (for example, due to a decline), the PaymentIntent’s status returns to requires_payment_method.
  • requires_confirmation optional
    • After the customer provides their payment information, the PaymentIntent is ready to be confirmed.
    • In most integrations, this state is skipped because the payment method information is submitted at the same time that the payment is confirmed.
  • requires_capture optional
    • Separate authorization and capture to create a charge now, but capture funds later. For example, a hotel may authorize a payment in full prior to a guest’s arrival, then move the money when the guest checks out. If the capture_method=manual for the PaymentIntent, the status will move to requires_capture after it has been confirmed.
  • requires_action
    • If the payment requires additional actions, such as authenticating with 3D Secure or physically swiping the card with the terminal during card_present transactions, the PaymentIntent has a status of requires_action.
  • processing
    • Once required actions are handled, the PaymentIntent moves to processing. While for some payment methods (e.g. cards), processing can be quick, other types of payment methods can take up to a few days to process.
  • succeeded
    • A PaymentIntent with a status of succeeded means that the payment flow it is driving is complete.
    • The funds are now in your account and you can confidently fulfill the order. If you need to refund the customer, you can use the Refunds API.
  • canceled
    • You may cancel a PaymentIntent at any point before it processing or succeeded. This invalidates the PaymentIntent for future attempts and cannot be undone. If any funds have been held, cancellation returns those funds.

Copyright © 2022 Tilled