charge()

Execute a one-step payment charge that immediately captures funds from the customer’s payment method. The charge is routed to the appropriate payment provider based on your configured routing rules.

Method signature

async charge(request: ChargeRequest): Promise<PaymentResult>

Parameters

body.amount

number

required

Amount in the smallest currency unit (e.g., cents for USD, centavos for BRL).

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.

Show Payment method types

card (tokenized)

object

{ type: 'card', token: string }

card (raw)

object

{
  type: 'card',
  number: string,
  expMonth: number,
  expYear: number,
  cvc: string
}

bank_transfer

object

{ type: 'bank_transfer', bankCode: string, accountNumber: string }

wallet

object

{ type: 'wallet', walletType: string, token: string }

pix

object

{ type: 'pix' }

boleto

object

{ type: 'boleto', customerDocument: string }

body.customer

CustomerInput

Customer billing and contact information.

Show Customer properties

string

Customer email address.

name

string

Customer full name.

phone

string

Customer phone number.

document

string

Tax ID or national document number (e.g., CPF in Brazil).

address

AddressInput

Customer billing or shipping address with fields: line1, line2, city, state, postalCode, country (ISO 3166-1 alpha-2).

body.description

string

Human-readable description of the charge.

body.metadata

object

Arbitrary key-value pairs forwarded to the payment provider.

body.idempotencyKey

string

Unique key to prevent duplicate charges 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.

Show Routing properties

provider

string

Force routing to a specific provider, bypassing all routing rules.

exclude

string[]

Provider names to exclude from routing consideration.

Returns

PaymentResult

object

Normalized payment result containing transaction details and routing information.

Hide properties

string

required

VaultSaaS-normalized transaction identifier.

status

PaymentStatus

required

Payment status: "completed", "pending", "requires_action", "declined", "failed", "cancelled", or "authorized".

provider

string

required

Name of the provider that processed the transaction (e.g., "stripe", "adyen").

providerId

string

required

Provider’s own identifier for this transaction.

amount

number

required

Amount in smallest currency unit.

currency

string

required

ISO 4217 currency code.

paymentMethod

object

required

Snapshot of the payment method used.

Show properties

type

string

required

Payment method type.

last4

string

Last 4 digits of card or account number.

brand

string

Card brand (e.g., "visa", "mastercard").

expiryMonth

number

Card expiry month.

expiryYear

number

Card expiry year.

customer

object

Customer information returned by the provider.

Show properties

string

Provider’s customer identifier.

string

Customer email address.

metadata

object

required

Merged metadata from the request and provider response.

routing

object

required

Information about how the provider was selected.

Show properties

source

string

required

Routing source: "local" or "platform".

reason

string

required

Reason for provider selection (e.g., "forced provider", "fallback provider").

createdAt

string

required

ISO 8601 timestamp when the transaction was created.

providerMetadata

object

required

Raw provider-specific fields not mapped to the normalized schema.

Error handling

The charge() method may throw the following errors:

VaultIdempotencyConflictError

Thrown when an idempotency key is reused with different request data.

// src/client/vault-client.ts:612-619
if (existingRecord.payloadHash !== payloadHash) {
  throw new VaultIdempotencyConflictError(
    'Idempotency key was reused with a different payload.',
    { operation, key }
  );
}

VaultRoutingError

Thrown when no eligible provider is found or when routing configuration is invalid.

// src/client/vault-client.ts:428-430
throw new VaultRoutingError(
  'No eligible provider found after exclusions.'
);

Provider-specific errors

Provider errors are caught and wrapped in VaultError instances with provider context. See src/client/vault-client.ts:636-652.

Example

const result = await client.charge({
  amount: 5000,
  currency: 'USD',
  paymentMethod: {
    type: 'card',
    token: 'tok_visa'
  },
  customer: {
    email: '[email protected]',
    name: 'John Doe'
  },
  description: 'Order #1234',
  idempotencyKey: 'order-1234'
});

console.log(result.status); // 'completed'
console.log(result.provider); // 'stripe'
console.log(result.id); // 'txn_abc123'

Implementation details

The charge operation:

Checks for idempotency key and returns cached result if the same request was made previously
Resolves the appropriate payment provider using routing rules (src/client/vault-client.ts:375-437)
Executes the charge through the selected provider adapter
Normalizes the provider response into a standard PaymentResult format
Records the transaction in the provider index for future lookups
Queues transaction report to the platform for analytics (if configured)

The charge method supports automatic idempotency to safely retry failed requests. Store the id from the response to reference this transaction in future operations like refunds.

Client

Payment Operations

Types

Adapters

Method signature

Parameters

Returns

Error handling

Example

Implementation details

Build docs developers (and LLMs) love

Client

Payment Operations

Types

Adapters

​Method signature

​Parameters

​Returns

​Error handling

​Example

​Implementation details

Build docs developers (and LLMs) love

Method signature

Parameters

Returns

Error handling

Example

Implementation details