API Documentation

Build powerful payment experiences with PayGate's comprehensive API

Getting Started

PayGate API is designed to be simple and intuitive. All requests are made to api.paygate.liper.io over HTTPS.

Authentication is handled via API keys. Include your API key in the Authorization header as a Bearer token.

curl -X GET https://api.paygate.liper.io/v1/transactions \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json"

Authentication

API Keys

Each PayGate account comes with two API keys: a publishable key and a secret key. Use the secret key for server-side requests only.

Live Secret Key:

sk_live_51234567890abcdef

⚠️ Security Note: Never expose your secret key in client-side code. Always keep it server-side only.

Core Endpoints

Create Payment

Initialize a new payment transaction

POST /v1/payments

Request Body

{
  "amount": 10000,
  "currency": "NGN",
  "customer_id": "cust_abc123",
  "customer_email": "customer@example.com",
  "description": "Order #12345",
  "escrow": true,
  "metadata": {
    "order_id": "12345",
    "user_id": "user_xyz"
  }
}

Response

{
  "id": "txn_1234567890",
  "status": "pending",
  "amount": 10000,
  "currency": "NGN",
  "customer_id": "cust_abc123",
  "escrow": true,
  "payment_link": "https://pay.paygate.io/txn_1234567890",
  "created_at": "2024-03-29T12:30:00Z",
  "expires_at": "2024-03-30T12:30:00Z"
}

Get Payment Details

Retrieve details of a specific transaction

GET /v1/payments/{id}

Example Request

curl -X GET https://api.paygate.liper.io/v1/payments/txn_1234567890 \
  -H "Authorization: Bearer sk_live_xxxxx"

Response

{
  "id": "txn_1234567890",
  "status": "completed",
  "amount": 10000,
  "currency": "NGN",
  "customer_id": "cust_abc123",
  "escrow": true,
  "escrow_status": "held",
  "payment_method": "card",
  "card_last4": "4242",
  "metadata": {...},
  "created_at": "2024-03-29T12:30:00Z",
  "completed_at": "2024-03-29T12:31:00Z"
}

Release Escrow Funds

Release held escrow funds to the recipient

POST /v1/payments/{id}/release

Request Body

{
  "reason": "service_completed",
  "metadata": {
    "released_by": "merchant_id"
  }
}

Response

{
  "id": "txn_1234567890",
  "status": "completed",
  "escrow_status": "released",
  "released_at": "2024-03-29T13:00:00Z",
  "settlement_reference": "sett_1234567890"
}

Refund Payment

Create a full or partial refund for a completed transaction

POST /v1/payments/{id}/refund

Request Body

{
  "amount": 5000,
  "reason": "customer_request",
  "notes": "Partial refund for cancelled item"
}

Webhooks

Webhooks allow you to receive real-time notifications about payment events. Configure your webhook endpoint in the PayGate dashboard.

Webhook Events

payment.created

A new payment has been initiated

payment.pending

Payment is awaiting confirmation

payment.completed

Payment has been successfully completed

payment.failed

Payment attempt failed

escrow.held

Funds have been held in escrow

escrow.released

Escrow funds have been released

payment.refunded

Payment has been refunded

Webhook Payload

{
  "id": "evt_1234567890",
  "type": "payment.completed",
  "data": {
    "id": "txn_1234567890",
    "status": "completed",
    "amount": 10000,
    "currency": "NGN",
    "customer_id": "cust_abc123"
  },
  "created_at": "2024-03-29T12:31:00Z"
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a detailed error message.

200

OK - Request succeeded

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid or missing API key

403

Forbidden - Access denied

404

Not Found - Resource does not exist

429

Too Many Requests - Rate limit exceeded

500

Internal Server Error

SDKs & Libraries

JavaScript

npm install @paygate/sdk

Python

pip install paygate-sdk

Go

go get github.com/paygate/sdk-go

Need Help?

Check our comprehensive guides, contact our support team, or join our developer community.