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 and currency (in minor units)
Redirect URLs for success/failure/callback
Merchant reference (your order ID)
Optional metadata and merchant data

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
GET	`/merchant-order/integration/v1/orders/{id}`	—

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

Checking Order Status

After creating an order and payment link, monitor the order status:

<?php

function checkOrderStatus(string $accessToken, string $orderId): string
{
    $ch = curl_init("https://api.paysera.com/merchant-order/integration/v1/orders/{$orderId}");

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
        ],
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $order = json_decode($response, true);

    return $order['status']; // 'pending_payment', 'paid', 'canceled', or 'closed'
}

// Check if order is paid
$status = checkOrderStatus($accessToken, $orderId);
if ($status === 'paid') {
    // Fulfill the order
    fulfillOrder($orderId);
}

Error Responses

Validation Error

{
  "error": "validation_error",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "purchase.amount",
      "message": "Amount must be a positive whole number"
    }
  ]
}

Invalid Project

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

Duplicate Reference

{
  "error": "conflict",
  "message": "Order with this reference already exists"
}

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

Overview​

Endpoints​

Order Statuses​

Code Examples​

Checking Order Status​

Error Responses​

Validation Error​

Invalid Project​

Duplicate Reference​

Related Documentation​