Skip to main content
Initialize a checkout transaction for the Checkout flow. This endpoint creates a temporary session and returns a checkout_url where you can redirect your customer to complete their payment.

​
Endpoint

POST /pms/transactions/initialize/

​
Headers

NameTypeRequiredDescription
api-keystringRequiredBusiness API key
api-secretstringRequiredBusiness API secret
Content-TypestringRequiredMust be application/json

​
Request Body

​
amount
string
required
Amount to charge in the smallest currency unit (e.g., "10000" for ₦100.00).
​
currency
string
default:"NGN"
Currency code for the transaction.
​
channels
array
List of enabled payment methods. Options: ["BANK_TRANSFER", "CARD"].
​
customer_name
string
required
The customer’s full name.
​
customer_email
string
required
The customer’s email address.
​
customer_phone_number
string
required
The customer’s phone number.
​
reference
string
Your unique transaction reference. If not provided, PayVessel will generate one.
​
redirect_url
string
The URL users should be redirected to after payment.
​
webhook_url
string
The URL to receive webhook notifications about the transaction.
​
metadata
string
Additional data you want to store with the transaction.

​
Response

​
status
boolean
Request status - true or false.
​
message
string
Description of the result.
​
data
object

​
Example Request

curl -X POST https://api.payvessel.com/pms/transactions/initialize/ \
  -H "api-key: your_api_key" \
  -H "api-secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500000",
    "currency": "NGN",
    "channels": ["BANK_TRANSFER", "CARD"],
    "customer_name": "John Doe",
    "customer_email": "customer@example.com",
    "customer_phone_number": "+2348012345678",
    "redirect_url": "https://yourapp.com/payment/callback",
    "webhook_url": "https://yourapp.com/webhook"
  }'

​
Example Response

{
    "status": true,
    "message": "Checkout transaction successfully initialized",
    "data": {
        "id": "21d0c799-fbb5-473e-856d-1b2f9ada9d8a",
        "transaction_ref": "<string>",
        "amount": "5000.00",
        "status": "PENDING",
        "access_code": "ABC-I77VVH-EROP40XN-TCGOTP-ABCD",
        "checkout_url": "https://checkout.payvessel.com/ACS-I77VVH-EROP40XN-ABCD-XCN4",
        "created_datetime": "2026-03-25T16:39:25.872400"
    }
}