Payments

Endpoints

Create a Payment

POST /payments

Create a payment

Headers

Name	Type	Description
x-api-key	string	Your API key
Content-Type	string	application/json

Request Body

Name	Type	Description
prescriptionRequired	boolean	Defines whether a user has to upload a prescription during the checkout flow.
amount	object	See Amount
merchantReference	string	This reference can be used to identify the payment in your system. Maximum 40 characters.
merchantUrls	object	See MerchantUrls
cardCaptureMode	String	either "MANUAL" or "AUTO". Defaults to AUTO. If "MANUAL" the user's card will only be pre-authorised. You then have to use the /capture method in the given timespan. See dedicated method for details.
merchantId	String	hi.health issued ID. Use it instead of x-api-key to create a payment for a dedicated merchant.

200

{
    "amount": 20.01,
    "currency": "EUR",
    "createdAt": "2021-06-23T05:50:22.090Z",
    "customerInformation": {},
    "id": "01F8VPPRANKR4418TWW97QQGEH",
    "merchantReference": null,
    "merchantUrls": {
        "callback": "https://api.exampleshop.com/callback",
        "cancelRedirect": "https://exampleshop.com/cancel",
        "failureRedirect": "https://exampleshop.com/failure",
        "successRedirect": "https://exampleshop.com/success"
    },
    "amountDetails": {
        "tax": 2,
        "shipping": 10,
        "subtotal": 30.01
    },
    "prescriptionRequired": false,
    "status": "INITIAL",
    "updatedAt": null,
    "token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJhbW91bnQiOjIwMDEsImN1cnJlbmN5IjoiRVVSIiwiaWQiOiIwMUY4VlBQUkFOS1I0NDE4VFdXOTdRUUdFSCIsIm1lcmNoYW50VXJscyI6eyJmYWlsdXJlUmVkaXJlY3QiOiJodHRwczovL2V4YW1wbGVzaG9wLmNvbS9mYWlsdXJlIiwic3VjY2Vzc1JlZGlyZWN0IjoiaHR0cHM6Ly9leGFtcGxlc2hvcC5jb20vc3VjY2VzcyIsImNhbmNlbFJlZGlyZWN0IjoiaHR0cHM6Ly9leGFtcGxlc2hvcC5jb20vY2FuY2VsIn0sImFtb3VudERldGFpbHMiOnsidGF4IjoyMDAsInNoaXBwaW5nIjoxMDAwLCJzdWJ0b3RhbCI6MzAwMX0sInByZXNjcmlwdGlvblJlcXVpcmVkIjpmYWxzZSwic3RhdHVzIjoiSU5JVElBTCIsImlhdCI6MTYyNDQyNzQyMjA5MCwiZXhwIjoxNjI0NDM0NjIyMDkwLCJpc3MiOiJodHRwczovL2hpLmhlYWx0aCJ9.ABiWxQIJyzwiXXqxiepB0cJig70qXv3WEoBpmpN5HqHrEtRyuPrwaDdjnldXZOQbs1xBBMSZu0TxVsGCQRg4isqYAa6F1rHs2-wMjs3HS6F7CQTa3UTVj1J2_wb3-JuAsgv7QNRU21G53Jw9CYbAkGeIbM2pAscZJTGiQdrRRjqRZVmH"
}

400 Make sure you specified all required parameters in their correct form. Possible errors includes: - validation on required parameters or their required properties - validation on parameters of type number - validation on currency code - validation on the type of parameter used

- if required body parameter is missing

{
    "error": "merchantUrls is a required field"
}
---

- if required property of any body parameter is missing

{
    "error": "merchantUrls.callback is a required field"
}
---

- if a number is a float with more than 2 decimal places

{
    "error": "amount.total must have 2 or less digits after decimal point"
}
---

- if a number is negative or 0

{
    "error": "amount.total must be a positive number"
}
---

- if a number is negative

{
    "error": "amount.details.tax must be greater than or equal to 0"
}
---

- if currency is something other than "EUR" or "eur"

{
    "error": "amount.currency must be one of the following values: EUR, eur"
}
---

- if a parameter is not of expected type

{
    "error": "amount must be a `object` type, but the final value was: `123`."
}

403 Make sure you specified a valid x-api-key header.

