Skip to main content
Authorize a payment by placing a hold on funds without immediately capturing them. This is useful for pre-authorizations in scenarios like hotel reservations or rental deposits. Use capture() to complete the payment later.

​
Method signature

async authorize(request: AuthorizeRequest): Promise<PaymentResult>

​
Parameters

AuthorizeRequest has an identical shape to ChargeRequest. The only difference is the operation type.
​
body.amount
number
required
Amount to authorize in the smallest currency unit (e.g., cents for USD).
​
body.currency
string
required
ISO 4217 currency code (e.g., "USD", "BRL", "EUR").
​
body.paymentMethod
PaymentMethodInput
required
Payment method information. Can be a tokenized card, raw card data, bank transfer, wallet, PIX, or boleto.
​
body.customer
CustomerInput
Customer billing and contact information.
​
body.description
string
Human-readable description of the authorization.
​
body.metadata
object
Arbitrary key-value pairs forwarded to the payment provider.
​
body.idempotencyKey
string
Unique key to prevent duplicate authorizations when retrying the same request. If the same key is used with different request data, a VaultIdempotencyConflictError will be thrown.
​
body.routing
RoutingPreference
Per-request routing overrides.

​
Returns

​
PaymentResult
object
Normalized payment result with status "authorized" for successful authorizations.

​
Error handling

The authorize() method may throw the following errors:
Thrown when an idempotency key is reused with different request data.
if (existingRecord.payloadHash !== payloadHash) {
  throw new VaultIdempotencyConflictError(
    'Idempotency key was reused with a different payload.',
    { operation, key }
  );
}
Thrown when no eligible provider is found or when routing configuration is invalid.
Provider errors are caught and wrapped in VaultError instances with provider context.

​
Example

// Authorize $500 for hotel stay
const authorization = await client.authorize({
  amount: 50000,
  currency: 'USD',
  paymentMethod: {
    type: 'card',
    token: 'tok_visa'
  },
  customer: {
    email: '[email protected]',
    name: 'Jane Smith'
  },
  description: 'Hotel reservation - Room 305',
  metadata: {
    reservationId: 'res_789',
    checkIn: '2026-03-15',
    checkOut: '2026-03-18'
  },
  idempotencyKey: 'reservation-res_789'
});

console.log(authorization.id); // 'txn_auth_xyz'
console.log(authorization.status); // 'authorized'

// Later, capture the actual charge
const capture = await client.capture({
  transactionId: authorization.id,
  amount: 45000 // Capture $450 (partial capture)
});

​
Implementation details

The authorize operation follows the same flow as charge() (src/client/vault-client.ts:175-208):
  1. Checks for idempotency key and returns cached result if the same request was made previously
  2. Resolves the appropriate payment provider using the same routing logic as charges
  3. Executes the authorization through the selected provider adapter
  4. Normalizes the provider response into a standard PaymentResult format
  5. Records the transaction in the provider index for future capture() or void() calls
  6. Queues transaction report to the platform for analytics
Authorizations typically expire after 7 days, though this varies by provider. Capture the authorization before it expires or the funds will be automatically released. Use void() to explicitly release the hold.
Store the authorization.id to use with capture() for completing the payment or void() for canceling the authorization.

Build docs developers (and LLMs) love

Get started for freeTalk to us