Verify Payment

Verify the status and details of a payment transaction using its unique reference. Call this endpoint after payment completion to confirm the transaction status.

Always verify payments! Never rely solely on frontend callbacks or webhook notifications. Always verify transaction status on your backend for security.

For checkout-specific flows, you may also call GET /pms/transactions/{reference}/confirm/ (documented as api-reference/checkout/confirm-transaction) to obtain the same transaction status plus enriched checkout session details.

Endpoint

GET /transaction/verify/{reference}

Path Parameters

reference

string

required

The unique transaction reference returned when the payment was initialized

Headers

Name	Type	Required	Description
`api-key`	string	Required	Your API key
`Content-Type`	string	Required	Must be `application/json`

Example Request

curl -X GET https://api.payvessel.com/transaction/verify/TXN_2024_001 \
  -H "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json"

Response

status

string

Request status indicator - "success" or "error"

message

string

Human-readable message describing the result

data

object

Transaction verification data

Show Data Object

data.id

integer

Internal transaction ID

data.reference

string

Unique transaction reference

data.amount

integer

Transaction amount in smallest currency unit

data.currency

string

Transaction currency code

data.status

string

Transaction statusPossible values:

success - Payment completed successfully
failed - Payment failed or was declined
pending - Payment is still processing
abandoned - Payment was started but not completed
cancelled - Payment was cancelled

data.gateway_response

string

Response message from the payment gateway

data.paid_at

string

ISO 8601 timestamp when payment was completed (null if not paid)

data.created_at

string

ISO 8601 timestamp when transaction was created

data.channel

string

Payment method used - card, bank, ussd, qr, mobile_money, bank_transfer

data.fees

integer

Transaction fees charged in smallest currency unit

data.customer

object

Customer information

Show Customer Object

data.customer.id

integer

Customer ID in PayVessel system

data.customer.email

string

Customer’s email address

data.customer.first_name

string

Customer’s first name

data.customer.last_name

string

Customer’s last name

data.customer.phone

string

Customer’s phone number

data.authorization

object

Payment authorization details (for card payments)

Show Authorization Object

data.authorization.authorization_code

string

Authorization code for future charges

data.authorization.bin

string

First 6 digits of the card number

data.authorization.last4

string

Last 4 digits of the card number

data.authorization.exp_month

string

Card expiry month

data.authorization.exp_year

string

Card expiry year

data.authorization.channel

string

Authorization channel used

data.authorization.card_type

string

Type of card - visa, mastercard, american express, etc.

data.authorization.bank

string

Issuing bank name

data.authorization.country_code

string

Country code of the issuing bank

data.authorization.brand

string

Card brand

data.authorization.reusable

boolean

Whether the authorization can be reused for future payments

data.metadata

object

Custom metadata attached to the transaction

data.log

object

Transaction processing log and history

Example Response

{
  "status": "success",
  "message": "Transaction verification successful",
  "data": {
    "id": 123456789,
    "reference": "TXN_2024_001",
    "amount": 50000,
    "currency": "NGN",
    "status": "success",
    "gateway_response": "Successful",
    "paid_at": "2024-01-15T14:35:22Z",
    "created_at": "2024-01-15T14:30:00Z",
    "channel": "card",
    "fees": 750,
    "customer": {
      "id": 12345,
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+2348012345678"
    },
    "authorization": {
      "authorization_code": "AUTH_xyz789abc",
      "bin": "408408",
      "last4": "4081",
      "exp_month": "12",
      "exp_year": "2027",
      "channel": "card",
      "card_type": "visa",
      "bank": "TEST BANK",
      "country_code": "NG",
      "brand": "visa",
      "reusable": true
    },
    "metadata": {
      "custom_fields": [
        {
          "display_name": "Order ID",
          "variable_name": "order_id",
          "value": "ORD_001"
        }
      ]
    },
    "log": {
      "start_time": 1705329000,
      "time_spent": 322,
      "attempts": 1,
      "errors": 0,
      "success": true,
      "mobile": false,
      "input": [],
      "history": [
        {
          "type": "action",
          "message": "Attempted to pay with card",
          "time": 15
        },
        {
          "type": "success",
          "message": "Successfully paid with card",
          "time": 322
        }
      ]
    }
  }
}

Transaction Status Guide

Understanding transaction statuses is crucial for proper payment handling:

success

Payment Completed SuccessfullyThe payment has been processed and funds have been collected. You can proceed with order fulfillment.

