Payment Orders

Create and manage payment orders - the core transaction record in Paysera Checkout.

Payment orders represent the core transaction record in Paysera Checkout. This guide covers creating and managing orders via the API.

Overview

A payment order contains:

Transaction amount, currency, and your merchant reference (your order ID)
Optional redirect URLs for success/failure/callback
Optional metadata and merchant_data key-value pairs

note

redirect_urls.* fields are optional in the create-order request. Provide them per environment if you need browser redirects after payment.

Amount Format

All amounts in the API use minor currency units (e.g., cents for EUR, pennies for GBP):

Request: String format (e.g., "2500" for €25.00)
Response: Long/integer format (e.g., 2500 for €25.00)

Endpoints

For complete request/response schemas and examples, see the Endpoint Reference:

Method	Endpoint	Reference
POST	`/merchant-order/integration/v1/orders`	Create Order

info

Order state is delivered to your callback_url via webhooks. There is no public GET /orders/{id} endpoint — subscribe to webhooks for status updates instead. See Webhooks.

Order Statuses

Status	Code	Description
Pending Payment	`pending_payment`	Order created, awaiting payment
Paid	`paid`	Order fully paid
Canceled	`canceled`	Order was canceled*
Closed	`closed`	Order closed, no further operations*

*canceled and closed statuses are defined but not yet fully implemented.

See Payment Statuses Reference for complete status documentation.

Code Examples

<?php

function createPaymentOrder(string $accessToken, array $orderData): array
{
    $ch = curl_init('https://api.paysera.com/merchant-order/integration/v1/orders');

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'project_id' => $orderData['project_id'],
            'redirect_urls' => [
                'success_url' => $orderData['success_url'],
                'failure_url' => $orderData['failure_url'],
                'callback_url' => $orderData['callback_url'],
            ],
            'purchase' => [
                'reference' => $orderData['reference'],
                'amount' => (string) $orderData['amount'], // Already in minor units
                'currency' => $orderData['currency'],
            ],
        ]),
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 201) {
        throw new Exception('Failed to create order: ' . $response);
    }

    return json_decode($response, true);
}

// Usage - amount is in minor units (cents)
$order = createPaymentOrder($accessToken, [
    'project_id' => 'your-project-id',
    'success_url' => 'https://your-site.paysera.net/success',
    'failure_url' => 'https://your-site.paysera.net/failure',
    'callback_url' => 'https://your-site.paysera.net/webhook',
    'reference' => 'ORDER-12345',
    'amount' => 2500, // €25.00 in cents
    'currency' => 'EUR',
]);

echo "Order ID: " . $order['order_id'];
// Note: To get a payment URL, create a payment link using this order_id

