Skip to main content
Capture funds from a previously authorized transaction. This completes a two-step payment flow started with authorize(). You can capture the full authorized amount or a partial amount.

​
Method signature

async capture(request: CaptureRequest): Promise<PaymentResult>

​
Parameters

​
body.transactionId
string
required
The transaction ID returned from a prior authorize() call. This identifies which authorization to capture.
​
body.amount
number
Partial capture amount in smallest currency unit. Omit this parameter to capture the full authorized amount.
​
body.idempotencyKey
string
Unique key to prevent duplicate captures when retrying the same request.

​
Returns

​
PaymentResult
object
Normalized payment result with status "completed" for successful captures.

​
Error handling

The capture() method may throw the following errors:
Thrown when an idempotency key is reused with different request data.
Thrown when the provider for the original transaction cannot be found.
// src/client/vault-client.ts:491-495
if (!fallbackProvider) {
  throw new VaultRoutingError(
    'No configured providers are available for transaction lookup.'
  );
}
The provider may return errors such as:
  • Authorization not found
  • Authorization already captured
  • Authorization expired
  • Capture amount exceeds authorized amount

​
Example

// First, create an authorization
const authorization = await client.authorize({
  amount: 50000,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  idempotencyKey: 'auth-order-123'
});

// Later, capture the full amount
const capture = await client.capture({
  transactionId: authorization.id,
  idempotencyKey: 'capture-order-123'
});

console.log(capture.status); // 'completed'
console.log(capture.amount); // 50000

​
Implementation details

The capture operation (src/client/vault-client.ts:210-244):
  1. Looks up the provider that handled the original authorization using the transaction index
  2. Falls back to the first configured provider if the transaction is not found in the index
  3. Executes the capture through the provider adapter
  4. Normalizes the provider response into a standard PaymentResult format
  5. Records the capture transaction in the provider index
  6. Queues transaction report to the platform for analytics
The capture uses the same provider that processed the original authorization. Provider selection is based on transaction lookup, not routing rules.
Not all providers support partial captures or multiple captures. Check your provider’s documentation for specific limitations.
Use partial captures to adjust the final charge based on actual usage, such as in hotel stays, car rentals, or pay-per-use services.

Build docs developers (and LLMs) love

Get started for freeTalk to us