Payments.lk

Developers / Guides / Tokenised payments

Tokenised payments: save once, charge later.

The customer keeps their card on the hosted checkout. You get a card id, never the card number, and charge it later without the customer present, or place a hold on it.

Card numbers on your servers
None
Sandbox
On for every account
Live
Payable's Advanced plan

1How tokenised payments work

The customer pays once on the hosted checkout and chooses to keep their card. Payable keeps the card and gives it a token; you receive a card id, never the card number, and charge it later without the customer present. Card details never touch your servers or ours.

A charge on a saved card is a card payment at your plan’s rate. You can also place a hold on a saved card and capture or release it later, and our subscriptions charge saved cards for you every period.

2Availability and Payable's Advanced plan

Keeping a card at checkout, and charging, listing or removing it later, use Payable’s business key APIs, which only its Advanced plan opens, in the sandbox as well as live. In the sandbox there is nothing to switch on: every sandbox account is on the Advanced plan, so you can keep, charge and remove test cards before you go live.

For live, switch saved cards on in the dashboard under Business settings once your account is live. It moves your account to Payable’s Advanced plan, which carries its own monthly fee and a fee for each card saved; the dashboard shows both before you confirm. Until then a live checkout with saveCard is refused with saved_cards_off. One-time checkouts and payment links work on every plan.

3Save a card at checkout

Set saveCard: true and send the customer’s name and email in customer: Payable needs the full details to keep a card, so this checkout always shows the details form. The checkout offers to keep the card, and nothing is kept unless the customer ticks the box. It works from a website or a mobile app.

A checkout that keeps the card cannot be a hold: saveCard with captureMethod manual is refused.

