Core Resources

Payments

A Payment represents a single attempt to move money from a customer to your account. Payments can be captured immediately, held, partially captured, or refunded.

Creating a payment

Provide an amount in the smallest currency unit (cents for USD) and a payment source — a tokenized card, saved customer, or Checkout Session.

create.ts

const payment = await ep.payments.create(
  {
    amount: 4999,
    currency: "usd",
    source: "tok_visa",
    capture: true,
    description: "Order ord_18cQX",
    metadata: { order_id: "ord_18cQX" },
  },
  { idempotencyKey: "ord_18cQX-create" },
);

Payment object

Field	Type	Description
`id`	string	Unique identifier (e.g. pay_3Pq8…)
`amount`	integer	Amount in smallest currency unit
`currency`	string	ISO 4217 lowercase
`status`	enum	requires_action, processing, succeeded, canceled, failed
`captured`	boolean	Whether funds have been moved
`refunded_amount`	integer	Cumulative amount refunded

Holds and partial captures

Set capture: false to authorize a hold without moving money. Capture later with up to the original authorized amount.

capture.ts

// Authorize $50, capture $42 once the order ships
const auth = await ep.payments.create({
  amount: 5000, currency: "usd", source: "tok_visa", capture: false,
});

await ep.payments.capture(auth.id, { amount_to_capture: 4200 });

Refunds

refund.ts

await ep.refunds.create({
  payment: "pay_3Pq8...",
  amount: 1000, // optional — omit for full refund
  reason: "requested_by_customer",
});

Errors

Errors are returned as a JSON object with type, code, and a human-readable message.

error.json

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "decline_code": "insufficient_funds",
    "message": "Your card has insufficient funds.",
    "param": "source"
  }
}