Coherent API
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: "[email protected]", //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: "[email protected]", //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
)
Charge an on-demand payment plan
await coherent.paymentPlans.charge(
plan.uuid,
{ amount: 2000, reference: "INVOICE-1234" } // optional
)
Recover a Direct Debit plan that failed collection for insufficient funds (PaymentPlanStatus.InsufficientFunds) — resumes the plan and immediately charges the current instalment in one call:
const { transactionUuid } = await coherent.paymentPlans.resumeAndCharge(
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')