Payments.lk
මෙම පිටුව දැනට ඉංග්‍රීසියෙන් පමණි. අයදුම්පත, මිල ගණන් සහ මුල් පිටුව සිංහල සහ දෙමළ භාෂාවලින් ලබා ගත හැක.

Developers / Guides / Pre-authorisation

Pre-authorisation: hold now, capture later.

Authorise a customer's card for an amount and take nothing. Then capture all of it, capture part of it, or release it, once, before the hold's cut-off. You pay fees only on what you capture.

Window
7 days, less 2 hours
Actions per hold
One
Test mode
Every account

1How a hold works

A hold (a pre-authorisation) asks the customer’s bank to set an amount aside on their card and takes nothing. You create a checkout, or charge a saved card, with captureMethod: "manual". The customer pays on the same hosted checkout as any payment and passes their bank’s check; the payment then reads requires_capture and you receive payment.authorized.

Then you do one thing with it, before its cut-off: capture all of it, capture part of it (send amountCents), or release it. Fees are charged on what you capture, at your plan’s card rate, and a released hold costs nothing. A captured payment is an ordinary payment from then on, and refunds like one.

2Where holds work

Test keys place holds on every account, so you can build and try everything here before you go live. A live hold needs three things: your Visa and Mastercard payments processed through Seylan Bank; pre-authorisation switched on for your account at Payable, which Payments.lk does for you once Payable has set up the hosted checkout it needs; and your account’s Payable key carrying the permission holds need, which Payments.lk adds for you. Payments.lk checks these with Payable about every fifteen minutes. Live holds through Commercial Bank and Nations Trust Bank are not available yet.

A hold that cannot be placed is refused before anything is made, with 409 and the reason holds_unavailable; its message, and the dashboard’s Pre-authorisations page, say which condition is missing. Holds are for Visa and Mastercard, on checkouts opened on the web and on saved card charges from your server, for now: the mobile SDKs do not yet read a held checkout’s return. Payment links, checkout pages, invoices and subscriptions take the money at once.

Both libraries have holds: lk.payments.capture() and lk.payments.release() in Node.js, $payments->payments->capture() and $payments->payments->release() in PHP. Every example below uses a sandbox key; set the client up once:

import { PaymentsLk } from "@payments-lk/node";

const lk = new PaymentsLk(process.env.PAYMENTS_LK_SECRET_KEY); // sk_test_... while you build

3Place a hold at checkout

Create the checkout as for any payment, with captureMethod set to manual, and send the customer to its url. Take the amount from your own records, never from the browser. The checkout expires 30 minutes after it is made unless you send expiresInMinutes.

A hold cannot keep the card: a checkout with saveCard and captureMethod manual is refused. To hold a card the customer already saved, see Hold a saved card.

app.post("/bookings/:id/deposit", async (req, res) => {
  const booking = await bookings.find(req.params.id); // the amount comes from your records

  const checkout = await lk.checkouts.create(
    {
      amountCents: booking.depositCents, // Rs. 25,000.00 is 2500000
      description: booking.summary,
      reference: "booking-" + booking.id,
      customer: { name: booking.guestName, email: booking.guestEmail },
      successUrl: "https://yourhotel.lk/bookings/" + booking.id,
      cancelUrl: "https://yourhotel.lk/bookings/" + booking.id,
      captureMethod: "manual", // authorise the card now, take the money later
    },
    { idempotencyKey: "booking-" + booking.id },
  );

  res.redirect(303, checkout.url);
});

4Webhooks: authorized, captured, released

Verify each webhook as for any payment, then act on the hold’s three events. payment.authorized means the card is held: the payment reads requires_capture, and its authorization carries amountCents, what was held, and expiresAt, the cut-off for your capture. Keep the payment id against your order.

payment.captured brings the payment succeeded, with amountCents and the fee for what you captured. payment.released brings it canceled, nothing taken, with authorization.releaseReason: merchant when you released it, expiry when its window ended, payable when Payable reported it released.

If the card is declined on Payable’s page, Payable sends no word: the customer can try again until the checkout expires, and the expiry then closes the payment, so an order with no payment.authorized by the checkout’s expiresAt is not held. A saved card hold that fails, or a failed 3D Secure check, is payment.failed. Events can arrive more than once: make every handler safe to run twice.

