Request types

All request types are imported from the @vtex/payment-provider package and represent incoming payment operations from VTEX’s Payment Gateway.

AuthorizationRequest

Represents a request to authorize a payment transaction. This is the primary request type that initiates the payment flow.

paymentId

string

required

Unique identifier for the payment transaction

transactionId

string

required

VTEX transaction identifier

paymentMethod

string

required

Payment method name (e.g., “Visa”, “Mastercard”, “BankInvoice”)

merchantName

string

required

Name of the merchant account

value

number

required

Transaction amount in cents (e.g., 1050 for $10.50)

currency

string

required

Three-letter ISO currency code (e.g., “USD”, “BRL”)

installments

number

Number of installments for the payment

deviceFingerprint

string

Device fingerprint for fraud detection

card

CardData | TokenizedCard

Card information for card-based payments

Show CardData properties

holder

string

Cardholder name

number

string

Card number (PCI-compliant, may be masked)

csc

string

Card security code (CVV/CVC)

expiration

object

Card expiration date

month

string

Expiration month (01-12)

year

string

Expiration year (YYYY)

Show TokenizedCard properties

token

string

Tokenized card identifier

tokenProvider

string

Token provider name

miniCart

object

Shopping cart information

Show Properties

shippingValue

number

Shipping cost in cents

taxValue

number

Tax amount in cents

buyer

object

Buyer information including email, phone, and address

merchantSettings

object

Custom configuration values from the provider’s configuration.json customFields

ipAddress

string

Customer’s IP address

Type guards

The framework provides helper functions to identify authorization types:

import {
  isCardAuthorization,
  isBankInvoiceAuthorization,
  isTokenizedCard
} from '@vtex/payment-provider'

if (isCardAuthorization(request)) {
  const card = request.card
  if (isTokenizedCard(card)) {
    // Handle tokenized card
  } else {
    // Handle regular card
  }
}

if (isBankInvoiceAuthorization(request)) {
  // Handle bank invoice payment
}

The card field is only present when isCardAuthorization() returns true. Always use type guards to safely access card data.

CancellationRequest

Represents a request to cancel a previously authorized payment.

paymentId

string

required

Unique identifier for the original payment transaction

requestId

string

required

Unique identifier for this cancellation request

authorizationId

string

Authorization identifier returned from the original authorization

transactionId

string

required

VTEX transaction identifier

value

number

required

Amount to cancel in cents

merchantSettings

object

Custom configuration values from the provider’s settings

Usage example

public async cancel(
  cancellation: CancellationRequest
): Promise<CancellationResponse> {
  // Cancel the payment with your payment provider
  const result = await this.provider.cancelPayment({
    authorizationId: cancellation.authorizationId,
    amount: cancellation.value
  })
  
  return Cancellations.approve(cancellation, {
    cancellationId: result.id
  })
}

RefundRequest

Represents a request to refund a settled payment transaction.

paymentId

string

required

Unique identifier for the original payment transaction

requestId

string

required

Unique identifier for this refund request

settleId

string

Settlement identifier from the original settlement

transactionId

string

required

VTEX transaction identifier

value

number

required

Amount to refund in cents

merchantSettings

object

Custom configuration values from the provider’s settings

Refunds can only be performed on settled transactions. Use cancellations for authorized-but-not-settled payments.

SettlementRequest

Represents a request to settle (capture) an authorized payment.

paymentId

string

required

Unique identifier for the payment transaction

requestId

string

required

Unique identifier for this settlement request

authorizationId

string

Authorization identifier from the original authorization

transactionId

string

required

VTEX transaction identifier

value

number

required

Amount to settle in cents (must not exceed authorized amount)

merchantSettings

object

Custom configuration values from the provider’s settings

Usage example

public async settle(
  settlement: SettlementRequest
): Promise<SettlementResponse> {
  // Capture the authorized payment
  const result = await this.provider.capturePayment({
    authorizationId: settlement.authorizationId,
    amount: settlement.value
  })
  
  return Settlements.approve(settlement, {
    settleId: result.id
  })
}

Common patterns

Accessing merchant settings

All request types include merchantSettings which contains the custom fields defined in configuration.json:

public async authorize(
  authorization: AuthorizationRequest
): Promise<AuthorizationResponse> {
  const clientId = authorization.merchantSettings['Client ID']
  const secretToken = authorization.merchantSettings['Secret Token']
  const currency = authorization.merchantSettings['Currency']
  
  // Use settings to authenticate with payment provider
}

Handling different payment methods

Credit card
Bank invoice

if (isCardAuthorization(request)) {
  const { card } = request
  
  if (isTokenizedCard(card)) {
    // Process tokenized card
    return this.processToken(card.token)
  } else {
    // Process card details
    return this.processCard({
      number: card.number,
      holder: card.holder,
      cvv: card.csc,
      expiration: card.expiration
    })
  }
}

if (isBankInvoiceAuthorization(request)) {
  // Generate payment URL for bank invoice
  const paymentUrl = await this.generateBankInvoice(request)
  
  return Authorizations.pendingBankInvoice(request, {
    paymentUrl,
    tid: generateTransactionId(),
    delayToCancel: 86400000 // 24 hours
  })
}

Core Classes

Routes

Types & Interfaces

AuthorizationRequest

Type guards

CancellationRequest

Usage example

RefundRequest

SettlementRequest

Usage example

Common patterns

Accessing merchant settings

Handling different payment methods

Build docs developers (and LLMs) love

Core Classes

Routes

Types & Interfaces

​AuthorizationRequest

​Type guards

​CancellationRequest

​Usage example

​RefundRequest

​SettlementRequest

​Usage example

​Common patterns

​Accessing merchant settings

​Handling different payment methods

Build docs developers (and LLMs) love

AuthorizationRequest

Type guards

CancellationRequest

Usage example

RefundRequest

SettlementRequest

Usage example

Common patterns

Accessing merchant settings

Handling different payment methods