Verify Transaction

Verifies the status of a transaction to confirm if it was successful, pending, or failed.

Authentication required (API Key or User JWT).

GET/api/transactions/:transactionId/verify

Authentication

This endpoint requires either:

• API Key (recommended for server-to-server verification)
• User JWT token (for client applications)

// Using API Key
Authorization: Bearer sk_test_xxxxx

// Using JWT
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Path Parameters

Parameter	Type	Description
transactionId	String	The ID of the transaction to verify.

Response 200 OK

Returns the current status and details of the transaction.

{
  "status": "success",
  "data": {
    "id": "txn_1234567890",
    "reference": "ref_abcdef12345",
    "amount": 5000000,
    "fee": 75000,
    "currency": "NGN",
    "status": "COMPLETED",
    "paymentMethod": "CARD",
    "customerEmail": "customer@example.com",
    "customerName": "John Doe",
    "description": "Payment for Invoice #INV-001",
    "metadata": {
      "orderId": "ORD-12345"
    },
    "createdAt": "2023-10-26T10:15:30.000Z",
    "updatedAt": "2023-10-26T10:16:45.000Z",
    "completedAt": "2023-10-26T10:16:45.000Z"
  }
}

Possible Transaction Statuses

Status	Description
PENDING	Transaction has been initiated but not completed
COMPLETED	Transaction was successful
FAILED	Transaction failed
CANCELLED	Transaction was cancelled by the customer
REFUNDED	Transaction was refunded (partially or fully)

Errors

• 400 Bad Request: Invalid transaction ID format.
• 401 Unauthorized: Invalid or missing authorization.
• 404 Not Found: Transaction not found.
• 500 Internal Server Error: Server encountered an unexpected error.

Best Practices

1. Always verify server-side: Never trust client-side verification for financial transactions
2. Implement webhooks: For real-time notifications, implement webhooks alongside verification
3. Idempotency: This endpoint is safe to call multiple times without side effects

Example Requests

cURL

curl -X GET \
  "https://api.skypay.com/api/transactions/txn_1234567890/verify" \
  -H "Authorization: Bearer sk_test_xxxxx"

JavaScript (Fetch API)

fetch('https://api.skypay.com/api/transactions/txn_1234567890/verify', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_test_xxxxx'
  }
})
.then(response => response.json())
.then(data => {
  if (data.data.status === 'COMPLETED') {
    // Transaction is successful, update your system
    console.log('Payment verified successfully');
  } else {
    // Handle other statuses
    console.log('Payment status:', data.data.status);
  }
})
.catch(error => console.error('Error:', error));