// In the same webhook handler, after lk.webhooks.constructEvent has verified the signature.
switch (event.type) {
  case "payment.authorized":
    // The card is held (status requires_capture). Nothing is taken yet.
    await bookings.markHeld(event.data.reference, event.data.id, event.data.authorization.expiresAt);
    break;
  case "payment.captured":
    // The money is taken: amountCents and the fee are for what you captured.
    await bookings.markPaid(event.data.reference, event.data.amountCents);
    break;
  case "payment.released":
    // Nothing was taken. authorization.releaseReason says why: merchant (you released it),
    // expiry (its window ended) or payable (Payable reported it released).
    await bookings.markReleased(event.data.reference, event.data.authorization.releaseReason);
    break;
  case "payment.failed":
    // Not held: a saved card hold that failed, or a failed 3D Secure check. A customer who then
    // tries again on the same checkout and is authorised brings payment.authorized after it.
    await bookings.markNotHeld(event.data.reference);
    break;
}

5Verify the hold on your return page

Once your endpoints have answered payment.authorized, the checkout tells the customer Card authorised and sends them to successUrl with checkout=<id>&status=authorized added. Do not wait for the webhook and do not trust the URL: read that checkout from your server with GET /v1/checkouts/{id}. A held card reads payment.status requires_capture, with authorization.status authorized.

Show the order as confirmed, not as paid: nothing has been taken yet.

app.get("/bookings/:id", async (req, res) => {
  const booking = await bookings.find(req.params.id);

  // The customer comes back with ?checkout=<id>&status=authorized. The URL proves nothing: read the checkout itself.
  if (!booking.paymentId && typeof req.query.checkout === "string") {
    const checkout = await lk.checkouts.retrieve(req.query.checkout).catch(() => null);
    const payment = checkout?.payment;
    if (payment?.reference === "booking-" + booking.id && payment.status === "requires_capture") {
      // Held, not paid. The webhook's own call, safe to run twice.
      await bookings.markHeld(payment.reference, payment.id, payment.authorization?.expiresAt);
    }
  }
  res.render("booking", { booking: await bookings.find(booking.id) });
});

6Capture all of it

When you know the customer owes the whole amount, capture without amountCents. The answer is the payment with authorization.status capture_requested while the bank confirms it; payment.captured follows, and the payment then reads succeeded.

// The guest stayed as booked: take everything that was held.
const payment = await lk.payments.capture(
  booking.paymentId,
  {}, // no amountCents: all of it
  { idempotencyKey: "booking-" + booking.id + "-capture" },
);
// authorization.status is capture_requested until the bank confirms: payment.captured follows.

7Capture part of it

Send amountCents to take less than was held: a deposit less what came back, a stay shorter than booked. It can be anything up to authorization.amountCents. The rest of the hold is released with the capture and can never be captured later. Fees are charged on the amount you captured only.

// At check out: take what the guest owes, up to what was held.
const payment = await lk.payments.capture(
  booking.paymentId,
  { amountCents: 1800000 }, // Rs. 18,000.00 of the Rs. 25,000.00 held. Leave it out to take it all.
  { idempotencyKey: "booking-" + booking.id + "-capture" },
);
// authorization.status is capture_requested until the bank confirms: payment.captured follows.

8Release it

Release a hold you will not take: nothing is taken, the customer’s bank frees the amount, and a released hold costs you nothing. The answer reads authorization.status release_requested until the bank confirms; payment.released follows with releaseReason merchant.

// The guest cancelled in time: take nothing.
const payment = await lk.payments.release(booking.paymentId, {
  idempotencyKey: "booking-" + booking.id + "-release",
});
// authorization.status is release_requested until the bank confirms: payment.released follows.

9The window and automatic release

Payable keeps a hold for 7 days. Payments.lk closes the window 2 hours before that, to stay inside Payable’s limit, and gives you the exact cut-off as authorization.expiresAt. A capture or release after it is refused with not_capturable.

A hold you neither captured nor released by then is released by Payments.lk once the cut-off passes: payment.released arrives with authorization.status expired and releaseReason expiry. Nothing is taken from the customer. Read the payment at any time to see where a hold stands.

// Where a hold stands, after a timeout or at any time:
const payment = await lk.payments.retrieve(booking.paymentId);

// payment.authorization.status is one of:
//   authorized         held: capture or release it before authorization.expiresAt
//   capture_requested  a capture on its way to the bank: payment.captured follows
//   release_requested  a release on its way to the bank: payment.released follows
//   captured           done: payment.amountCents was taken
//   released           done: nothing was taken (releaseReason merchant or payable)
//   expired            done: the window ended, nothing was taken (releaseReason expiry)
// authorization.failureMessage says why the last capture or release was refused.
// Capture or release by authorization.expiresAt: 7 days after the hold, less 2 hours.

10One action per hold, and safe retries

Each hold takes one action: one full capture, one partial capture or one release. A released hold cannot be captured, and a captured one cannot be captured again.

