Payment Request Types

Payment request types define the shape of data you pass to VaultSaaS SDK operations like charge, authorize, capture, refund, and void.

ChargeRequest

Request payload for a one-step charge (immediate capture).

amount

number

required

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

currency

string

required

ISO 4217 currency code (e.g. “USD”, “BRL”).

paymentMethod

PaymentMethodInput

required

Payment method to charge. See PaymentMethodInput.

customer

CustomerInput

Customer details passed with the charge request.

Show 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.

Show properties

line1

string

required

Primary address line.

line2

string

Secondary address line (apartment, suite, etc.).

city

string

required

City name.

state

string

State or province code.

postalCode

string

required

Postal or ZIP code.

country

string

required

ISO 3166-1 alpha-2 country code (e.g. “US”, “BR”).

description

string

Human-readable description of the charge.

metadata

Record<string, string>

Arbitrary key-value pairs forwarded to the provider.

idempotencyKey

string

Prevents duplicate charges when retrying the same request.

routing

RoutingPreference

Per-request routing overrides.

Show properties

provider

string

Force routing to this provider, bypassing rules.

exclude

string[]

Provider names to exclude from routing consideration.

Example

const request: ChargeRequest = {
  amount: 5000,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  idempotencyKey: 'order-123',
};

AuthorizeRequest

Request payload for a two-step authorization (hold funds without capture). Identical shape to ChargeRequest; the client calls authorize instead of charge.

type AuthorizeRequest = ChargeRequest;

Example

const request: AuthorizeRequest = {
  amount: 10000,
  currency: 'USD',
  paymentMethod: { 
    type: 'card',
    number: '4242424242424242',
    expMonth: 12,
    expYear: 2025,
    cvc: '123'
  },
  customer: {
    email: '[email protected]',
    name: 'John Doe'
  },
  idempotencyKey: 'auth-456',
};

CaptureRequest

Request payload to capture a previously authorized transaction.

transactionId

string

required

The transaction ID returned from a prior authorize call.

amount

number

Partial capture amount. Omit to capture the full authorized amount.

idempotencyKey

string

Prevents duplicate captures when retrying the same request.

Example

const request: CaptureRequest = {
  transactionId: 'txn_abc123',
  amount: 5000, // Partial capture
  idempotencyKey: 'capture-789',
};

RefundRequest

Request payload to refund a completed transaction (full or partial).

transactionId

string

required

The transaction ID of the original charge or capture.

amount

number

Partial refund amount. Omit to refund the full amount.

reason

string

Human-readable reason forwarded to the provider.

idempotencyKey

string

Prevents duplicate refunds when retrying the same request.

Example

const request: RefundRequest = {
  transactionId: 'txn_abc123',
  amount: 2500, // Partial refund
  reason: 'Customer requested partial refund',
  idempotencyKey: 'refund-101',
};

VoidRequest

Request payload to void (cancel) an authorized transaction before capture.

transactionId

string

required

The transaction ID of the authorization to void.

idempotencyKey

string

Prevents duplicate void operations when retrying the same request.

Example

const request: VoidRequest = {
  transactionId: 'txn_auth_xyz',
  idempotencyKey: 'void-202',
};

Client

Payment Operations

Types

Adapters

ChargeRequest

Example

AuthorizeRequest

Example

CaptureRequest

Example

RefundRequest

Example

VoidRequest

Example

Build docs developers (and LLMs) love

Client

Payment Operations

Types

Adapters

​ChargeRequest

​Example

​AuthorizeRequest

​Example

​CaptureRequest

​Example

​RefundRequest

​Example

​VoidRequest

​Example

Build docs developers (and LLMs) love

ChargeRequest

Example

AuthorizeRequest

Example

CaptureRequest

Example

RefundRequest

Example

VoidRequest

Example