Skip to main content

Payment Flow

This page describes the standard payment collection flow using Paysera Checkout API.

Overview​

Payment collection consists of two related methods:

  1. Standard payment collection flow - Completed by user interaction
  2. Recurring billing flow - Automated and made from your project via API calls

Both approaches begin with initializing a Payment Request, but differ in how payments are finalized.

Standard Payment Flow​

The standard payment flow involves four main steps:

Step 1: Create Payment Request​

Create a payment request via POST to /checkout/rest/v1/payment-requests

Required parameters:

  • business_id - Your business identifier
  • order_id - Your unique order reference
  • price - Amount and currency
  • description - Payment description
  • method_key - Payment method (e.g., "card")
  • payer - Customer email
  • locale - Language code (e.g., "en")
  • accept_url - Redirect URL after successful payment
  • cancel_url - Redirect URL if payment is canceled
  • callback_url - URL for payment notifications

For recurring billing, add:

{
  "token_strategy": "required"
}

Response contains:

  • id - Payment request ID
  • authorization_url - URL to redirect customer
  • status - Initial status "new"

Step 2: Redirect Customer​

Redirect the customer to the authorization_url received in Step 1.

What happens:

  • Customer selects payment method
  • Completes payment at payment provider
  • After completion, customer is redirected to your accept_url
  • If canceled, customer is redirected to cancel_url

Step 3: Receive Notification​

Paysera sends a POST request to your callback_url with a notification_id parameter.

Example callback:

POST https://yoursite.com/payment/callback
Content-Type: application/x-www-form-urlencoded

notification_id=12345

Your server must:

  1. Retrieve notification details: GET /notification/rest/v1/notifications/{notification_id}
  2. Check the event field (e.g., "payment_request.captured")
  3. Verify status is "captured"
  4. Process the payment in your system

Notification response contains:

  • event - Event type. Possible values:
    • payment_request.captured - payment was completed and funds were captured
    • payment_request.checkout_token_issued - a recurring billing token was issued without capturing funds (used together with parameters.refund_on_capture: true, see Recurring Billing Flow)
  • status - Notification status (new or read)
  • data.payment_request - The Payment Request resource. Contains, among others:
    • status - Payment status
    • order_id
    • price / price_paid - Amount and currency
    • payer - Customer information (name, surname, account_number if available)
    • issued_token - Token for recurring payments (only when token_strategy: "required" was set on the initial Payment Request)

Step 4: Mark Notification as Read​

After processing, mark the notification as read: PUT /notification/rest/v1/notifications/{notification_id}/read

Critical

You must mark notifications as read. If you don't, Paysera will retry the callback multiple times until it's marked as read.

Payment Request Statuses​

Payment requests have the following statuses:

  • new - Payment request created, awaiting customer payment
  • captured - Payment successfully completed
  • canceled - Payment was refunded or canceled

Notification Statuses​

Notifications have their own status lifecycle:

  • new - Notification created, not yet processed
  • read - Notification has been marked as processed

API Endpoints​

Payment Request API:

  • Host: checkout-eu-a.paysera.com
  • Create: POST /checkout/rest/v1/payment-requests

Notification Event API:

  • Host: checkout-eu-a.paysera.com
  • Get notification: GET /notification/rest/v1/notifications/{id}
  • Mark as read: PUT /notification/rest/v1/notifications/{id}/read

Authentication: All requests require MAC authentication headers.

Flow Diagram​

┌─────────────────────────────────────────────────────────────┐
│ Step 1: Create Payment Request                             │
│ POST /checkout/rest/v1/payment-requests                     │
│ → Receive authorization_url                                 │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Redirect Customer                                   │
│ → Customer goes to authorization_url                        │
│ → Customer completes payment                                │
│ → Customer redirected to accept_url or cancel_url           │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 3: Receive Notification (async)                        │
│ POST to your callback_url with notification_id              │
│ → GET /notification/rest/v1/notifications/{id}              │
│ → Check event: "payment_request.captured"                   │
│ → Extract payment details and issued_token                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 4: Mark as Read                                        │
│ PUT /notification/rest/v1/notifications/{id}/read           │
│ → Prevent callback retries                                  │
└─────────────────────────────────────────────────────────────┘

Important Notes​

  • Domain provided with credentials: The API domain is provided together with your credentials
  • Token strategy: If you want recurring billing, use "token_strategy": "required" in the initial payment request
  • Supported payment methods: When using token_strategy, only payment methods that support tokens are available
  • Callback retries: Callbacks will be repeated multiple times until marked as read
  • Libraries available: Use official Paysera libraries for easier integration

Next Steps​