Payments API

Create, retrieve, confirm, and manage payments through the Hyperswitch REST API.

Base URL

base URL

http://localhost:8081

All endpoints require an API key passed via the api-key header.

Create a Payment

POST/payments

Request Body

request body

{
  "amount": 100000,
  "currency": "NGN",
  "confirm": true,
  "capture_method": "automatic",
  "description": "Order #12345",
  "email": "customer@example.com",
  "customer_id": "cus_abc123",
  "metadata": {
    "order_id": "12345"
  },
  "billing": {
    "address": {
      "first_name": "John",
      "last_name": "Doe",
      "line1": "123 Main St",
      "city": "Lagos",
      "state": "Lagos",
      "zip": "100001",
      "country": "NG"
    }
  }
}

Response

response

{
  "payment_id": "pay_xyz789",
  "status": "Succeeded",
  "amount": 100000,
  "currency": "NGN",
  "connector": "paystack",
  "connector_transaction_id": "txn_abc123",
  "created_at": "2026-07-26T10:30:00Z",
  "customer_id": "cus_abc123",
  "description": "Order #12345",
  "email": "customer@example.com",
  "metadata": {
    "order_id": "12345"
  }
}

Retrieve a Payment

GET/payments/{payment_id}

Example

curl

curl -X GET http://localhost:8081/payments/pay_xyz789 \
  -H "api-key: test_api_key_xxxx"

Response

response

{
  "payment_id": "pay_xyz789",
  "status": "Succeeded",
  "amount": 100000,
  "currency": "NGN",
  "connector": "paystack",
  "connector_transaction_id": "txn_abc123",
  "created_at": "2026-07-26T10:30:00Z"
}

List Payments

GET/payments

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of payments to return (default 20, max 100)
`offset`	integer	Number of payments to skip
`status`	string	Filter by status: Succeeded, Failed, Processing, etc.
`created`	object	Date range filter with gt, lt, gte, lte

Example

curl

curl -X GET "http://localhost:8081/payments?limit=10&status=Succeeded" \
  -H "api-key: test_api_key_xxxx"

Confirm a Payment

POST/payments/{payment_id}/confirm

Confirm a payment that was created with confirm: false. This triggers the actual payment processing through the connector.

request body

{
  "payment_method": "card",
  "payment_method_data": {
    "card": {
      "card_number": "4084084084084081",
      "card_exp_month": "12",
      "card_exp_year": "2027",
      "card_cvc": "123"
    }
  }
}

Cancel a Payment

POST/payments/{payment_id}/cancel

Cancel a payment that is in RequiresConfirmation or Processing status.

request body

{
  "cancellation_reason": "Customer requested cancellation"
}

Payment Statuses

Status	Description
`RequiresConfirmation`	Payment created but not yet confirmed
`Processing`	Payment is being processed by the connector
`Succeeded`	Payment completed successfully
`Failed`	Payment failed at the connector
`Cancelled`	Payment was cancelled before processing
`RequiresAction`	Customer action needed (e.g., 3DS redirect)