​
Overview

Card payment initialization is the first step in processing a card payment. This endpoint creates a payment session that can be used to securely process credit and debit card transactions.

​
Endpoint

POST /payment-sessions

​
Request Parameters

​
amount
integer
required
Payment amount in minor units (e.g., cents, kobo)
  • Minimum: 100
  • Must be positive integer
  • Example: 10000 = $100.00 USD
​
currency
string
required
Three-letter ISO currency code
  • Supported: NGN, USD, CAD
  • Must match payment method
  • Example: “USD”
​
customer
object
required
Customer information object
​
description
string
required
Payment description
  • Maximum length: 200 characters
  • Will appear on statements
​
reference
string
required
Unique transaction reference
  • Must be unique per transaction
  • Maximum length: 50 characters
​
payment_method
object
required
Payment method details
​
type
string
required
  • Must be of type: ""
​
order
object
required
Order information object
​
metadata
object
Optional additional data
  • Nested objects allowed

​
Example Requests

{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+2348118873422",
    "billing_address": {
      "line1": "123 Main St",
      "line2": "Suite 456",
      "city": "Springfield",
      "state": "CA",
      "country": "US",
      "zip_code": "12345"
    },
    "ip_address": "127.0.0.1"
  },
  "description": "Premium Package Purchase",
  "currency": "USD",
  "amount": 100000,
  "payment_method": {
    "type": "card"
  },
  "reference": "ord_1234567890",
  "order": {
    "identifier": "ORD12345",
    "items": [
      {
        "name": "Premium Package",
        "type": "digital"
      }
    ]
  }
}

​
Test Cards

Use these test cards in your sandbox environment to simulate different payment scenarios:

​
Response Examples

{
  "data": {
    "auth_type": "3ds",
    "expires_at": "2024-03-01T08:43:08.110470Z",
    "links": {},
    "message": "Created",
    "payment": {
      "amount": 100000,
      "cancellation_reason": null,
      "currency": "USD",
      "customer": {
        "billing_address": {
          "city": "Springfield",
          "country": "US",
          "line1": "123 Main St",
          "line2": "Suite 456",
          "state": "CA",
          "zip_code": "12345"
        },
        "email": "john.doe@example.com",
        "first_name": "John",
        "id": "cust_1234567890",
        "last_name": "Doe",
        "phone_number": "+2348118873422"
      },
      "date": "2024-02-29T20:43:08.344264Z",
      "description": "Premium Package Purchase",
      "id": "pay_1234567890",
      "order": {
        "identifier": "ORD12345",
        "items": [
          {
            "name": "Premium Package",
            "type": "digital"
          }
        ]
      }
      "mode": "live",
      "payment_method": {
        "type": "card"
      },
      "reference": "ord_1234567890",
      "status": "pending"
    },
    "status": "pending"
  }
}

​
Authentication Flows

Some card payments may require additional authentication steps. The response will indicate the required authentication type:
1

3D Secure Authentication

If 3DS is required, you’ll receive:
{
  "data": {
    "auth_type": "3ds",
    "message": "3DS authentication required",
    "links": {
      "redirect_url": "https://3ds.payment-processor.com/auth"
    }
  }
}
Redirect the customer to complete 3DS verification, then:
  1. Listen for webhook notification, or
  2. Poll payment status endpoint
2

OTP Validation

For OTP authentication:
{
  "data": {
    "auth_type": "otp",
    "message": "Please enter OTP to complete transaction"
  }
}
Submit OTP via:
POST /payment-sessions/{payment_id}/authorize
{
  "otp": "123456"
}
3

PIN Verification

For PIN authentication:
{
  "data": {
    "auth_type": "pin",
    "message": "Please enter card PIN"
  }
}
Submit PIN via:
POST /payment-sessions/{payment_id}/authorize
{
  "pin": "1234"
}

​
Security Requirements

​
Error Handling

​
card_declined
error
Card declined by issuing bank
  • Status code: 402
  • Possible reasons:
    • Insufficient funds
    • Suspicious activity
    • Expired card
​
invalid_card
error
Invalid card details provided
  • Status code: 400
  • Check:
    • Card number
    • Expiry date
    • CVV
​
authentication_failed
error
Failed authentication (3DS/OTP/PIN)
  • Status code: 401
  • Verify credentials and retry
Common error scenarios to handle:
  • Invalid currency code
  • Amount below minimum
  • Missing customer information
  • Invalid phone/email format
  • Incorrect billing address
  • Network timeouts

​
Next Steps

After successful initialization:
  1. Handle any required authentication
  2. Capture the payment
  3. Listen for webhook notifications

Need Help?