Send every capture and release with an Idempotency-Key made from your own record, such as booking-5521-capture: a retry after a timeout gets the first answer back and never asks twice. While a capture or release is being confirmed with the bank the payment says so, and nothing more can be asked of the hold: wait for the webhook, or read the payment. If Payable refuses one outright, the hold goes back to authorized with the reason in authorization.failureMessage, and you can try again or do the other. If Payable answers that the hold has already expired on its side, it ends here too: payment.released follows with releaseReason expiry.

11Hold a saved card

The same captureMethod: "manual" on POST /v1/cards/{id}/charge places a hold on a card the customer kept, without them present: a deposit from a returning customer, say. The answer is usually processing; payment.authorized follows once the card is held, and you capture or release it as above. Hold only what the customer agreed to.

Saved cards need Payable’s Advanced plan for live charges; see the tokenised payments guide.

const payment = await lk.cards.charge(
  customer.cardId,
  { amountCents: 500000, description: "Bicycle hire deposit, 3 days", reference: "hire-3307", captureMethod: "manual" },
  { idempotencyKey: "hire-3307" },
);
// Usually processing: payment.authorized follows once the card is held, or payment.failed.

12Errors

A refusal carries a code, a reason, a sentence you can show and a docUrl. Match on the code and the reason, never on the sentence. These are the two a hold adds; a request with saveCard and captureMethod manual together fails validation before either.

holds_unavailable409 CONFLICT
A payment with captureMethod manual asks Payable to authorise the card without taking the money. Test mode takes holds for every account. A live hold needs all of these: your Visa and Mastercard payments are processed through Seylan Bank (other banks do not take holds yet); Payable has set up the hosted checkout holds need on your account; pre-authorisation is switched on for your account at Payable, which Payments.lk does for you; and your account's Payable key carries the permission holds need, which Payments.lk adds for you. Payments.lk checks these with Payable about every fifteen minutes and refuses a live hold while any is missing, or while live holds are paused on Payments.lk; the message says which. A hold is also refused on a checkout that keeps the card and on a payment for an invoice.
Fix: Use a test key to try holds. For a live payment send captureMethod automatic until the message no longer appears. When it says Payments.lk is switching holds on, try again in a few minutes; otherwise contact Payments.lk support.
not_capturable409 CONFLICT
Only a payment that reads requires_capture with authorization.status authorized can be captured or released, and a capture takes at most authorization.amountCents. A hold already captured, released or expired, or one whose capture or release is on its way, cannot be asked again.
Fix: Read the payment: authorization.status says where the hold is. Wait for payment.captured or payment.released after a request.

Every other error is on the errors page.

Errors
{
  "code": "CONFLICT",
  "reason": "holds_unavailable",
  "message": "A hold cannot be placed on this payment.",
  "docUrl": "https://payments.lk/developers/errors#holds_unavailable",
  "traceId": "7d2e9c41-3b8a-4f6e-a1c5-0e9b8d7f6a52"
}

13Refunds after a capture

A captured hold is a payment that succeeded, for what was captured. Refund it like any other payment, in full or in part, up to what was captured. A released or expired hold took nothing, so there is nothing to refund.

// After payment.captured the payment reads succeeded, for what was captured, and refunds like any other.
const refund = await lk.refunds.create(
  { paymentId: booking.paymentId, amountCents: 300000, reason: "Late check out fee waived" }, // Rs. 3,000.00 of the Rs. 18,000.00
  { idempotencyKey: "booking-" + booking.id + "-refund-1" },
);

14From the dashboard

Pre-authorisations lists every hold, live and sandbox apart, with the time left, and captures all or part of a hold, or releases it. Tokenised payments places a hold on a saved card. In live mode, placing a hold and capturing ask for your password and a one time code; releasing does not, since it takes nothing. The owner, admins and support can do each of these.

15Test in the sandbox

With a sandbox key (sk_test_), place a hold at a checkout and pay on Payable’s sandbox page with a Visa or Mastercard test card and CVV 100. The expiry decides the answer, and on the 3D Secure page you choose the authentication result. Then capture or release it from your code or the dashboard, and watch the events arrive at your endpoint or the dashboard’s test inbox. No money moves. Sandbox checkouts open once you have submitted your application, when Payable’s sandbox has a test merchant for you.

  • 5123 4500 0000 0008 Mastercard
  • 2223 0000 0000 0007 Mastercard
  • 4508 7500 1574 1019 Visa
  • Expiry 01/39 Approved
  • Expiry 05/39 Declined
  • Expiry 04/27 Expired card

Payments.lk ගෙන් අසන්න

මෙම වෙබ් අඩවියේ පිටුවලින් ලැබෙන පිළිතුරු.

Pre-authorisation guide · Payments.lk