Payments

Endpoints

Create a Payment

POST /payments

Create a payment

Headers

NameTypeDescription

x-api-key

string

Your API key

Content-Type

string

application/json

Request Body

NameTypeDescription

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.

{
    "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"
}
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

NameTypeDescription

id

string

ID of the previously created payment

Headers

NameTypeDescription

x-api-key

string

Your API key

{
    "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
}
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

NameTypeDescription

id

string

ID of the previously created payment

Headers

NameTypeDescription

x-api-key

string

Your API key

{
    "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
}

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

NameTypeDescription

id

string

ID of the previously created payment

Headers

NameTypeDescription

x-api-key

string

Your API key

{
    "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
}

Upload Document

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

Upload a document related to a specific Order Payment.

Path Parameters

NameTypeDescription

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

NameTypeDescription

x-api-key

string

Your API Key

Content-Type

string

application/pdf

Request Body

NameTypeDescription

body

object

The pdf of the invoice you want to upload

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.

Last updated