Server SDK

`payfer.charge()`

Updated Oct 25, 2026

Charges a connected user from your server, within what’s left of their allowance this month. Call it only from your server; it needs your secret key.

payfer.charge(params: ChargeParams): Promise<Payment>

Parameters

paymentUserIdstring · required: The app-specific ID returned by verifyConnection().
amountstring · required: A decimal string, for example "0.01". At least $0.005, and it must fit within the user’s remaining allowance.
idempotencyKeystring · required: A key for this operation. Repeating it returns the existing payment instead of charging again.

Returns

A Payment. Amounts are decimal strings.

id: The payment ID, used for refunds.
amount: Total debited from the user.
fee: Payfer’s fee for this charge, set by your application’s pricing tier and deducted from the customer price.
developerProceeds: amount minus fee.
status: succeeded, pending, failed, partially_refunded or refunded.
receiptUrl: Explorer page for the settlement transaction, once submitted.

Errors

Thrown as a PayferError with a stable code.

invalid_amount: The amount is malformed or below the $0.005 minimum.
funding_required: The user’s balance is too low. Ask them to add funds.
allowance_exceeded: The charge would go over this month’s allowance.
approval_revoked: The user revoked your application’s allowance.
payment_pending: Settlement hasn’t finished. Retry with the same idempotency key to reconcile.
rate_limited: Too many charges for your app. Wait for the Retry-After header.

Example

server.ts

try {
  const payment = await payfer.charge({
    paymentUserId: user.paymentUserId,
    amount: "0.01",
    idempotencyKey: operationId,
  });
} catch (err) {
  if (err.code === "funding_required") {
    // Ask the user to add funds, then retry.
    return askToAddFunds(user);
  }
  throw err;
}