Initialize Payment

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"
  }
}

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"
  }
}

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/

Request Body

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

Show Customer Object

customer.email

string

Customer’s email address (alternative to root-level email)

customer.first_name

string

Customer’s first name

customer.last_name

string

Customer’s last name

customer.phone

string

Customer’s phone number in international format

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

Show Data Object

data.authorization_url

string

Secure checkout URL where customers complete payment

data.access_code

string

Access code for the transaction session

data.reference

string

Unique transaction reference

data.amount

integer

Transaction amount in the smallest currency unit

data.currency

string

Transaction currency code

data.status

string

Current transaction status - "pending"

data.created_at

string

ISO 8601 timestamp when transaction was created

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

Show child attributes

API Reference Verify Payment

​Endpoint

​Request Body

​Example Request

​Response

​Example Response

Verify Payment

Handle Webhooks

​Webhook Events

Headers

Body

Response

Endpoint

Request Body

Example Request

Response

Example Response

Webhook Events