app.post("/coffee-club/join", requireSignedInCustomer, async (req, res) => {
  const customer = await customers.find(req.user.id); // ruwan@example.lk

  const checkout = await lk.checkouts.create(
    {
      amountCents: 250000, // Rs. 2,500.00, the first month
      description: "First month of your coffee subscription",
      reference: "sub-" + customer.id,
      customer: { name: customer.name, email: customer.email }, // Payable needs the details to keep a card
      saveCard: true, // the checkout asks the customer if they want to keep the card
      successUrl: "https://yourshop.lk/account",
      cancelUrl: "https://yourshop.lk/account",
    },
    { idempotencyKey: "sub-" + customer.id + "-first" },
  );

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

4card.saved and the other card events

After the first payment succeeds you receive card.saved, whose data is the saved card. Keep its id against your customer: it is not a card number and is useless outside your account.

If the payment succeeds but Payable does not keep the card, you receive card.save_failed instead, whose data is the payment (its cardSave is failed): nothing is on file, so ask the customer to save the card again at a new checkout. card.expiring arrives when a card a running subscription is charged to expires at the end of the month; the customer is emailed a link to change it.

// In your webhook handler, after lk.webhooks.constructEvent has verified the signature.
switch (event.type) {
  case "card.saved":
    // event.data is the saved card:
    //   { id: "card_...", customerEmail, scheme, last4, mode, active,
    //     expiry: { month, year },      // when the card itself runs out
    //     paymentId,                    // the payment the customer made when they kept it
    //     consent: { agreedAt, locale, wording } }  // what they agreed to
    await customers.rememberCard(event.data.customerEmail, event.data.id);
    break;
  case "card.save_failed":
    // The payment went through, but the card was not kept. event.data is the payment (cardSave: "failed").
    await customers.askToSaveCardAgain(event.data.customer?.email);
    break;
  case "card.expiring":
    // A card a running subscription is charged to expires at the end of this month.
    // The customer is emailed a link to the customer portal to change it.
    await customers.noteExpiringCard(event.data.customerEmail, event.data.id);
    break;
}

6List and retrieve cards

List the cards your customers kept, newest first, filtered by the email they gave at checkout and paged with limit and cursor. A list leaves out deleted cards; retrieving one by id answers deleted cards too, so you can still say why a charge stopped.

// One page of a customer's cards, newest first.
const page = await lk.cards.list({ customerEmail: "ruwan@example.lk", limit: 1 });

// Or every card, page after page, as you iterate.
for await (const card of lk.cards.listAll({ customerEmail: "ruwan@example.lk" })) {
  console.log(card.id, card.scheme, card.last4, card.expiry);
}

// One card. A card you deleted still reads, so you can say why a charge stopped.
const card = await lk.cards.retrieve("card_g2a1rex14ff7qh2dc6j6qzmq");
// card.consent: { agreedAt, locale, wording }. card.retiredAt: when it was deleted, or null.

7Charge a saved card

Charge only what the customer agreed to. Use one idempotency key per billing period, so a retry never charges twice; the window is 24 hours, so a job that retries later than that should read the payment first. The answer is usually processing, and the outcome arrives as payment.succeeded or payment.failed, with savedCardId on the payment.

Charge in another currency with currency (USD, GBP or EUR) when your account takes it; a card saved on a rupee payment can be charged in dollars.

const payment = await lk.cards.charge(
  customer.cardId,
  { amountCents: 250000, description: "October coffee subscription", reference: "sub-" + customer.id + "-2026-10" },
  { idempotencyKey: "sub-" + customer.id + "-2026-10" }, // one charge per billing period, however often you retry
);
// Usually processing: payment.succeeded or payment.failed follows, with savedCardId on the payment.

8Only the first payment asks the cardholder to authenticate

The customer is present for the first payment and passes their bank’s check there. A later charge is made without them, so nobody can be asked to authenticate: a bank that insists declines it, and the answer is payment.failed. Take the customer back to a checkout to save the card again when that happens.

9Hold a saved card

Send captureMethod: "manual" with the charge to place a hold instead of taking the money: payment.authorized follows once the card is held, and you capture all of it, part of it, or release it. The same rules apply as for any hold, live only where holds are available; see the pre-authorisation 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.

10Delete a card

Delete the card when the customer asks or cancels. It stops working at once and its token is deleted at Payable; deleting a card that is already deleted answers the same card, so a retry is safe. The deleted card still reads, with active false and retiredAt set.

// When the customer removes the card or cancels. It stops working at once.
const card = await lk.cards.delete(customer.cardId);
// card.active is false and card.retiredAt is set; the token is deleted at Payable.
// Deleting a card that is already deleted answers the same card, so a retry is safe.

11Watch the expiry, and card_not_reusable

A card carries the month it runs out in expiry: a charge after that is declined, so ask the customer for a new card before then. A charge refused with the reason card_not_reusable is permanent, never a retry: the card has nothing behind it any more, so send the customer to a new checkout to save one.

12Customers and subscriptions

Our subscriptions keep the card at the first payment and charge it every period, retrying a decline for you. A customer’s defaultCardId is the card their renewals are charged to unless a subscription names its own; a subscription made with cardId, a card the customer already saved with you, charges its first invoice to it at once. Customers change their card in the customer portal.

The libraries do not have subscription methods yet, so this one is shown over HTTP. The subscriptions guide has the whole flow.

Customers and subscriptions
curl https://api.payments.lk/v1/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: member-1042-gym" \
  -d '{
    "customerId": "cus_q8w3n5v1x7c2m9r4t6ya0kzp",
    "priceId": "price_m3v8q1x6c9k2r5t7y0wn4hzp",
    "reference": "member-1042",
    "successUrl": "https://gym.example/welcome",
    "cardId": "card_g2a1rex14ff7qh2dc6j6qzmq"
  }'

13Errors

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 ones saved cards bring:

saved_cards_off409 CONFLICT
The checkout asked to keep the card (saveCard: true), but saved cards are not switched on. They use Payable's Advanced plan.
Fix: Switch saved cards on in the dashboard under Business settings, or send saveCard: false.
card_not_reusable409 CONFLICT
The saved card is missing what the processor needs to charge it again, or it was saved by the local simulator, which Payable cannot charge. This does not change with time, so sending the request again gets the same answer.
Fix: Ask the customer to pay once at a checkout with saveCard: true, then charge the new card id that card.saved sends you.
merchant_not_live409 CONFLICT
A live payment, link, page or saved card setting was asked for before the account was approved and activated, or while it is not active.
Fix: Use a test key until the dashboard says the account is live, then create live keys there.
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.
monthly_limit_reached409 CONFLICT
Each plan takes card payments up to a monthly limit: Starter to the first pricing bracket's ceiling, Growth to the second's. Payments that succeeded this month and payments with the processor now count toward it, and a payment that would take the month past the limit is refused whole. Refunds do not free up room. The limit resets at midnight on the 1st, Sri Lankan time. Test mode has its own count against the same limit.
Fix: Request an upgrade to the next plan in the dashboard (Plans) or with POST /v1/account/upgrade_requests. In test mode, reset the sandbox's usage on the Developers page. Customers are told only that card payments are not available right now.
currency_unavailable409 CONFLICT
Rupees are always available. US dollars, pounds and euros are taken once Payable has set the currency up for the account (a card profile and a limit in it). Test mode takes a currency only where Payable's sandbox holds it for the account.
Fix: Send currency: "LKR", or ask for the currency in the dashboard under Business settings, Currencies: test mode is set up straight away, live once our team approves. GET /v1/account lists the currencies each mode takes.

Every other error is on the errors page.

14From the dashboard

Tokenised payments lists the cards your customers kept, live and sandbox apart, with the charges made on each, and charges a card or places a hold on it. In live mode, charging a card and placing a hold ask for your password and a one time code. The owner, admins and support can do each of these.

15Test in the sandbox

With a sandbox key (sk_test_), create a checkout with saveCard: true, tick the box on Payable’s sandbox page and pay with a test card. The expiry decides the answer. Then charge, hold and delete the card from your code or the dashboard. 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
  • 3718 812455 60002 American Express, CVV 1000
  • 3600 0000 0000 0123 Diners Club
  • 6445 6445 6445 6460 Discover
  • Expiry 01/39 Approved
  • Expiry 05/39 Declined
  • Expiry 04/27 Expired card

Ask Payments.lk

Answers from the pages on this site.

Tokenised payments guide · Payments.lk