Skip to main content

​
Initialize Payment

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.

​
Endpoint

POST /transaction/initialize

​
Headers

NameTypeRequiredDescription
AuthorizationstringRequiredBearer token with your secret API key
Content-TypestringRequiredMust be application/json
Idempotency-KeystringOptionalUnique key to prevent duplicate transactions

​
Request Body

​
email
string
required
Customer’s email address for transaction receipt and notifications
​
amount
string
required
Transaction amount in kobo (NGN) or the smallest currency unit
For ₦500.00, send "50000" (500 × 100 kobo)
​
currency
string
default:"NGN"
Three-letter ISO currency codeSupported currencies: NGN, USD, GBP, EUR, GHS, KES, ZAR
​
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
​
metadata
object
Additional information about the transaction in key-value pairs
{
  "custom_fields": [
    {
      "display_name": "Cart ID",
      "variable_name": "cart_id", 
      "value": "8393"
    }
  ],
  "customer_id": "12345",
  "order_id": "ORD-2024-001"
}
​
channels
array
Payment methods to allow for this transactionAvailable channels: card, bank, ussd, qr, mobile_money, bank_transfer
If not specified, all available channels will be enabled
​
customer
object
Customer information object

​
Example Request

curl -X POST https://api.payvessel.com/transaction/initialize \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn_2024_001" \
  -d '{
    "email": "[email protected]",
    "amount": "50000",
    "currency": "NGN",
    "reference": "TXN_2024_001",
    "callback_url": "https://yourapp.com/payment/callback",
    "channels": ["card", "bank", "ussd"],
    "customer": {
      "first_name": "John",
      "last_name": "Doe", 
      "phone": "+2348012345678"
    },
    "metadata": {
      "custom_fields": [
        {
          "display_name": "Order ID",
          "variable_name": "order_id",
          "value": "ORD_001"
        }
      ]
    }
  }'

​
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": "success",
  "message": "Transaction initialized successfully",
  "data": {
    "authorization_url": "https://checkout.payvessel.com/TXN_2024_001",
    "access_code": "rk_live_abc123xyz789",
    "reference": "TXN_2024_001",
    "amount": 50000,
    "currency": "NGN",
    "status": "pending",
    "created_at": "2024-01-15T14:30:00Z"
  }
}

​
Integration Flow

1

Initialize Transaction

Make a POST request to /transaction/initialize with transaction details
2

Redirect Customer

Redirect your customer to the authorization_url from the response
3

Customer Completes Payment

Customer enters payment details and completes the transaction
4

Handle Callback

Customer is redirected to your callback_url with transaction status
5

Verify Transaction

Use the Verify Transaction endpoint to confirm payment status

​
Next Steps

After initializing a payment:

Verify Payment

Confirm transaction status after payment

Handle Webhooks

Receive real-time payment notifications

Process Refunds

Handle refund requests when needed

View Transactions

Retrieve transaction history

​
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.