@coherentx/coherent

Coherent API

• Coherent API
  • Installation
  • Usage
    • Payments
      • Create a Transaction (aka Payment)
      • Refunds
      • Terminals
      • Transaction Status Webhooks
    • Recurring Payments (aka Payment Plans)
      • Link Payment Plan to Transactions
    • Partner Merchant Management
      • API Key Management
      • Webhook URL Management

Installation

Install the API using the following command

npm install coherent

Add --save if building a deployable.

Usage

Import and initialise the connection

import {Coherent} from "coherent";

const coherent = new Coherent({
    environment: "TEST", // or "PRODUCTION"
    token: process.env.COHERENT_TOKEN
})

Payments

Create a Transaction (aka Payment)

Create a payment link, notifying an email or phone number optionally

const transaction = await coherent.transactions.create({
    amount: 1000, // The amount in the smallest regular unit, e.g. pennies (£10 = 1000)
    name: `John Smith`, // The name of the patient,
    note: "A test", //optional, what this transaction involves
    email: "[e-mail]", //optional
    emailNotify: true, //optional, `email` receives payment request notification
    patientNote: "Thanks for your payment", //optional, a note visible to the patient during payment
    phone: "+44...", //optional
    smsNotify: true, //optional, `phone` receives SMS payment request notification
    successUrl: "https://example.com/success", //optional, where to redirect to after successful payment
    failureUrl: "https://example.com/failure", //optional, where to redirect to after rejected payment
})

console.log(transaction.uuid)
console.log(transaction.status)
console.log(transaction.paymentUrl)

Get a payment

const transaction = await coherent.transactions.get(
    transaction.uuid
)

Void a payment

await coherent.transactions.updateStatus(
    transaction.uuid,
    'void'
)

#### Refunds

```js
await coherent.transactions.refund({
    transactionUuid: transaction.uuid,
    amount: 100,
    reason: 'Anything'
})

Terminals

List terminals

await coherent.terminals.list()

Name the terminal

await coherent.terminals.rename({
    terminalId: '<TYPE>-123455678',
    name: 'The Trusty Terminal'
})

Send for payment

await coherent.terminals.setTransaction({
    terminalId: '<TYPE>-123455678',
    transactionUuid: 'abcd-1234'
})

Clear the terminal

await coherent.terminals.clearTransaction({
    terminalId: '<TYPE>-123455678'
})

Transaction Status Webhooks

See Transaction Status Webhooks in the main documentation

Recurring Payments and Holds (aka Payment Plans)

Create a Payment Plan, currently limited to monthly recurring payments, or payment holds for charging on demand

const plan = await coherent.paymentPlans.create({
    amount: 1000, // The amount in the smallest regular unit, e.g. pennies (£10 = 1000)
    name: `John Smith`, // The name of the patient,
    note: "A test", //optional, what this transaction involves
    startDate: new Date("2025-01-01"), //required except if creating an on_demand plan
    endDate: new Date("2025-03-01"), //optional, the date of the last payment occurrence
    transactionReference: "Invoice123456", //optional, but recommended, and unique per clinic. Transactions relating to this payment plan will have this set
    email: "[e-mail]", //optional
    emailNotify: true, //optional, defaults to true if email is provided
    phone: "+44...", //optional
    smsNotify: true, //optional, defaults to true if phone is provided
    type: "recurring", //optional, defaults to recurring, can be on_demand
    method: "direct_debit", //optional, defaults to direct_debit, can be card
    successUrl: "https://app.coherenthealthcare.com/receipt?token=example", //optional, where the user is sent after successful payment. NOTE: only supported for type = card
})

console.log(plan.uuid)
console.log(plan.status)
console.log(plan.paymentUrl)

Get a payment plan

const plan = await coherent.paymentPlans.get(
    plan.uuid
)

Pause or cancel a payment plan

await coherent.paymentPlans.setStatus(
    plan.uuid,
    PaymentPlanStatus.Void 
    // OR PaymentPlanStatus.Paused
    // OR PaymentPlanStatus.Resumed
)

You can set the second parameter to one of:

• Void: Cancels the payment plan and associated schedule
• Paused: Pauses the payment plan's schedule, scheduled occurences that fall when the plan is paused are skipped forever
• Resumed: Resumes the payment plan's schedule, restoring it to the state it was in before it became paused or errored.

Resend a notification

await coherent.paymentPlans.notify(
    plan.uuid
)

Execute an on-demand payment plan

await coherent.paymentPlans.execute(
    plan.uuid
)

Link Payment Plan to Transactions

Each recurrence of a payment plan will create a Transaction, and in turn trigger a Transaction webhook as usual.

To link transactions generated to payment plans, set the transactionReference on payment plan creation.

You will not have a record of the transaction with the given UUID when the webhook is received, but when you get the transaction, it should contain the reference set earlier at {}.paymentPlan.transactionReference.

Partner Merchant Management

Partners can manage their merchants, including listing merchants, managing API keys, and configuring webhook URLs.

Note: An API key and webhook URL are created automatically during onboarding (startOnboarding). The endpoints below are only needed if you want to rotate keys or change the webhook URL after onboarding.

List all merchants belonging to this partner

const merchants = await coherent.merchants.listMerchants()
// Returns: [{ uuid, name, email, phone?, onboarded }]

API Key Management

Create a new API key for a merchant

const result = await coherent.merchants.createApiKey('merchant-uuid')
console.log(result.apiKey) // Store this securely — it cannot be retrieved again

List existing API keys for a merchant

const keys = await coherent.merchants.listApiKeys('merchant-uuid')
// Returns: [{ uuid, createdTime }]

Webhook URL Management

Get the current webhook URL for a merchant

const webhook = await coherent.merchants.getWebhookUrl('merchant-uuid')
console.log(webhook.webhookUrl) // null if not set

Update a merchant's webhook URL

await coherent.merchants.updateWebhookUrl('merchant-uuid', 'https://example.com/webhook')