{
    "message": "Forbidden"
}

500 Something went wrong on our side.

{
    "error": "Internal Server Error"
}

import axios from 'axios'

const HIDIRECT_BASE_URL = "<HIDIRECT_BASE_URL>"
const API_KEY = "<YOUR_API_KEY>"

axios.post(
  `${HIDIRECT_BASE_URL}/payments`,
  {
    "amount": {
      "total": 10,
      "currency": "EUR"
    },
    "merchantUrls": {
      "callback": "https://api.exampleshop.com/callback",
      "successRedirect": "https://exampleshop.com/success",
      "failureRedirect": "https://exampleshop.com/failure",
      "cancelRedirect": "https://exampleshop.com/cancel"
    }
  },
  {
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json"
    }
  })
  .then((response) => {
      console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
      console.log(error);
  });

Fetch a Payment

GET /payments/<id>

Fetch a payment

Path Parameters

Name	Type	Description
id	string	ID of the previously created payment

Headers

Name	Type	Description
x-api-key	string	Your API key

200

{
    "amount": 20.01,
    "currency": "EUR",
    "createdAt": "2021-06-24T08:34:30.874Z",
    "customerInformation": {},
    "id": "01F8YJG175R7JP223G76N7X75N",
    "merchantReference": null,
    "merchantUrls": {
        "callback": "https://api.exampleshop.com/callback",
        "cancelRedirect": "https://exampleshop.com/cancel",
        "failureRedirect": "https://exampleshop.com/failure",
        "successRedirect": "https://exampleshop.com/success"
    },
    "amountDetails": {
        "tax": 0,
        "shipping": 10,
        "subtotal": 10.01
    },
    "prescriptionRequired": false,
    "status": "INITIAL",
    "updatedAt": null
}

403 Make sure you specify a valid x-api-key header. You can also encounter this error code in case you don't use the required <id> parameter, but the message is different.

{
    "message": "Forbidden"
}
---

- if you don't use the <id> parameter

{
    "message": "Missing Authentication Token"
}

404 Make sure you have a valid Payment Id

{
    "error": "Not Found"
}

import axios from 'axios'

const HIDIRECT_BASE_URL = "<HIDIRECT_BASE_URL>"
const API_KEY = "<YOUR_API_KEY>"
const invoice_id = "<INVOICE_ID>"

axios.get(
  `${HIDIRECT_BASE_URL}/payments/${invoice_id}`,
  {
    headers: {
      "x-api-key": API_KEY,
    }
  })
  .then((response) => {
      console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
      console.log(error);
  });

Capture a Payment

POST /payments/<id>/capture

Trigger the capture of a payment that was previously pre-authorised.

This action is only possible on Payments that we're created with the option cardCaptureMode = MANUAL and have the Status AUTHORISED

If Payments are not captured within a span of 7 days, they are automatically cancelled.

Path Parameters

Name	Type	Description
id	string	ID of the previously created payment

Headers

Name	Type	Description
x-api-key	string	Your API key

200

{
    "amount": 20.01,
    "currency": "EUR",
    "createdAt": "2021-06-24T08:34:30.874Z",
    "customerInformation": {},
    "id": "01F8YJG175R7JP223G76N7X75N",
    "merchantReference": null,
    "merchantUrls": {
        "callback": "https://api.exampleshop.com/callback",
        "cancelRedirect": "https://exampleshop.com/cancel",
        "failureRedirect": "https://exampleshop.com/failure",
        "successRedirect": "https://exampleshop.com/success"
    },
    "amountDetails": {
        "tax": 0,
        "shipping": 10,
        "subtotal": 10.01
    },
    "prescriptionRequired": false,
    "status": "INITIAL",
    "updatedAt": null
}

403 Make sure you specify a valid x-api-key header. You can also encounter this error code in case you don't use the required <id> parameter, but the message is different.

{
    "message": "Forbidden"
}
---

- if you don't use the <id> parameter

{
    "message": "Missing Authentication Token"
}

404 Make sure you have a valid Payment Id

{
    "error": "Not Found"
}

Cancel a Payment

POST /payments/<id>/cancel

Cancel a payment that was previously pre-authorised.

