Payments API

The Payments API allows you to create, retrieve, and manage payments. This is the core functionality of iNPAY Checkout.

Create Payment

Create a new payment with the specified amount and customer information.

POST/v2/payments/{payment_id}

Request Body

{
  "amount": 2999,
  "currency": "NGN",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "payment_method": {
    "type": "card",
    "card": {
      "number": "4242424242424242",
      "exp_month": 12,
      "exp_year": 2025,
      "cvc": "123"
    }
  },
  "description": "Payment for order #12345",
  "metadata": {
    "order_id": "12345",
    "product": "Premium Plan"
  }
}

Parameters

Parameter	Type	Required	Description
amount	integer	Yes	Amount in cents (e.g., 2999 = $29.99)
currency	string	Yes	Three-letter ISO currency code
customer	object	Yes	Customer information
customer.email	string	Yes	Customer email address
customer.name	string	No	Customer full name
payment_method	object	Yes	Payment method details
description	string	No	Payment description
metadata	object	No	Additional metadata

Response

{
  "success": true,
  "data": {
    "id": "pay_1234567890",
    "amount": 2999,
    "currency": "NGN",
    "status": "succeeded",
    "customer": {
      "id": "cus_1234567890",
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "payment_method": {
      "id": "pm_1234567890",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2025
      }
    },
    "description": "Payment for order #12345",
    "metadata": {
      "order_id": "12345",
      "product": "Premium Plan"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_1234567890",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "2.0"
  }
}

Example Request

curl -X POST https://api.inpaycheckout.com/v1/payments \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2999,
    "currency": "NGN",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4242424242424242",
        "exp_month": 12,
        "exp_year": 2025,
        "cvc": "123"
      }
    },
    "description": "Payment for order #12345"
  }'

Get Payment

Retrieve details of a specific payment.

GET/v2/payments/{payment_id}

Path Parameters

Parameter	Type	Required	Description
payment_id	string	Yes	The payment ID

Response

{
  "success": true,
  "data": {
    "id": "pay_1234567890",
    "amount": 2999,
    "currency": "NGN",
    "status": "succeeded",
    "customer": {
      "id": "cus_1234567890",
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "payment_method": {
      "id": "pm_1234567890",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2025
      }
    },
    "description": "Payment for order #12345",
    "metadata": {
      "order_id": "12345",
      "product": "Premium Plan"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

List Payments

Retrieve a list of payments with optional filtering and pagination.

GET/v2/payments

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of payments to return (max 100)
cursor	string	No	Cursor for pagination
status	string	No	Filter by payment status
customer_id	string	No	Filter by customer ID
created_after	string	No	Filter payments created after this date
created_before	string	No	Filter payments created before this date

Response

{
  "success": true,
  "data": [
    {
      "id": "pay_1234567890",
      "amount": 2999,
      "currency": "NGN",
      "status": "succeeded",
      "customer": {
        "id": "cus_1234567890",
        "email": "customer@example.com"
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "has_more": true,
      "next_cursor": "eyJpZCI6IjEyMzQ1Njc4OTAifQ==",
      "previous_cursor": null
    }
  }
}

Payment Statuses

Status	Description
pending	Payment is being processed
succeeded	Payment completed successfully
failed	Payment failed
canceled	Payment was canceled
refunded	Payment was refunded
partially_refunded	Payment was partially refunded

Error Codes

Code	Description
INVALID_AMOUNT	Amount must be greater than 0
INVALID_CURRENCY	Currency code is not supported
INVALID_PAYMENT_METHOD	Payment method is invalid
CARD_DECLINED	Card was declined by the bank
INSUFFICIENT_FUNDS	Card has insufficient funds
EXPIRED_CARD	Card has expired
INVALID_CVC	CVC is invalid

Webhooks

Payment events trigger webhooks:

• payment.created - Payment created
• payment.succeeded - Payment completed successfully
• payment.failed - Payment failed
• payment.refunded - Payment refunded

SDK Examples

Node.js

const inpaycheckout = require("inpaycheckout")("sk_test_1234567890abcdef");

// Create payment
const payment = await inpaycheckout.payments.create({
  amount: 2999,
  currency: "NGN",
  customer: {
    email: "customer@example.com",
    name: "John Doe",
  },
  payment_method: {
    type: "card",
    card: {
      number: "4242424242424242",
      exp_month: 12,
      exp_year: 2025,
      cvc: "123",
    },
  },
});

console.log(payment.id);

Python

import inpaycheckout

inpaycheckout.api_key = 'sk_test_1234567890abcdef'

payment = inpaycheckout.Payment.create(
    amount=2999,
    currency='NGN',
    customer={
        'email': 'customer@example.com',
        'name': 'John Doe'
    },
    payment_method={
        'type': 'card',
        'card': {
            'number': '4242424242424242',
            'exp_month': 12,
            'exp_year': 2025,
            'cvc': '123'
        }
    }
)

print(payment.id)

PHP

<?php
require_once 'vendor/autoload.php';

\InPayCheckout\InPayCheckout::setApiKey('sk_test_1234567890abcdef');

$payment = \InPayCheckout\Payment::create([
    'amount' => 2999,
    'currency' => 'NGN',
    'customer' => [
        'email' => 'customer@example.com',
        'name' => 'John Doe'
    ],
    'payment_method' => [
        'type' => 'card',
        'card' => [
            'number' => '4242424242424242',
            'exp_month' => 12,
            'exp_year' => 2025,
            'cvc' => '123'
        ]
    ]
]);

echo $payment->id;
?>