async function createPaymentOrder(accessToken, orderData) {
  const response = await fetch(
    'https://api.paysera.com/merchant-order/integration/v1/orders',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        project_id: orderData.projectId,
        redirect_urls: {
          success_url: orderData.successUrl,
          failure_url: orderData.failureUrl,
          callback_url: orderData.callbackUrl,
        },
        purchase: {
          reference: orderData.reference,
          amount: String(orderData.amount), // Already in minor units
          currency: orderData.currency,
        },
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to create order: ${await response.text()}`);
  }

  return response.json();
}

// Usage - amount is in minor units (cents)
const order = await createPaymentOrder(accessToken, {
  projectId: 'your-project-id',
  successUrl: 'https://your-site.paysera.net/success',
  failureUrl: 'https://your-site.paysera.net/failure',
  callbackUrl: 'https://your-site.paysera.net/webhook',
  reference: 'ORDER-12345',
  amount: 2500, // €25.00 in cents
  currency: 'EUR',
});

console.log('Order ID:', order.order_id);
// Note: To get a payment URL, create a payment link using this order_id

import requests

def create_payment_order(access_token: str, order_data: dict) -> dict:
    response = requests.post(
        'https://api.paysera.com/merchant-order/integration/v1/orders',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={
            'project_id': order_data['project_id'],
            'redirect_urls': {
                'success_url': order_data['success_url'],
                'failure_url': order_data['failure_url'],
                'callback_url': order_data['callback_url'],
            },
            'purchase': {
                'reference': order_data['reference'],
                'amount': str(order_data['amount']),  # Already in minor units
                'currency': order_data['currency'],
            },
        },
    )

    response.raise_for_status()
    return response.json()

# Usage - amount is in minor units (cents)
order = create_payment_order(access_token, {
    'project_id': 'your-project-id',
    'success_url': 'https://your-site.paysera.net/success',
    'failure_url': 'https://your-site.paysera.net/failure',
    'callback_url': 'https://your-site.paysera.net/webhook',
    'reference': 'ORDER-12345',
    'amount': 2500,  # €25.00 in cents
    'currency': 'EUR',
})

print(f"Order ID: {order['order_id']}")
# Note: To get a payment URL, create a payment link using this order_id

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import kotlinx.serialization.json.*

suspend fun createPaymentOrder(accessToken: String, orderData: OrderData): JsonObject {
    val client = HttpClient.newHttpClient()

    val requestBody = buildJsonObject {
        put("project_id", orderData.projectId)
        putJsonObject("redirect_urls") {
            put("success_url", orderData.successUrl)
            put("failure_url", orderData.failureUrl)
            put("callback_url", orderData.callbackUrl)
        }
        putJsonObject("purchase") {
            put("reference", orderData.reference)
            put("amount", orderData.amount.toString()) // Already in minor units
            put("currency", orderData.currency)
        }
    }

    val request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.paysera.com/merchant-order/integration/v1/orders"))
        .header("Authorization", "Bearer $accessToken")
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(requestBody.toString()))
        .build()

    val response = client.send(request, HttpResponse.BodyHandlers.ofString())

    if (response.statusCode() != 201) {
        throw Exception("Failed to create order: ${response.body()}")
    }

    return Json.parseToJsonElement(response.body()).jsonObject
}

// Usage - amount is in minor units (cents)
val order = createPaymentOrder(accessToken, OrderData(
    projectId = "your-project-id",
    successUrl = "https://your-site.paysera.net/success",
    failureUrl = "https://your-site.paysera.net/failure",
    callbackUrl = "https://your-site.paysera.net/webhook",
    reference = "ORDER-12345",
    amount = 2500, // €25.00 in cents
    currency = "EUR"
))

println("Order ID: ${order["order_id"]}")
// Note: To get a payment URL, create a payment link using this order_id

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type OrderRequest struct {
    ProjectID    string       `json:"project_id"`
    RedirectURLs RedirectURLs `json:"redirect_urls"`
    Purchase     Purchase     `json:"purchase"`
}

type RedirectURLs struct {
    SuccessURL  string `json:"success_url"`
    FailureURL  string `json:"failure_url"`
    CallbackURL string `json:"callback_url"`
}

type Purchase struct {
    Reference string `json:"reference"`
    Amount    string `json:"amount"`
    Currency  string `json:"currency"`
}

func createPaymentOrder(accessToken string, orderData OrderRequest) (map[string]interface{}, error) {
    jsonData, _ := json.Marshal(orderData)

    req, _ := http.NewRequest("POST",
        "https://api.paysera.com/merchant-order/integration/v1/orders",
        bytes.NewBuffer(jsonData))

    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    if resp.StatusCode != 201 {
        return nil, fmt.Errorf("failed to create order: %s", string(body))
    }

    var result map[string]interface{}
    json.Unmarshal(body, &result)
    return result, nil
}

// Usage - amount is in minor units (cents)
func main() {
    order, _ := createPaymentOrder(accessToken, OrderRequest{
        ProjectID: "your-project-id",
        RedirectURLs: RedirectURLs{
            SuccessURL:  "https://your-site.paysera.net/success",
            FailureURL:  "https://your-site.paysera.net/failure",
            CallbackURL: "https://your-site.paysera.net/webhook",
        },
        Purchase: Purchase{
            Reference: "ORDER-12345",
            Amount:    "2500", // €25.00 in cents
            Currency:  "EUR",
        },
    })

    fmt.Printf("Order ID: %s\n", order["order_id"])
    // Note: To get a payment URL, create a payment link using this order_id
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

public class PayseraClient
{
    private readonly HttpClient _httpClient;

    public PayseraClient(string accessToken)
    {
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", accessToken);
    }

    public async Task<JsonDocument> CreatePaymentOrderAsync(OrderData orderData)
    {
        var request = new
        {
            project_id = orderData.ProjectId,
            redirect_urls = new
            {
                success_url = orderData.SuccessUrl,
                failure_url = orderData.FailureUrl,
                callback_url = orderData.CallbackUrl
            },
            purchase = new
            {
                reference = orderData.Reference,
                amount = orderData.Amount.ToString(), // Already in minor units
                currency = orderData.Currency
            }
        };

        var json = JsonSerializer.Serialize(request);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await _httpClient.PostAsync(
            "https://api.paysera.com/merchant-order/integration/v1/orders",
            content);

        var responseBody = await response.Content.ReadAsStringAsync();

        if (!response.IsSuccessStatusCode)
        {
            throw new Exception($"Failed to create order: {responseBody}");
        }

        return JsonDocument.Parse(responseBody);
    }
}

// Usage - amount is in minor units (cents)
var client = new PayseraClient(accessToken);
var order = await client.CreatePaymentOrderAsync(new OrderData
{
    ProjectId = "your-project-id",
    SuccessUrl = "https://your-site.paysera.net/success",
    FailureUrl = "https://your-site.paysera.net/failure",
    CallbackUrl = "https://your-site.paysera.net/webhook",
    Reference = "ORDER-12345",
    Amount = 2500, // €25.00 in cents
    Currency = "EUR"
});

Console.WriteLine($"Order ID: {order.RootElement.GetProperty("order_id")}");
// Note: To get a payment URL, create a payment link using this order_id

Tracking Order Status

There is no public GET /orders/{id} endpoint. Track order state by subscribing to webhooks delivered to your callback_url. The webhook payload contains the full order snapshot, including order.status and nested payment details. See Webhooks and the order event reference.

Error Responses

Validation Error

{
  "error": "invalid_request",
  "error_description": "Validation failed",
  "error_properties": {
    "purchase.amount": ["Amount should be greater than 0"]
  }
}

Invalid Project

{
  "error": "not_found",
  "error_description": "Project not found or access denied"
}

Authentication Failure

{
  "error": "unauthorized",
  "error_description": "Authentication is required to access this resource"
}

Payment Links - Create payment links for orders
Webhooks - Handle payment notifications
Payment Statuses Reference - Complete status reference

Overview​

Endpoints​

Order Statuses​

Code Examples​

Tracking Order Status​

Error Responses​

Validation Error​

Invalid Project​

Authentication Failure​

Related Documentation​