The way we process payments, is a 2-step process. First, you’re going to make a REST call to our API, to initiate the payment, and the second step will be a callback from us, once the user has confirmed the payment.
In order to initiate a payment on HealthKey, you will require the authorisation token, obtained after authenticating the user. We will also be expecting you to provide us details about the purchase, such as the product(s) the user is wishing to buy, the type of transaction (one-time/subscription), etc. An example of a request initiating a payment could look like this:
POST /api/v1/transactions HTTP/1.1
Host: SERVER_API_HOSTNAME
Accept: application/json
Authorization: Bearer {access_token}
Content-Type: application/json
{
"products": [
{
"name":"Test Product",
"externalId": "asa1213sdfds231f",
"description": "description",
"price": 20,
"currency": "GBP",
"quantity": 1,
"subscription": {
"frequency": 3,
"frequencyUnit": "months",
"startingDate" : "11/04/2023",
"freeTrial" : "true"
}
},
{
"name":"Test Product One",
"externalId": "233gsddd33dsgs233",
"description": "description",
"price": 40,
"currency": "GBP",
"quantity": 2
}
],
"successUrl" : "<https://healthkey.healt?returnPage=confirmation>",
"requireAddress": "true"
}
In the request, you will have to send a list of products, and optionally, a URL where we should redirect the user at the end of the transaction.
The structure of each product is as follows:
name: the name of the product; this will be displayed on the HealthKey platform, to help the user identify what they’ve purchased.
externalId: this is the id of the product (shouldn’t be unique per transaction; we expect the same id for the same product), that will help you reconcile the data back into your system, once the transaction has been processed. We are also using this id on our side, in order to process any updates that might come with every request (update the price, the description, etc.).
description (optional): a short description of the product; this will be displayed on the HealthKey platform, to help the user identify each product.
price: the price of the product; this will be used both for one-time off purchases and for subscriptions. For a subscription, this field should contain the price of the subscription, for the given frequency, specified inside the subscription object.
currency: the currency of the price; currently we only support GBP, so if you don’t send it, it will default to GBP.
quantity: the number of purchases for this product.
subscription (optional): the way our support for subscription works, is that if you send a subscription object when starting the payment for a product, we will treat it as a recurring payment. Currently, we provide support for two fields of a subscription.
frequency is the number of days/months the subscription should renew, the frequencyUnit can have two possible values: months or days
startingDate is the date you would want the user to start their subscription (if you send null, it will start on the day you make the request). The format should be “dd/MM/YYYY”
freeTrial if you want to offer a free trial for the subscription of one of your products, set this flag to true; until the startingDate, we won’t charge the user anything
successUrl: this parameter can be used, if you’d like us to redirect the user to a different page, for each transaction; normally we redirect the user back to your home URL, but if you have an invoice page or something similar, you might want to use this parameter
requireAddress: if you set this flag to true, we won’t allow the user to process the transaction, until they enter the details of their address; good to use when you need us to tell you the user’s home address.
This request will initiate the payment, and will return a response like this:
{
"id": "t_2d36bb8bdd1c47a9a500ae8ad036f5df",
"status": "processing",
"createdOn": "2023-01-17T16:58:40.517498221",
"processedOn": "2023-01-17T16:58:40.517505889",
"products": [
{
"name": "Test Product",
"externalId": "asa1213sdfds231f",
"description": "description",
"price": 20,
"currency": "GBP",
"quantity": 2,
"subscription": null
}
]
}
From this request, it is important to persist the ‘transaction_id’ somewhere, as that’s what you will use to reconcile the payment confirmation request.
At the moment, we have decided to limit the number of pending transactions to one. So a customer won’t be able to start another payment until they finish their current pending payment.