This action is only possible on Payments that we're created with the option cardCaptureMode = MANUAL and have the Status AUTHORISED

Path Parameters

Name	Type	Description
id	string	ID of the previously created payment

Headers

Name	Type	Description
x-api-key	string	Your API key

200

{
    "amount": 20.01,
    "currency": "EUR",
    "createdAt": "2021-06-24T08:34:30.874Z",
    "customerInformation": {},
    "id": "01F8YJG175R7JP223G76N7X75N",
    "merchantReference": null,
    "merchantUrls": {
        "callback": "https://api.exampleshop.com/callback",
        "cancelRedirect": "https://exampleshop.com/cancel",
        "failureRedirect": "https://exampleshop.com/failure",
        "successRedirect": "https://exampleshop.com/success"
    },
    "amountDetails": {
        "tax": 0,
        "shipping": 10,
        "subtotal": 10.01
    },
    "prescriptionRequired": false,
    "status": "INITIAL",
    "updatedAt": null
}

403 Make sure you specify a valid x-api-key header. You can also encounter this error code in case you don't use the required <id> parameter, but the message is different.

{
    "message": "Forbidden"
}
---

- if you don't use the <id> parameter

{
    "message": "Missing Authentication Token"
}

404 Make sure you have a valid Payment Id

{
    "error": "Not Found"
}

Upload Document

POST /payments/<id>/document/<type>

Upload a document related to a specific Order Payment.

Path Parameters

Name	Type	Description
type	string	Can be one of: OTHER, INVOICE, PRESCRIPTION, CERTIFICATE, TEST_RESULT - if not specified, the default value is: OTHER
id	string	ID of the previously created payment

Headers

Name	Type	Description
x-api-key	string	Your API Key
Content-Type	string	application/pdf

Request Body

Name	Type	Description
body	object	The pdf of the invoice you want to upload

204

400 Make sure the file you upload is a valid pdf and that "Content-Type" header is set to "application/pdf".

- if file is not a valid pdf
{
    "error": "Uploaded file's MIME type does not match the type in the 'Content-Type'"
}
---

- if "Content-Type" header has a value other than "application/pdf"
{
    "error": "Content-Type must be one of the following values: application/pdf"
}

import axios from 'axios'

const HIDIRECT_BASE_URL = "<HIDIRECT_BASE_URL>"
const file = fs.readFileSync('/path/to/file'); 
const API_KEY = "<YOUR_API_KEY>"

axios.post(
  `${HIDIRECT_BASE_URL}/payments/<id>/invoice`,
  data: file,
  {
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/pdf"
    }
  })
  .then((response) => {
      console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
      console.log(error);
  });

Entity Definitions

A payment represents the user's intent to pay for a purchase. A payment can be used to initialise the Checkout flow, therefore allowing a hi.health user to confirm a transaction. Once a payment is confirmed, it will require an invoice to be uploaded for fully processing the reimbursement claim with the user's insurance.

Payment

Property Name	Property Type	Description
id	string	Primary key, automatically assigned when the payment is created
amount	Amount	Contains total payment amount with a breakdown that provides details.
merchantReference	string	Identifier from another system, e.g. used to reference the order in your database.
merchantUrls	MerchantUrls	Contains URLs to send callbacks and redirect the user.
status	INITIAL | CLAIMED | SETTLED|DENIED | PENDING	Describes the current status of the payment. INITIAL: The payment was created. CLAIMED: The payment was claimed by a user logging into the checkout flow. SETTLED: The payment was fulfilled by hi.health DENIED: The payment was denied by hi.health PENDING : The payment is still being processed

MerchantUrls

Property name	Property type	Description
callback (optional)	string	This webhook will be used to keep your backend up to date with status updates (payment claimed, payment cancelled, ...).
successRedirect	string	The user will be redirected to this URL once the payment was successfully confirmed.
failureRedirect	string	The user will be redirected to this URL in case the payment was failed. (Note: This redirect is currently not used by our frontend)
cancelRedirect	string	The user will be redirected to this URL in case the payment was cancelled.

Amount

Property name	Property type	Description
total	number	The amount the user will be charged. Must be a positive integer or a positive float with up to 2 decimal places.
currency	string	The 3 character currency code that identifies the currency. We support only "EUR" or "eur" at the moment.