All response types are imported from the @vtex/payment-provider package and represent your connector’s responses to VTEX’s Payment Gateway.
AuthorizationResponse
Response returned from the authorize() method. Use the helper methods from the Authorizations namespace to construct responses.
Unique identifier for the payment (from the request)
Payment status
approved - Payment was successfully authorizeddenied - Payment was declinedundefined - Payment is pending (async approval, bank invoice, redirect)
Transaction identifier from your payment provider
Authorization identifier for approved payments (required when status is approved)
Unique sequential number from your payment provider
Response code from your payment provider
Human-readable message about the transaction result
Time in milliseconds before automatic cancellation (for pending payments)
Payment URL for bank invoice flows
Redirect URL for redirect-based payment flows
Time in milliseconds before automatic settlement
delayToAutoSettleAfterAntifraud
Time in milliseconds before auto-settlement after antifraud check
Helper methods
Use the Authorizations namespace to construct properly formatted responses:
Approved
Denied
Pending
Bank invoice
Redirect
import { Authorizations } from '@vtex/payment-provider'
return Authorizations.approve(request, {
authorizationId: 'auth_123456',
nsu: 'nsu_789012',
tid: 'tid_345678'
})
approved with the provided identifiers.return Authorizations.deny(request, {
tid: 'tid_345678',
code: 'INSUFFICIENT_FUNDS',
message: 'Card has insufficient funds'
})
denied with optional error details.return Authorizations.pending(request, {
tid: 'tid_345678',
delayToCancel: 300000 // 5 minutes
})
undefined for async processing. Use the callback mechanism to send the final result.return Authorizations.pendingBankInvoice(request, {
paymentUrl: 'https://provider.com/invoice/123',
tid: 'tid_345678',
delayToCancel: 86400000 // 24 hours
})
undefined with a payment URL for bank invoice generation.return Authorizations.redirect(request, {
redirectUrl: 'https://provider.com/checkout/123',
tid: 'tid_345678',
delayToCancel: 600000 // 10 minutes
})
undefined with a redirect URL for external payment flows.When returning a pending response, you must use the callback() method to send the final authorization result asynchronously.
CancellationResponse
Response returned from the cancel() method.
Unique identifier for the payment (from the request)
Cancellation identifier from your payment provider (required for approved cancellations)
Response code from your payment provider
Human-readable message about the cancellation result
Request identifier (from the request)
Helper methods
import { Cancellations } from '@vtex/payment-provider'
return Cancellations.approve(request, {
cancellationId: 'cancel_123456'
})
return Cancellations.deny(request, {
code: 'ALREADY_SETTLED',
message: 'Cannot cancel settled payment'
})
RefundResponse
Response returned from the refund() method.
Unique identifier for the payment (from the request)
Refund identifier from your payment provider (required for approved refunds)
Response code from your payment provider
Human-readable message about the refund result
Request identifier (from the request)
Actual refunded amount in cents (may differ from requested amount)
Helper methods
import { Refunds } from '@vtex/payment-provider'
return Refunds.approve(request, {
refundId: 'refund_123456',
value: request.value
})
return Refunds.deny(request, {
code: 'REFUND_WINDOW_EXPIRED',
message: 'Refund period has expired'
})
SettlementResponse
Response returned from the settle() method.
Unique identifier for the payment (from the request)
Settlement identifier from your payment provider (required for approved settlements)
Response code from your payment provider
Human-readable message about the settlement result
Request identifier (from the request)
Actual settled amount in cents (may differ from requested amount)
Helper methods
import { Settlements } from '@vtex/payment-provider'
return Settlements.approve(request, {
settleId: 'settle_123456',
value: request.value
})
return Settlements.deny(request, {
code: 'AUTHORIZATION_EXPIRED',
message: 'Authorization has expired'
})
Common patterns
Using the callback for async operations
For pending authorizations, use the callback mechanism to send the final result:
public async authorize(
authorization: AuthorizationRequest
): Promise<AuthorizationResponse> {
// Start async processing
this.processAsync(authorization).then(result => {
const response = result.approved
? Authorizations.approve(authorization, {
authorizationId: result.id,
tid: result.transactionId
})
: Authorizations.deny(authorization, {
tid: result.transactionId,
message: result.errorMessage
})
// Send result via callback
this.callback(authorization, response)
})
// Return pending status immediately
return Authorizations.pending(authorization, {
tid: generateTid(),
delayToCancel: 300000
})
}
Error handling
Always handle errors gracefully and return proper denial responses:
public async authorize(
authorization: AuthorizationRequest
): Promise<AuthorizationResponse> {
try {
const result = await this.provider.authorize(authorization)
return Authorizations.approve(authorization, {
authorizationId: result.id,
tid: result.tid,
nsu: result.nsu
})
} catch (error) {
return Authorizations.deny(authorization, {
tid: generateTid(),
code: error.code,
message: error.message
})
}
}
Never throw errors from payment methods. Always return a properly formatted denial response when operations fail.
Partial settlements and refunds
You can settle or refund partial amounts:
public async settle(
settlement: SettlementRequest
): Promise<SettlementResponse> {
// Settle only 80% of authorized amount
const partialAmount = Math.floor(settlement.value * 0.8)
const result = await this.provider.capture({
authorizationId: settlement.authorizationId,
amount: partialAmount
})
return Settlements.approve(settlement, {
settleId: result.id,
value: partialAmount // Return actual settled amount
})
}