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

import requests

url = "https://api.payvessel.com/pms/transactions/initialize/"

payload = {
    "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"
}
headers = {
    "api-key": "<api-key>",
    "api-secret": "<api-secret>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'api-key': '<api-key>',
    'api-secret': '<api-secret>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.payvessel.com/pms/transactions/initialize/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payvessel.com/pms/transactions/initialize/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "api-key: <api-key>",
    "api-secret: <api-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payvessel.com/pms/transactions/initialize/"

	payload := strings.NewReader("{\n  \"amount\": \"5000.00\",\n  \"channels\": [\n    \"BANK_TRANSFER\"\n  ],\n  \"currency\": \"NGN\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"customer@example.com\",\n  \"customer_phone_number\": \"+2348012345678\",\n  \"redirect_url\": \"https://yourapp.com/payment/callback\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("api-secret", "<api-secret>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.payvessel.com/pms/transactions/initialize/")
  .header("api-key", "<api-key>")
  .header("api-secret", "<api-secret>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"amount\": \"5000.00\",\n  \"channels\": [\n    \"BANK_TRANSFER\"\n  ],\n  \"currency\": \"NGN\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"customer@example.com\",\n  \"customer_phone_number\": \"+2348012345678\",\n  \"redirect_url\": \"https://yourapp.com/payment/callback\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.payvessel.com/pms/transactions/initialize/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"amount\": \"5000.00\",\n  \"channels\": [\n    \"BANK_TRANSFER\"\n  ],\n  \"currency\": \"NGN\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"customer@example.com\",\n  \"customer_phone_number\": \"+2348012345678\",\n  \"redirect_url\": \"https://yourapp.com/payment/callback\"\n}"

response = http.request(request)
puts response.read_body

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

import requests

url = "https://api.payvessel.com/pms/transactions/initialize/"

payload = {
    "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"
}
headers = {
    "api-key": "<api-key>",
    "api-secret": "<api-secret>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'api-key': '<api-key>',
    'api-secret': '<api-secret>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.payvessel.com/pms/transactions/initialize/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payvessel.com/pms/transactions/initialize/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "api-key: <api-key>",
    "api-secret: <api-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payvessel.com/pms/transactions/initialize/"

	payload := strings.NewReader("{\n  \"amount\": \"5000.00\",\n  \"channels\": [\n    \"BANK_TRANSFER\"\n  ],\n  \"currency\": \"NGN\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"customer@example.com\",\n  \"customer_phone_number\": \"+2348012345678\",\n  \"redirect_url\": \"https://yourapp.com/payment/callback\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("api-secret", "<api-secret>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.payvessel.com/pms/transactions/initialize/")
  .header("api-key", "<api-key>")
  .header("api-secret", "<api-secret>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"amount\": \"5000.00\",\n  \"channels\": [\n    \"BANK_TRANSFER\"\n  ],\n  \"currency\": \"NGN\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"customer@example.com\",\n  \"customer_phone_number\": \"+2348012345678\",\n  \"redirect_url\": \"https://yourapp.com/payment/callback\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.payvessel.com/pms/transactions/initialize/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"amount\": \"5000.00\",\n  \"channels\": [\n    \"BANK_TRANSFER\"\n  ],\n  \"currency\": \"NGN\",\n  \"customer_name\": \"John Doe\",\n  \"customer_email\": \"customer@example.com\",\n  \"customer_phone_number\": \"+2348012345678\",\n  \"redirect_url\": \"https://yourapp.com/payment/callback\"\n}"

response = http.request(request)
puts response.read_body

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

string

required

Transaction amount in naira (NGN) or the smallest currency unit

For ₦500.00, send "500" (500 naira)

string

default:"NGN"

Three-letter ISO currency codeSupported currencies: NGN, USD

string

Unique transaction reference. If not provided, PayVessel will generate one automatically

Must be unique across all your transactions

string

URL to redirect customers after payment completion

array

Payment methods to allow for this transactionAvailable channels: BANK_TRANSFER

If not specified, all available channels will be enabled

object

Customer information object

Show Customer Object

string

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

string

Customer’s first name

string

Customer’s last name

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

const payvessel = require('payvessel')(process.env.PAYVESSEL_SECRET_KEY);

const transaction = await payvessel.transaction.initialize({
  email: 'customer@example.com',
  amount: '50',
  currency: 'NGN',
  reference: 'TXN_2024_001',
  callback_url: 'https://yourapp.com/payment/callback',
  channels: ['BANK_TRANSFER'],
  customer: {
    first_name: 'John',
    last_name: 'Doe',
    phone: '+2348012345678'
  }
});

<?php
$payvessel = new \Payvessel\Payvessel(getenv('PAYVESSEL_SECRET_KEY'));

$transaction = $payvessel->transaction->initialize([
  'email' => 'customer@example.com',
  'amount' => '50',
  'currency' => 'NGN',
  'reference' => 'TXN_2024_001',
  'callback_url' => 'https://yourapp.com/payment/callback',
  'channels' => ['BANK_TRANSFER'],
  'customer' => [
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone' => '+2348012345678'
  ]
]);
?>

import payvessel

payvessel.api_key = os.environ['PAYVESSEL_SECRET_KEY']

transaction = payvessel.Transaction.initialize(
    email='customer@example.com',
    amount='50',
    currency='NGN',
    reference='TXN_2024_001',
    callback_url='https://yourapp.com/payment/callback',
    channels=['BANK_TRANSFER'],
    customer={
        'first_name': 'John',
        'last_name': 'Doe',
        'phone': '+2348012345678'
    }
)

Response

string

Request status indicator - "success" or "error"

string

Human-readable message describing the result

object

Transaction data object

Show Data Object

string

Secure checkout URL where customers complete payment

string

Access code for the transaction session

string

Unique transaction reference

integer

Transaction amount in the smallest currency unit

string

Transaction currency code

string

Current transaction status - "pending"

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

{
  "success": false,
  "message": "amount must be at least 50",
  "details": [
    {
      "code": "invalid",
      "detail": "amount must be at least 50",
      "attr": "amount"
    },
    {
      "code": "required",
      "detail": "This field is required.",
      "attr": "channels"
    },
    {
      "code": "blank",
      "detail": "This field may not be blank.",
      "attr": "customer_email"
    }
  ]
}

{
  "status": "error",
  "message": "Unauthorized. Please check your API key"
}

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

Getting Started

Transactions

Virtual Accounts

Issuing

Transfer

Wallets

Identity Verification

Value Added Services

Webhook

Initialize 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

Verify Payment

Handle Webhooks

​Webhook Events

Headers

Body

Response

Endpoint

Request Body

Example Request

Response

Example Response

Webhook Events