@coherentx/coherent v0.0.47

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

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: "support@coherenthealthcare.com", //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: "support@coherenthealthcare.com", //optional
    phone: "+44...", //optional
    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.