​
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., kobo, cents)

  • Minimum: 10000

  • Examples:

    • 10000 (NGN 100.00)

    • 150000 (USD 1,500.00)

​
currency
string
required

Three-letter currency code

  • Supported values: NGN, USD, CAD

  • Must match the payment method’s supported currencies

​
description
string
required

Description of the payment transaction

  • Maximum length: 255 characters

  • Will appear on customer’s statement

​
payment_method
object
required

Payment method details

{
  "type": "card"
}
​
customer
object
required

Customer information object

​
direction
string
default:"incoming"

Payment direction

  • Valid values: incoming, outgoing
​
reference
string
required

Unique reference for the payment

  • Must be unique across all transactions

  • Alphanumeric characters only

​
metadata
object
required

Additional transaction data

{
  "order": {
    "identifier": string,
    "items": [{
      "name": string,
      "type": "physical" | "digital"
    }]
  }
}

​
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",
  "metadata": {
    "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",
      "metadata": {
        "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?