Quick Start

Get started with OctaPay API in minutes. Our RESTful API is designed to be simple, predictable, and easy to use.

Authentication

All API requests require authentication using your API key. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create a Payment

Create a new payment session for your customer.

Request Body

{
  "amount": 5000,
  "currency": "EUR",
  "description": "Order #12345",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "metadata": {
    "order_id": "12345"
  }
}

Response

{
  "id": "pay_1234567890",
  "status": "pending",
  "amount": 5000,
  "currency": "EUR",
  "checkout_url": "https://checkout.ledgepay.com/pay_1234567890",
  "created_at": "2024-01-15T10:30:00Z"
}

Retrieve a Payment

Get the details of a specific payment.

Response

{
  "id": "pay_1234567890",
  "status": "succeeded",
  "amount": 5000,
  "currency": "EUR",
  "description": "Order #12345",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "metadata": {
    "order_id": "12345"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:15Z"
}

List Payments

Retrieve a list of payments with optional filters.

Query Parameters

• limit - Number of results (default: 10, max: 100)
• status - Filter by status: pending, succeeded, failed, canceled
• created_after - ISO 8601 timestamp
• created_before - ISO 8601 timestamp

Create a Refund

Refund a payment partially or fully.

Request Body

{
  "payment_id": "pay_1234567890",
  "amount": 2500,
  "reason": "customer_request"
}

Webhooks

Receive real-time notifications about payment events.

Event Types

• payment.succeeded - Payment completed successfully
• payment.failed - Payment failed
• payment.canceled - Payment canceled by customer
• refund.created - Refund issued
• refund.succeeded - Refund completed

Webhook Payload Example

{
  "event": "payment.succeeded",
  "timestamp": "2024-01-15T10:32:15Z",
  "data": {
    "id": "pay_1234567890",
    "amount": 5000,
    "currency": "EUR",
    "metadata": {
      "order_id": "12345"
    }
  }
}

Error Codes

Common HTTP status codes you may encounter:

Rate Limits

API requests are limited to prevent abuse:

• Standard: 100 requests per minute
• Enterprise: 1,000 requests per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1610712000

SDKs & Libraries

Official libraries to integrate OctaPay faster: