Customer tokens

Paying by transfer in your UI, delivering, releasing, cancelling, disputes and payout accounts are your customer’s decisions. To make those calls from your UI, get a customer token: proof that your customer, not just your platform, is making the request.

Send a code

KetaPay sends a one-time code to the customer’s email, or to their phone (WhatsApp, falling back to SMS).

const otp = await ketapay.customerSessions.create({
  email: 'ada@example.com',
})

Verify it

Your UI collects the code and your server exchanges it for a token.

const { token } = await ketapay.customerSessions.verify(
  otp.id,
  codeTheyTyped,
)

Use it

Send it with your secret key. The libraries put it in the KetaPay-Customer-Token header.

await ketapay.escrows.milestones.release(
  escrowId,
  milestoneId,
  {},
  { customerToken: token },
)

Rules

A token is valid for 15 minutes, only for escrows where that person is the buyer or the seller, and only with the secret key that created it.
KetaPay checks the role: only the buyer releases, only the seller delivers. Anyone else gets 403 customer_not_allowed.
Wrong codes return code_invalid; after too many tries, too_many_attempts. Codes expire (code_expired).
In the sandbox no code is sent and every code is 123456.

Treat a customer token like a password for its 15 minutes. Keep it on your server, never log it, and never pass it to another customer.

Get started

Accept payments

Escrow

Customers

After payment

Integrate

Rules

​Rules

Rules