Welcome to Valuepay Application Documentation

The Transactions API allows you to create and manage payments on your integration.

Initialize Transaction

Initiates a new payment transaction from your backend.

POST/v1/transactions/initialize

Headers

Name	Type	Description
Authorization*	String	Set value to Bearer SECRET_KEY
Content-Type*	String	Set value to application/json

Body Parameters

Name	Type	Description
transactionRef*	String	Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
amount*	Number	Amount in Naira (not kobo)
currency*	String	The transaction currency (e.g., NGN)
redirectUrl*	String	Fully qualified URL to redirect after payment
customer*	Object	Customer information object
customer.email*	String	Customer's email address
customer.firstName	String	Customer's first name
customer.lastName	String	Customer's last name
customer.fullName	String	Customer's full name
customer.phone	String	Customer's phone number
channels	Array	Payment channels: card, transfer, ussd, qrcode
planId	String	Plan ID for subscription payments
type	String	Transaction type (default: 'default')
splitCodeId	String	Split code ID for transaction splitting
metaData	Object	Additional metadata for the transaction
transactionCharge	Number	Transaction charge amount
subaccountId	String	Subaccount ID for split payments
chargesBearer	String	Who bears the charges: 'main' or 'subaccount'

Request Body

{
  "transactionRef": "req_1755126367403_901186",
  "amount": 500,
  "currency": "NGN",
  "redirectUrl": "https://yoursite.com/payment/callback",
  "channels": ["card", "transfer", "ussd", "qrcode"],
  "customer": {
    "email": "customer@example.com",
    "fullName": "John Doe",
    "phone": "+2348012345678"
  }
}

Sample Response

{
  "status": "Success",
  "data": {
    "paymentUrl": "https://www.valuepayng.com/payments/transaction/c2e816b48789f41f9d130ffac0cc86c4",
    "valueRef": "c2e816b48789f41f9d130ffac0cc86c4",
    "transactionRef": "req_1755126367403_901186"
  },
  "message": "transaction created"
}

Notes

Use the paymentUrl to complete the payment
After payment, you are redirected to the specified redirectUrl with URL-encoded parameters
Decode the response parameter to get transaction details

Check Transaction Status

Retrieves the status and details of a specific transaction.

GET/v1/transactions/:transactionRef

Headers

Name	Type	Description
Authorization*	String	Set value to Bearer SECRET_KEY
Content-Type*	String	Set value to application/json

Path Parameters

Name	Type	Description
transactionRef*	String	The transaction reference used to initiate the transaction

Sample Response

{
  "status": "Success",
  "data": {
    "id": "8de26631-a8f9-4807-8ab2-62ca214cd0ef",
    "merchantId": "vp6111425176234",
    "valueRef": "c2e816b48789f41f9d130ffac0cc86c4",
    "transactionRef": "req_1755126367403_901186",
    "status": "COMPLETED",
    "type": "default",
    "currency": "NGN",
    "amount": 500,
    "fees": 7,
    "paymentOption": "transfer",
    "settlementAmount": 493,
    "completedAt": "2025-08-13T23:09:04.272Z",
    "customer": {
      "email": "customer@example.com",
      "fullName": "John Doe",
      "phone": "+2348012345678"
    },
    "history": [
      {
        "action": "Customer starts payment",
        "actionType": "success",
        "message": "Customer starts payment",
        "performedAt": "2025-08-13T23:07:12.603Z"
      }
    ]
  },
  "message": "transaction details fetched"
}

Notes

Use the transactionRef from the initialization response
Status updates are also available via webhooks

List Transactions

Retrieves a list of transactions filtered by criteria.

GET/v1/transactions/

Headers

Name	Type	Description
Authorization*	String	Set value to Bearer SECRET_KEY
Content-Type*	String	Set value to application/json

Query Parameters

Name	Type	Description
from	Datetime	ISO 8601 date (e.g., 2025-08-01T00:00:00Z)
to	Datetime	ISO 8601 date (e.g., 2025-08-07T23:59:59Z)
status	String	Filter by status: COMPLETED, PENDING, FAILED, ABORTED, CANCELLED
paymentOption	String	Filter by payment method: card, qrcode, ussd, transfer
page	Integer	Page number for pagination (default: 1)
limit	Integer	Number of transactions per page (default: 20, max: 100)

Sample Response

{
  "status": "Success",
  "data": {
    "current_page": 1,
    "total_page": 1,
    "total_docs": 5,
    "has_next": false,
    "has_previous": false,
    "next_page": null,
    "previous_page": null,
    "results": [
      {
        "id": "8de26631-a8f9-4807-8ab2-62ca214cd0ef",
        "transactionRef": "req_1755126367403_901186",
        "status": "COMPLETED",
        "amount": 500,
        "currency": "NGN",
        "customer": {
          "email": "customer@example.com"
        }
      }
    ]
  },
  "message": "transactions fetched"
}

Notes

Use pagination to handle large datasets
Combine with webhooks for real-time updates

Export Transactions

Export a list of transactions as CSV for reporting and analysis.

GET/v1/transactions/exports/csv

Headers

Name	Type	Description
Authorization*	String	Set value to Bearer SECRET_KEY
Content-Type*	String	Set value to application/json

Query Parameters

Name	Type	Description
from	Datetime	ISO 8601 date (e.g., 2025-08-01T00:00:00Z)
to	Datetime	ISO 8601 date (e.g., 2025-08-07T23:59:59Z)
status	String	Filter by status: COMPLETED, PENDING, FAILED, ABORTED, CANCELLED
paymentOption	String	Filter by payment method: card, qrcode, ussd, transfer

Sample Response

{
  "status": "Success",
  "message": "Export successful",
  "data": {
    "downloadUrl": "https://valuepay.com/exports/transactions_2025_08_13.csv",
    "expiresAt": "2025-08-13 12:00:00"
  }
}

Notes

The CSV file will include all transaction details for the specified date range
Export URLs expire after 1 hour for security
Use the same query parameters as the List Transactions endpoint for filtering

Transaction Statuses

The following statuses are used to indicate the state of a transaction:

Notes

PENDING: Transaction initiated, awaiting processing
COMPLETED: Transaction successfully processed and funds transferred
FAILED: Transaction declined (e.g., insufficient funds, invalid card)
ABORTED: Customer abandoned the checkout page
CANCELLED: Transaction cancelled by the customer

Transactions API

Initialize Transaction

Headers

Body Parameters

Request Body

Sample Response

Notes

Check Transaction Status

Headers

Path Parameters

Sample Response

Notes

List Transactions

Headers

Query Parameters

Sample Response

Notes

Export Transactions

Headers

Query Parameters

Sample Response

Notes

Transaction Statuses

Notes

ON THIS PAGE