Skip to main content
Retrieve the current status and complete history of a transaction. This method queries the payment provider for the latest transaction state and returns a full status timeline.

​
Method signature

async getStatus(transactionId: string): Promise<TransactionStatus>

​
Parameters

​
transactionId
string
required
The transaction ID to query. Can be from any payment operation: charge(), authorize(), or capture().

​
Returns

​
TransactionStatus
object
Complete transaction status including current state and historical changes.

​
Error handling

The getStatus() method may throw the following errors:
Thrown when the provider for the transaction cannot be found.
// src/client/vault-client.ts:491-495
if (!fallbackProvider) {
  throw new VaultRoutingError(
    'No configured providers are available for transaction lookup.'
  );
}
The provider may return errors such as:
  • Transaction not found
  • Access denied (transaction belongs to different account)
  • Provider API unavailable

​
Example

const charge = await client.charge({
  amount: 5000,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' }
});

// Later, check the status
const status = await client.getStatus(charge.id);

console.log(status.status); // 'completed'
console.log(status.provider); // 'stripe'
console.log(status.amount); // 5000
console.log(status.history);
// [
//   { status: 'pending', timestamp: '2026-03-03T10:00:00Z' },
//   { status: 'completed', timestamp: '2026-03-03T10:00:02Z' }
// ]

​
Implementation details

The getStatus operation (src/client/vault-client.ts:297-318):
  1. Looks up the provider that handled the original transaction using the transaction index
  2. Falls back to the first configured provider if the transaction is not in the index
  3. Queries the provider adapter for the current status
  4. Records the transaction in the provider index for future lookups
  5. Queues transaction report to the platform for analytics
  6. Returns the normalized status with complete history
Status queries are always made to the provider that originally processed the transaction. The method automatically routes to the correct provider using the transaction index.
Use getStatus() to:
  • Verify payment completion before fulfilling orders
  • Monitor async payment methods (bank transfers, PIX)
  • Track authorization expiration
  • Audit transaction history for reconciliation

​
Status transitions

1

Initial state

Transaction starts with "pending" status when first created.
2

Processing

Status may transition to:
  • "authorized" for authorizations
  • "requires_action" for 3DS or similar verification
  • "completed" for successful immediate charges
3

Final states

Terminal states include:
  • "completed" - successful charge or capture
  • "failed" - processing error
  • "declined" - rejected by bank or fraud check
  • "cancelled" - voided by merchant
Status history is provider-dependent. Some providers may return minimal history with only the current state, while others provide detailed audit trails.

​
Use cases

Use getStatus() to verify webhook events from your payment provider:
app.post('/webhook/payment', async (req, res) => {
  const event = await client.handleWebhook('stripe', req.body, req.headers);
  
  // Verify the status with the provider
  const status = await client.getStatus(event.transactionId);
  
  if (status.status === 'completed') {
    await fulfillOrder(event.transactionId);
  }
  
  res.sendStatus(200);
});
Monitor bank transfers or PIX payments that complete asynchronously:
const charge = await client.charge({
  amount: 10000,
  currency: 'BRL',
  paymentMethod: { type: 'pix' }
});

// Display QR code to customer
// Then poll for completion
const interval = setInterval(async () => {
  const status = await client.getStatus(charge.id);
  if (status.status === 'completed') {
    clearInterval(interval);
    console.log('PIX payment received!');
  }
}, 5000);
Audit transaction history for financial reconciliation:
const transactions = await getTransactionIds();

for (const txnId of transactions) {
  const status = await client.getStatus(txnId);
  console.log(`${txnId}: ${status.status} - ${status.amount}`);
  console.log(`History: ${status.history.length} changes`);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us