Card Payment Initialization

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

integer

required

Payment amount in minor units (e.g., cents, kobo)

Minimum: 100
Must be positive integer
Example: 10000 = $100.00 USD

string

required

ISO currency code

Supported: NGN, USD, CAD, USDT, USDC
Must match payment method
Example: “USD”

object

required

Customer information object

Show Customer Fields

string

required

Valid email address

string

required

Customer’s first name

string

required

Customer’s last name

string

required

Phone number in E.164 format

object

required

Billing address details

string

required

Must be of type business or individual

string

required

Customer’s ip address

Must be ipv4 e.g 127.0.0.1

string

required

Payment description

Maximum length: 200 characters
Will appear on statements

string

required

Unique transaction reference

Must be unique per transaction
Maximum length: 50 characters

object

required

Payment method details

string

required

Must be of type: ""

object

required

Order information object

Show Order Fields

string

required

Unique identifier

object[]

required

Show Items Fields

string

required

string

required

type must be one of digital,physical

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

{
  "customer": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "phone_number": "+2348012345678",
    "billing_address": {
      "line1": "10 Victoria Island",
      "city": "Lagos",
      "state": "Lagos",
      "country": "NG",
      "zip_code": "23401"
    },
    "ip_address": "127.0.0.1"
  },
  "description": "International Purchase",
  "currency": "NGN",
  "amount": 500000,
  "payment_method": {
    "type": "card"
  },
  "reference": "ord_intl_12345",
  "order": {
    "identifier": "INTL12345",
    "items": [
      {
        "name": "International Package",
        "type": "digital"
      }
    ]
  },
}

Test Cards

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

Successful Payments

VISA Test Card (NGN)

Card Number: 4012000033330026
Expiry Date: 01/39
CVV: 100

Mastercard Test Card (USD)

Card Number: 5123450000000008
Expiry Date: 12/25
CVV: 100

3DS Authentication Required

VISA 3DS Test Card

Card Number: 4761530000000008
Expiry Date: 05/25
CVV: 100
Test OTP: 123456

Mastercard 3DS Test Card

Card Number: 5200000000001005
Expiry Date: 12/25
CVV: 100
Test OTP: 123456

Failed Transactions

Insufficient Funds

Card Number: 4000000000000010
Expiry Date: 01/25
CVV: 100

Declined Card

Card Number: 4000000000000002
Expiry Date: 01/25
CVV: 100

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

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": {
      "amount": ["Amount must be at least 100000"]
    }
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid parameters",
    "details": {
      "currency": ["Currency must be one of: NGN, USD, CAD"]
    }
  }
}

Authentication Flows

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

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:

Listen for webhook notification, or
Poll payment status endpoint

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

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

Data Encryption

All card data must be encrypted before transmission
Use our encryption guide for implementation
Never log or store raw card details

PCI Compliance

Use our secure payment fields when collecting card data
Follow PCI DSS requirements if handling card data
Implement proper data sanitization

API Authentication

Use HTTPS for all API calls
Include proper authorization headers
Rotate API keys regularly

Error Handling

error

Card declined by issuing bank

Status code: 402
Possible reasons:
- Insufficient funds
- Suspicious activity
- Expired card

error

Invalid card details provided

Status code: 400
Check:
- Card number
- Expiry date
- CVV

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:

Handle any required authentication
Capture the payment
Listen for webhook notifications

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Card Payment Initialization

Overview

Endpoint

Request Parameters

Example Requests

Test Cards

Response Examples

Authentication Flows

Security Requirements

Error Handling

Next Steps

Need Help?

​Overview

​Endpoint

​Request Parameters

​Example Requests

​Test Cards

​Response Examples

​Authentication Flows

​Security Requirements

​Error Handling

​Next Steps

Need Help?

Overview

Endpoint

Request Parameters

Example Requests

Test Cards

Response Examples

Authentication Flows

Security Requirements

Error Handling

Next Steps