paid_at timestamp will be populated
authorization object will contain card details (for card payments)
Funds will be settled to your account based on your settlement schedule

failed

Payment FailedThe payment attempt was unsuccessful. Common reasons include:

Insufficient funds
Invalid card details
Bank decline
Network timeout
paid_at will be null
authorization will be null
Check gateway_response for specific failure reason

pending

Payment ProcessingThe payment is still being processed. This is common with:

Bank transfers
USSD payments
Some mobile money transactions
Keep checking status periodically
You’ll receive a webhook when status changes

abandoned

Payment Started but Not CompletedCustomer initiated payment but didn’t complete it:

Closed browser before entering details
Session timeout
Customer changed mind
No funds were collected
Payment can potentially still be completed if session is still valid

cancelled

Payment CancelledPayment was explicitly cancelled by customer or system:

Customer clicked cancel
Multiple failed attempts triggered cancellation
System timeout
Payment cannot be completed
Customer needs to initiate a new payment

Best Practices

Always Verify

Verify every transaction on your backend before order fulfillment, even after webhook notifications

Handle All Status

Implement logic for all possible transaction statuses in your application

Store Authorization

Save authorization codes for successful card payments to enable future recurring charges

Monitor Logs

Use transaction logs to debug payment issues and improve user experience

Common Integration Patterns

E-commerce Checkout
Subscription Service
Webhook Handler

// After customer returns from payment
app.get('/payment/callback', async (req, res) => {
  const reference = req.query.reference;
  
  try {
    const verification = await payvessel.transaction.verify(reference);
    
    if (verification.data.status === 'success') {
      // Payment successful - fulfill order
      await fulfillOrder(verification.data);
      res.redirect('/order/success');
    } else {
      // Payment failed - show error
      res.redirect('/order/failed');
    }
  } catch (error) {
    // Handle verification error
    res.redirect('/order/error');
  }
});

// Verify subscription payment
const verifySubscriptionPayment = async (reference) => {
  const verification = await payvessel.transaction.verify(reference);
  
  if (verification.data.status === 'success') {
    // Save authorization for future charges
    await saveCustomerAuthorization({
      customer_id: verification.data.customer.id,
      authorization_code: verification.data.authorization.authorization_code,
      card_type: verification.data.authorization.card_type,
      last4: verification.data.authorization.last4
    });
    
    // Activate subscription
    await activateSubscription(verification.data.customer.id);
  }
  
  return verification.data.status;
};

// Webhook endpoint for real-time updates
app.post('/webhook/payvessel', async (req, res) => {
  const event = req.body;
  
  if (event.event === 'transaction.success') {
    // Always verify the transaction
    const verification = await payvessel.transaction.verify(event.data.reference);
    
    if (verification.data.status === 'success') {
      await processSuccessfulPayment(verification.data);
    }
  }
  
  res.status(200).send('OK');
});

Initialize Payment

Create a new payment transaction

List Transactions

Retrieve transaction history

Create Refund

Process refunds for successful transactions

Charge Authorization

Charge a saved authorization for recurring payments

Headers

api-key

string

required

Your Payvessel public API key

api-secret

string

required

Your Payvessel secret

Content-Type

enum<string>

required

Request content type

Available options:

application/json

Path Parameters

reference

string

required

The unique transaction reference returned when the payment was initialized

Response

Transaction verification successful

status

string

Request status indicator - 'success' or 'error'

message

string

Human-readable message describing the result

data

object

Show child attributes

Getting Started

Transactions

Virtual Accounts

Transfer

Wallets

Identity Verification

Webhook

Endpoint

Path Parameters

Headers

Example Request

Response

Example Response

Transaction Status Guide

Best Practices

Always Verify

Handle All Status

Store Authorization

Monitor Logs

Common Integration Patterns

Initialize Payment

List Transactions

Create Refund

Charge Authorization

Headers

Path Parameters

Response

Getting Started

Transactions

Virtual Accounts

Transfer

Wallets

Identity Verification

Webhook

Documentation Index

​Endpoint

​Path Parameters

​Headers

​Example Request

​Response

​Example Response

​Transaction Status Guide

​Best Practices

Always Verify

Handle All Status

Store Authorization

Monitor Logs

​Common Integration Patterns

​Related Endpoints

Initialize Payment

List Transactions

Create Refund

Charge Authorization

Headers

Path Parameters

Response

Endpoint

Path Parameters

Headers

Example Request

Response

Example Response

Transaction Status Guide

Best Practices

Common Integration Patterns

Related Endpoints