​
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"
    }
  },
  "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?