Payments

Are you collecting payments as part of your booking flow?

With the instant_payment graph, you can collect payments from customers as they sign up for a booking. You can use whichever method you prefer to collect the payments. After collecting a payment for a booking, you simply need to make Timekit aware that a customer has paid and the booking will enter a paid state.

A blueprint for paid bookings

The instant_payment graph is a blueprint for handling payments in your booking flow. It looks like this:

592

The instant_payment graph.

There are a few ways in which the instant_payment graph differs from the instant graph. First of all, where the instant graph goes directly into a confirmed state, the instant_payment graph goes into a tentative state. Before entering this state, a timeout is set (the default is 5 minutes) after which the booking will automatically enter an unpaid state. While the booking is in its tentative state, you can mark it as paid, which, of course, will move it into a paid state. The paid state is similar to the confirmed state that non-payment booking flows have.

Creating a booking

Creating a booking using the instant_payment graph is similar to creating any other 1-on-1 booking. This is an example JSON payload you would [POST] to /bookings:

curl --request POST \
  --url https://api.timekit.io/v2/bookings \
  --user :test_api_key_nvHfRSlhvsnlg4rS7Wt28Ty47qdgegwSu3YK7hPW \
  --header 'Content-Type: application/json' \
  --data '{
  "graph": "instant_payment",
  "action": "create",
  "event": {
    "start": "2015-03-01T08:00:00+00:00",
    "end": "2015-03-01T13:00:00+00:00",
    "what": "Mens haircut",
    "where": "Sesame St, Middleburg, FL 32068, USA",
    "calendar_id": "<your-calendar-id>",
    "description": "Please arrive 10 minutes before you time begin"
  },
  "customer": {
    "name": "Marty McFly",
    "email": "[email protected]",
    "phone": "1-591-001-5403",
    "voip": "McFly",
    "timezone": "America/Los_Angeles"
  }
}'

The JSON response would look similar to this:

{
  "data": {
    "id": "58190fc6-1ec0-4ebb-b627-7ce6aa9fc703",
    "graph": "instant_payment",
    "state": "tentative",
    "completed": false,
    "created_at": "2016-02-11T11:58:45+0100",
    "updated_at": "2016-02-11T11:58:47+0100",
    "available_actions": [
      "pay"
    ],
    "attributes": {
      "event_info": {
        "start": "2015-03-01T08:00:00+00:00",
        "end": "2015-03-01T13:00:00+00:00",
        "what": "Mens haircut",
        "where": "Sesame St, Middleburg, FL 32068, USA",
        "description": "Please arrive 10 minutes before you time begin"
      }
    },
    "calendar": {
      "id": "c91c5d04-2a57-46c0-ab35-e489dadf132e",
      "name": "My calendar",
      "display_name": "My calendar",
      "description": "Ut adipisci non autem cum ut id.",
      "foregroundcolor": "#25d6be",
      "backgroundcolor": "#ea1cb8",
      "created_at": "2016-02-15T13:21:42+0100",
      "updated_at": "2016-02-15T13:21:42+0100"
    },
    "customers": [
      {
        "id": "a728e860-99c7-4009-8843-7d9ac5d7f53f",
        "name": "Marty McFly",
        "email": "[email protected]",
        "phone": "1-591-001-5403",
        "voip": "McFly",
        "timezone": "America/Los_Angeles"
      }
    ]
  }
}

Now, the booking is in a tentative state and will time out in 5 minutes, unless you mark it as paid.

Paying for a booking

Although Timekit offers a blueprint for your paid booking flows, and is aware if a booking has been paid or not, you need to handle the actual payment on your end. Timekit is 100% flexible in the sense that you can use whichever method you prefer to handle your payments.

When you transition a booking into a paid state, you need to provide a payment_id. This can really be anything that helps you identify the payment, but usually it would be something like a Stripe transaction ID.

Here's the JSON you would [PUT] to the /bookings/:id/:action endpoint in order to transition a booking into a paid state:

{
  "pay": {
    "payment_id": "ch_191szuINaMd4BFD1REo9yJaF"
  }
}

The booking will now enter its paid state, which is similar to the confirmed state in a booking following the instant (non-payment) graph.

Timing out payments

Once a booking has entered a tentative state, by default, it will time out in 5 minutes and transition into an unpaid state. You can set the value of the timeout yourself, when you create the booking. Here's an example of how the JSON in a [POST] request to the /bookings endpoint would look:

curl --request POST \
  --url https://api.timekit.io/v2/bookings \
  --user :test_api_key_nvHfRSlhvsnlg4rS7Wt28Ty47qdgegwSu3YK7hPW \
  --header 'Content-Type: application/json' \
  --data '{
  "graph": "instant_payment",
  "action": "create",
  "event": {
    "start": "2015-03-01T08:00:00+00:00",
    "end": "2015-03-01T13:00:00+00:00",
    "what": "Mens haircut",
    "where": "Sesame St, Middleburg, FL 32068, USA",
    "calendar_id": "<your-calendar-id>",
    "description": "Please arrive 10 minutes before you time begin"
  },
  "customer": {
    "name": "Marty McFly",
    "email": "[email protected]",
    "phone": "1-591-001-5403",
    "voip": "McFly",
    "timezone": "America/Los_Angeles"
  },
  "timeout": {
  	"unit": "sec",
    "time": 60
  }
}'

This will set the timeout to 60 seconds. You can also use min as your unit.

That's it! If you have any questions about how to incorporate payments into your booking flow, hit us up on the chat.

We recommend that you also take a look at our guide "Building booking experiences with Timekit".