Authorizations

An authorization is a hold on funds you can later capture in part or in full. Use it for marketplaces, hotels, rentals, or any flow where the final amount isn't known when the customer pays.

Methods

easy.listAuthorizations(params?);                   // GET    /authorizations
easy.getAuthorization(authorizationId);             // GET    /authorizations/:id
easy.captureAuthorization(authorizationId, amount); // POST   /authorizations/:id/capture
easy.voidAuthorization(authorizationId);            // POST   /authorizations/:id/void

const auths = await easy.listAuthorizations({ limit: 25 });
const { data: auth } = await easy.getAuthorization(auths.data[0].id);

// Capture a portion of the held amount:
await easy.captureAuthorization(auth.id, 7500); // smallest currency unit

// Or release the hold without capturing:
await easy.voidAuthorization(auth.id);

There is no createAuthorization method on the SDK — authorizations are produced by upstream charge APIs (auth-and-capture flows initiated through checkout or the embedded checkout) rather than created directly.

captureAuthorization requires the amount to be ≤ auth.amount_requested. Capturing 0 is not permitted; void instead.

Object shape

AuthorizationData:

Field	Type	Notes
`id`	`string`
`amount` / `amount_requested`	`number`	Captured amount and original hold, smallest currency unit.
`currency`	`string`	ISO 4217.
`state`	`"PENDING" \| "SUCCEEDED" \| "FAILED" \| "VOIDED" \| "CAPTURED"` (or string)
`source` / `destination` / `merchant`	`string \| null`
`failure_code` / `failure_message`	`string \| null`	Populated on `FAILED`.
`trace_id`	`string \| null`
`tags`	`Record<string, string> \| null`
`expires_at`	`string \| null`	After this, the network releases the hold automatically.
`captured_at` / `voided_at`	`string \| null`

Examples

Capture less than the original hold

await easy.captureAuthorization(authId, finalCartTotalCents);

Auto-void expiring holds

const stale = (await easy.listAuthorizations({ limit: 100 })).data.filter(
  (a) => a.state === "PENDING" && a.expires_at && Date.parse(a.expires_at) < Date.now(),
);
for (const a of stale) await easy.voidAuthorization(a.id);

React to an authorization webhook

if (event.type === "authorization.updated") {
  const auth = event.data as { id: string; state: string };
  if (auth.state === "SUCCEEDED") {
    await easy.captureAuthorization(auth.id, finalAmountCents);
  }
}