Skip to main content
POST
/
pms
/
transactions
/
initialize
Initialize Transaction
curl --request POST \
  --url https://api.payvessel.com/pms/transactions/initialize/ \
  --header 'Content-Type: <content-type>' \
  --header 'api-key: <api-key>' \
  --header 'api-secret: <api-secret>' \
  --data '
{
  "amount": "5000.00",
  "channels": [
    "BANK_TRANSFER"
  ],
  "currency": "NGN",
  "customer_name": "John Doe",
  "customer_email": "customer@example.com",
  "customer_phone_number": "+2348012345678",
  "redirect_url": "https://yourapp.com/payment/callback"
}
'
{
  "status": true,
  "message": "Checkout transaction successfully initialized",
  "data": {
    "id": "52b9bb2d-01d1-46ac-9800-14d34cb5f882",
    "transaction_ref": "B0C866BD914C487895ACB8C45B939017",
    "amount": "5000.00",
    "status": "PENDING",
    "access_code": "TEST-ACS-7AF7VH-2QIHE83N-TCTL28-BSDH",
    "checkout_url": "https://checkout.payvessel.com/TEST-ACS-7AF7VH-2QIHE83N-TCTL28-BSDH",
    "created_datetime": "2026-04-01T15:46:56.171229"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.payvessel.com/llms.txt

Use this file to discover all available pages before exploring further.

Initialize a new payment transaction to collect money from customers via cards, bank transfers, or mobile wallets.
This endpoint creates a payment session and returns a checkout URL where customers can complete their payment securely.
This is the primary canonical initialization endpoint for both the transaction and checkout flows. It maps to POST /pms/transactions/initialize/, and api-reference/checkout/initialize-transaction is an equivalent alias.

​
Endpoint

POST /pms/transactions/initialize/

​
Headers

NameTypeRequiredDescription
api-keystringRequiredYour API key
api-secretstringRequiredYour API secret
Content-TypestringRequiredMust be application/json

​
Request Body

​
email
string
required
Customer’s email address for transaction receipt and notifications
​
amount
string
required
Transaction amount in naira (NGN) or the smallest currency unit
For ₦500.00, send "500" (500 naira)
​
currency
string
default:"NGN"
Three-letter ISO currency codeSupported currencies: NGN, USD
​
reference
string
Unique transaction reference. If not provided, PayVessel will generate one automatically
Must be unique across all your transactions
​
callback_url
string
URL to redirect customers after payment completion
​
channels
array
Payment methods to allow for this transactionAvailable channels: BANK_TRANSFER
If not specified, all available channels will be enabled
​
customer
object
Customer information object

​
Example Request

curl -X POST https://sandbox.payvessel.com/pms/transactions/initialize/ \
  -H "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "test@example.com",
    "customer_name": "Test Customer",
    "customer_phone_number": "08012345678",
    "amount": "50",
    "currency": "NGN",
    "channels": [
        "BANK_TRANSFER"
    ]
}'

​
Response

​
status
string
Request status indicator - "success" or "error"
​
message
string
Human-readable message describing the result
​
data
object
Transaction data object

​
Example Response

{
  "status": true,
  "message": "Checkout transaction successfully initialized",
  "data": {
    "id": "52b9bb2d-01d1-46ac-9800-14d34cb5f882",
    "transaction_ref": "B0C866BD914C487895ACB8C45B939017",
    "amount": "5000.00",
    "status": "PENDING",
    "access_code": "TEST-ACS-7AF7VH-2QIHE83N-TCTL28-BSDH",
    "checkout_url": "https://checkout.payvessel.com/TEST-ACS-7AF7VH-2QIHE83N-TCTL28-BSDH",
    "created_datetime": "2026-04-01T15:46:56.171229"
  }
}
After initializing a payment:

Verify Payment

Confirm transaction status after payment

Handle Webhooks

Receive real-time payment notifications

​
Webhook Events

This endpoint triggers the following webhook events:
  • transaction.pending - Transaction created and pending payment
  • transaction.success - Payment completed successfully
  • transaction.failed - Payment failed or was declined
Best Practice: Always verify transaction status using the verification endpoint, even after receiving webhook notifications, to ensure data integrity.

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

Body

application/json
​
amount
string
required

Transaction amount in naira (for NGN) or minor currency units

​
channels
enum<string>[]
required

Payment channels to enable for this transaction

Available options:
BANK_TRANSFER
​
currency
enum<string>
required

Transaction currency code

Available options:
NGN,
USD
​
customer_name
string
required

Customer's full name

​
customer_email
string<email>
required

Customer's email address

​
customer_phone_number
string
required

Customer's phone number

​
metadata
object

Additional information about the transaction

​
redirect_url
string<uri>

URL to redirect customer after payment completion

​
reference
string

Unique transaction reference (optional - auto-generated if not provided)

Response

200 - application/json

Transaction initialized successfully

​
status
boolean

Transaction initialization status

​
message
string

Response message

​
data
object