authorize()

Overview

The authorize() method is the core payment processing route that handles authorization requests from VTEX. It supports multiple authorization flows including immediate approval/denial, asynchronous processing, bank invoice generation, and redirect-based authentication.

Method signature

public async authorize(
  authorization: AuthorizationRequest
): Promise<AuthorizationResponse>

Parameters

authorization

AuthorizationRequest

required

The authorization request object from VTEX containing payment details.

authorization.paymentId

string

required

Unique identifier for the payment transaction

authorization.transactionId

string

required

VTEX transaction identifier

authorization.paymentMethod

string

required

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

authorization.merchantName

string

required

Name of the merchant requesting authorization

authorization.value

number

required

Payment amount in cents

authorization.currency

string

required

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

authorization.card

CardAuthorization | TokenizedCard

Card payment details (for card-based transactions)

authorization.card.number

string

Card number (for non-tokenized cards)

authorization.card.holder

string

Cardholder name

authorization.card.expiration

object

Card expiration date

authorization.card.csc

string

Card security code

authorization.miniCart

object

Shopping cart details for the transaction

Response

response

AuthorizationResponse

The authorization response indicating the result of the payment authorization.

paymentId

string

required

Echo of the payment identifier from the request

status

string

required

Authorization status: approved, denied, or undefined (pending)

tid

string

required

Transaction identifier from the payment provider

authorizationId

string

Authorization identifier (present when approved)

nsu

string

Unique sequential number (NSU) for approved transactions

delayToCancel

number

Milliseconds to wait before canceling pending transactions

paymentUrl

string

URL for bank invoice payment (bank invoice flow)

redirectUrl

string

URL to redirect user for authentication (redirect flow)

message

string

Human-readable status message

Authorization flows

The authorize() method implements different flows based on the payment method and card details:

Card number: 4444333322221111Immediately approves the authorization with all required identifiers.

{
  paymentId: "ABC123",
  status: "approved",
  tid: "TID-XYZ789",
  authorizationId: "AUTH-456",
  nsu: "NSU-789"
}

Card number: 4444333322221112Immediately denies the authorization.

{
  paymentId: "ABC123",
  status: "denied",
  tid: "TID-XYZ789",
  message: "Authorization denied"
}

Card number: 4222222222222224Returns pending status, then asynchronously approves via callback.

// Initial response
{
  paymentId: "ABC123",
  status: undefined,
  tid: "TID-XYZ789",
  delayToCancel: 1000
}

// Callback response (async)
{
  paymentId: "ABC123",
  status: "approved",
  tid: "TID-XYZ789",
  authorizationId: "AUTH-456",
  nsu: "NSU-789"
}

Card number: 4222222222222225Returns pending status, then asynchronously denies via callback.

// Initial response
{
  paymentId: "ABC123",
  status: undefined,
  tid: "TID-XYZ789",
  delayToCancel: 1000
}

// Callback response (async)
{
  paymentId: "ABC123",
  status: "denied",
  tid: "TID-XYZ789"
}

Payment method: BankInvoiceGenerates a payment URL for bank invoice payment.

// Initial response
{
  paymentId: "ABC123",
  status: undefined,
  tid: "TID-XYZ789",
  delayToCancel: 1000,
  paymentUrl: "https://payment.example.com/invoice/ABC123"
}

// Callback after payment (async)
{
  paymentId: "ABC123",
  status: "approved",
  tid: "TID-XYZ789",
  authorizationId: "AUTH-456",
  nsu: "NSU-789"
}

Card: Tokenized card (no card number)Redirects user to external authentication page.

// Initial response
{
  paymentId: "ABC123",
  status: undefined,
  tid: "TID-XYZ789",
  delayToCancel: 1000,
  redirectUrl: "https://auth.example.com/verify/ABC123"
}

// Callback after authentication (async)
{
  paymentId: "ABC123",
  status: "approved",
  tid: "TID-XYZ789",
  authorizationId: "AUTH-456",
  nsu: "NSU-789"
}

Implementation

The test suite implementation demonstrates key patterns:

public async authorize(
  authorization: AuthorizationRequest
): Promise<AuthorizationResponse> {
  if (this.isTestSuite) {
    // Check for persisted response (idempotency)
    const persistedResponse = await getPersistedAuthorizationResponse(
      this.context.clients.vbase,
      authorization
    )

    if (persistedResponse !== undefined && persistedResponse !== null) {
      return persistedResponse
    }

    // Execute authorization flow
    return executeAuthorization(authorization, response =>
      this.saveAndRetry(authorization, response)
    )
  }

  throw new Error('Not implemented')
}

private async saveAndRetry(
  req: AuthorizationRequest,
  resp: AuthorizationResponse
) {
  await persistAuthorizationResponse(this.context.clients.vbase, resp)
  this.callback(req, resp)
}

Key features

Idempotency

The implementation persists authorization responses and returns the same response for duplicate requests with the same paymentId:

const persistedResponse = await getPersistedAuthorizationResponse(
  this.context.clients.vbase,
  authorization
)

if (persistedResponse !== undefined && persistedResponse !== null) {
  return persistedResponse
}

Asynchronous callbacks

For pending transactions, use the callback() method to notify VTEX of final status:

this.callback(authorizationRequest, finalResponse)

Flow selection

The framework automatically selects the appropriate flow based on:

Payment method (bank invoice detection)
Card details (specific test card numbers)
Card tokenization status (tokenized cards trigger redirect)

Best practices

Always persist responses

Store authorization responses to ensure idempotent behavior. VTEX may retry requests, and you must return the same response for the same paymentId.

Handle asynchronous flows properly

For pending authorizations, return immediately with status: undefined and use the callback mechanism to notify final status. Set appropriate delayToCancel values.

Include all required fields

Approved authorizations must include tid, authorizationId, and nsu. Missing fields will cause VTEX to reject the response.

Validate card details

Check card number format, expiration date, and security code before processing. Return appropriate denial messages for invalid data.

cancel() - Cancel an authorized payment
settle() - Settle an authorized payment
refund() - Refund a settled payment

Core Classes

Routes

Types & Interfaces

Overview

Method signature

Parameters

Response

Authorization flows

Implementation

Key features

Idempotency

Asynchronous callbacks

Flow selection

Best practices

Build docs developers (and LLMs) love

Core Classes

Routes

Types & Interfaces

​Overview

​Method signature

​Parameters

​Response

​Authorization flows

​Implementation

​Key features

​Idempotency

​Asynchronous callbacks

​Flow selection

​Best practices

​Related routes

Build docs developers (and LLMs) love

Overview

Method signature

Parameters

Response

Authorization flows

Implementation

Key features

Idempotency

Asynchronous callbacks

Flow selection

Best practices

Related routes