API Integration Guide

Direct REST API integration for developers who prefer maximum control.

This guide covers direct API integration with Paysera Checkout for developers who prefer maximum control or are integrating from languages other than PHP.

Overview

Checkout provides a RESTful API for all payment operations. The main APIs are:

API	Base Path	Purpose
Orders	/merchant-order/integration/v1/	Create and manage payment orders
Payment Links	/checkout-payment-link/integration/v1/	Generate shareable payment URLs
Payment Methods	/checkout-project/integration/v1/	Query available payment options

OpenAPI Specification

Download the complete API specification for use with your favorite API tools:

Download OpenAPI Spec (YAML)

Import this file into tools like:

• Postman - for API testing and exploration
• Insomnia - for REST client testing
• Swagger Editor - for viewing and editing

Base URL

https://api.paysera.com

Authentication

All API requests require OAuth2 Bearer token authentication:

curl -X POST https://api.paysera.com/auth/realms/Paysera/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Use the returned access_token in subsequent requests:

curl -X GET https://api.paysera.com/checkout-project/integration/v1/methods \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

See Authentication for detailed setup.

Request Format

• All requests use JSON format
• Include Content-Type: application/json header for POST/PUT requests
• Amounts are in minor currency units as strings: "amount": "1000" = €10.00

Amount Format

All amounts use minor currency units (e.g., cents for EUR):

• Request: String format (e.g., "1000" for €10.00)
• Response: Long/integer format (e.g., 1000 for €10.00)

Response Format

All responses follow a consistent JSON structure with Unix timestamps:

{
  "id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
  "status": "pending_payment",
  "createdAt": 1736433000,
  "updatedAt": 1736433000
}

Timestamps

All timestamps are Unix epoch (seconds since 1970-01-01), not ISO 8601.

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "validation_error",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "amount",
      "message": "Amount must be greater than 0"
    }
  ]
}

Common status codes:

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or expired token
403	Forbidden - Insufficient permissions
404	Not Found
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

All integration API endpoints are rate limited to 50 requests per minute per client IP address.

When the limit is exceeded, the API returns HTTP 429 Too Many Requests. Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Total requests allowed in the current time window
X-RateLimit-Remaining	Requests remaining in the current time window
X-RateLimit-Reset	Seconds until the rate limit window resets

Integration Guides

• Payment Orders - Creating and managing orders
• Payment Links - Generating payment URLs
• Webhooks - Handling payment notifications

Quick Start Example

Here's a minimal example to create a payment:

# 1. Get access token
TOKEN=$(curl -s -X POST https://api.paysera.com/auth/realms/Paysera/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
  | jq -r '.access_token')

# 2. Create order (amount in minor units: 1000 = €10.00)
ORDER_ID=$(curl -s -X POST https://api.paysera.com/merchant-order/integration/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "redirect_urls": {
      "success_url": "https://example.com/success",
      "failure_url": "https://example.com/failure",
      "callback_url": "https://example.com/webhook"
    },
    "purchase": {
      "reference": "ORDER-001",
      "amount": "1000",
      "currency": "EUR"
    }
  }' | jq -r '.id')

# 3. Create payment link
PAYMENT_URL=$(curl -s -X POST https://api.paysera.com/checkout-payment-link/integration/v1/payment-links \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"order_id\": \"$ORDER_ID\",
    \"name\": \"Order #001\",
    \"amount\": \"1000\",
    \"currency\": \"EUR\",
    \"language\": \"en\",
    \"link_lifetime\": 3600
  }" | jq -r '.link.url')

echo "Payment URL: $PAYMENT_URL"