Confirm Transaction
curl --request GET \
--url https://api.payvessel.com/pms/transactions/{reference}/confirm/ \
--header 'api-key: <api-key>' \
--header 'api-secret: <api-secret>'import requests
url = "https://api.payvessel.com/pms/transactions/{reference}/confirm/"
headers = {
"api-key": "<api-key>",
"api-secret": "<api-secret>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'api-key': '<api-key>', 'api-secret': '<api-secret>'}};
fetch('https://api.payvessel.com/pms/transactions/{reference}/confirm/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.payvessel.com/pms/transactions/{reference}/confirm/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"api-key: <api-key>",
"api-secret: <api-secret>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.payvessel.com/pms/transactions/{reference}/confirm/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("api-secret", "<api-secret>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.payvessel.com/pms/transactions/{reference}/confirm/")
.header("api-key", "<api-key>")
.header("api-secret", "<api-secret>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.payvessel.com/pms/transactions/{reference}/confirm/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
response = http.request(request)
puts response.read_body{
"status": true,
"message": "<string>",
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"transaction_ref": "<string>",
"amount": "<string>",
"fee": "<string>",
"status": "PENDING",
"transaction_type": "CREDIT",
"channel": "<string>",
"payment_processor": "<string>",
"access_code": "<string>",
"checkout_url": "<string>",
"api_key": "<string>",
"payment_link": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"description": "<string>",
"metadata": "<string>",
"business_profile": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "jsmith@example.com",
"business_logo": "<string>"
},
"order": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"channels": "<string>",
"currency": "<string>",
"redirect_url": "<string>",
"customer_name": "<string>",
"customer_email": "jsmith@example.com",
"customer_phone_number": "<string>",
"metadata": "<string>",
"created_datetime": "2023-11-07T05:31:56Z",
"updated_datetime": "2023-11-07T05:31:56Z"
},
"virtual_account": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_code": "<string>",
"bank_name": "<string>",
"account_number": "<string>",
"account_name": "<string>",
"account_type": "STATIC",
"expire_datetime": "2023-11-07T05:31:56Z",
"tracking_reference": "<string>",
"created_datetime": "2023-11-07T05:31:56Z",
"updated_datetime": "2023-11-07T05:31:56Z"
},
"logs": "<string>",
"created_datetime": "2023-11-07T05:31:56Z",
"updated_datetime": "2023-11-07T05:31:56Z"
}
}Transactions
Verify Payment
Verify the status of a payment transaction by reference
GET
/
pms
/
transactions
/
{reference}
/
confirm
/
Confirm Transaction
curl --request GET \
--url https://api.payvessel.com/pms/transactions/{reference}/confirm/ \
--header 'api-key: <api-key>' \
--header 'api-secret: <api-secret>'import requests
url = "https://api.payvessel.com/pms/transactions/{reference}/confirm/"
headers = {
"api-key": "<api-key>",
"api-secret": "<api-secret>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'api-key': '<api-key>', 'api-secret': '<api-secret>'}};
fetch('https://api.payvessel.com/pms/transactions/{reference}/confirm/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.payvessel.com/pms/transactions/{reference}/confirm/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"api-key: <api-key>",
"api-secret: <api-secret>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.payvessel.com/pms/transactions/{reference}/confirm/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("api-secret", "<api-secret>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.payvessel.com/pms/transactions/{reference}/confirm/")
.header("api-key", "<api-key>")
.header("api-secret", "<api-secret>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.payvessel.com/pms/transactions/{reference}/confirm/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
response = http.request(request)
puts response.read_body{
"status": true,
"message": "<string>",
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"transaction_ref": "<string>",
"amount": "<string>",
"fee": "<string>",
"status": "PENDING",
"transaction_type": "CREDIT",
"channel": "<string>",
"payment_processor": "<string>",
"access_code": "<string>",
"checkout_url": "<string>",
"api_key": "<string>",
"payment_link": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"description": "<string>",
"metadata": "<string>",
"business_profile": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "jsmith@example.com",
"business_logo": "<string>"
},
"order": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"channels": "<string>",
"currency": "<string>",
"redirect_url": "<string>",
"customer_name": "<string>",
"customer_email": "jsmith@example.com",
"customer_phone_number": "<string>",
"metadata": "<string>",
"created_datetime": "2023-11-07T05:31:56Z",
"updated_datetime": "2023-11-07T05:31:56Z"
},
"virtual_account": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_code": "<string>",
"bank_name": "<string>",
"account_number": "<string>",
"account_name": "<string>",
"account_type": "STATIC",
"expire_datetime": "2023-11-07T05:31:56Z",
"tracking_reference": "<string>",
"created_datetime": "2023-11-07T05:31:56Z",
"updated_datetime": "2023-11-07T05:31:56Z"
},
"logs": "<string>",
"created_datetime": "2023-11-07T05:31:56Z",
"updated_datetime": "2023-11-07T05:31:56Z"
}
}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.
Endpoint
GET/pms/transactions/{reference}/confirm/
Path Parameters
string
required
The unique transaction reference returned when the payment was initialized
Example Request
curl -X GET https://api.payvessel.com/pms/transactions/TXN_2024_001/confirm/ \
-H "api-key: YOUR_API_KEY" \
-H "api-secret: YOUR_SECRET" \
-H "Content-Type: application/json"
const payvessel = require('payvessel')(process.env.PAYVESSEL_SECRET_KEY);
const transaction = await payvessel.transaction.confirm('TXN_2024_001');
<?php
$payvessel = new \Payvessel\Payvessel(getenv('PAYVESSEL_SECRET_KEY'));
$transaction = $payvessel->transaction->confirm('TXN_2024_001');
?>
import payvessel
payvessel.api_key = os.environ['PAYVESSEL_SECRET_KEY']
transaction = payvessel.Transaction.confirm('TXN_2024_001')
Response
string
Request status indicator -
"success" or "error"string
Human-readable message describing the result
object
Transaction verification data
Show Data Object
Show Data Object
integer
Internal transaction ID
string
Unique transaction reference
integer
Transaction amount in smallest currency unit
string
Transaction currency code
string
Transaction statusPossible values:
success- Payment completed successfullyfailed- Payment failed or was declinedpending- Payment is still processingabandoned- Payment was started but not completedcancelled- Payment was cancelled
string
Response message from the payment gateway
string
ISO 8601 timestamp when payment was completed (null if not paid)
string
ISO 8601 timestamp when transaction was created
string
Payment method used -
card, bank, ussd, qr, mobile_money, bank_transferinteger
Transaction fees charged in smallest currency unit
object
object
Payment authorization details (for card payments)
Show Authorization Object
Show Authorization Object
string
Authorization code for future charges
string
First 6 digits of the card number
string
Last 4 digits of the card number
string
Card expiry month
string
Card expiry year
string
Authorization channel used
string
Type of card -
visa, mastercard, american express, etc.string
Issuing bank name
string
Country code of the issuing bank
string
Card brand
boolean
Whether the authorization can be reused for future payments
object
Custom metadata attached to the transaction
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
}
]
}
}
}
{
"status": "success",
"message": "Transaction verification successful",
"data": {
"id": 123456790,
"reference": "TXN_2024_002",
"amount": 50000,
"currency": "NGN",
"status": "failed",
"gateway_response": "Insufficient Funds",
"paid_at": null,
"created_at": "2024-01-15T15:00:00Z",
"channel": "card",
"fees": 0,
"customer": {
"id": 12346,
"email": "customer2@example.com",
"first_name": "Jane",
"last_name": "Smith",
"phone": "+2348012345679"
},
"authorization": null,
"metadata": {},
"log": {
"start_time": 1705330800,
"time_spent": 45,
"attempts": 1,
"errors": 1,
"success": false,
"mobile": false,
"input": [],
"history": [
{
"type": "action",
"message": "Attempted to pay with card",
"time": 10
},
{
"type": "error",
"message": "Payment failed: Insufficient Funds",
"time": 45
}
]
}
}
}
{
"status": "error",
"message": "Transaction not found"
}
{
"status": "error",
"message": "Unauthorized. Please check your API key"
}
Transaction Status Guide
Understanding transaction statuses is crucial for proper payment handling:success
success
Payment Completed SuccessfullyThe payment has been processed and funds have been collected. You can proceed with order fulfillment.
paid_attimestamp will be populatedauthorizationobject will contain card details (for card payments)- Funds will be settled to your account based on your settlement schedule
failed
failed
Payment FailedThe payment attempt was unsuccessful. Common reasons include:
- Insufficient funds
- Invalid card details
- Bank decline
- Network timeout
-
paid_atwill be null -
authorizationwill be null -
Check
gateway_responsefor specific failure reason
pending
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
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
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');
});
Related Endpoints
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
Your Payvessel public API key
Your Payvessel secret
Path Parameters
Transaction reference to confirm
