Payhub API

What is Payhub?

Payhub is a cloud-based payment orchestration platform that connects business platforms (like ERP, CRM, or e-commerce systems) with various payment service providers. It streamlines the entire lifecycle of payment request creation, execution, and monitoring.

Key Features

• Unified API for multiple payment providers (e.g., DIAS, Paygate, Onepay, Klarna, Worldline)

• Webhook support for real-time transaction updates

Who Should Use This API?

This API is designed for developers and integrators working with:

• ERP, CRM, or e-commerce platforms

• Businesses needing to automate or embed payment workflows

💡 Flow: Payment Request Flow

This diagram illustrates the process of creating a payment request through the business platform, Payhub, and the payment provider.

🔗 API Endpoint & Details

For full API specifications, required fields, supported providers, example requests/responses, and error handling, please refer to the Payment Request.

💡 Flow: Payment Flow

This diagram outlines the flow of a typical payment process from the client to the business platform via the payment provider and Payhub.

🔄 Handling Provider Callbacks

Payhub receives callbacks from the payment provider once a transaction is completed. These callbacks include essential payment metadata such as transaction ID, amount, status, and timestamp.

📬 Webhook Notifications to Business Platforms

After recording the payment, Payhub sends a webhook to the business platform using the user-defined URL. The webhook contains all necessary data for the platform to identify and process the transaction.

If a webhook delivery fails, Payhub retries notification delivery asynchronously.

🔁 Merchant Return URL Redirect

For providers where Payhub owns the return page (Level = Payhub in the table below), once checkout completes Payhub redirects the payer's browser to the registration's returnUrlOk/returnUrlNok, appending paymentRequestId as a query parameter, e.g. https://merchant.example.com/checkout/success?paymentRequestId=54321. If a Payment row was created for that attempt, paymentId is appended too, e.g. ...?paymentRequestId=54321&paymentId=98765. Use it to identify the exact attempt in the payments array returned by GET /payment/request/{paymentRequestId} when more than one payment exists for the same request (e.g. after a retry).

For providers where the redirect is configured at the Merchant level, the provider redirects the payer directly and Payhub is not in the loop — neither query parameter is appended, since Payhub never controls that redirect.

💡 Cancellation Overview

Payhub supports cancellation of Klarna payment sessions before the customer completes the payment. This feature allows both customers and registration owners (merchants) to cancel ongoing payment sessions.

✅ Cancellation Rules

💡 Flow: Customer-Initiated Cancellation

This diagram shows how a customer cancels their payment session through Klarna app, and Payhub notifies the business platform.

💡 Flow: Merchant-Initiated Cancellation

This diagram shows how a merchant (registration owner) cancels a payment session through Payhub API.

💡 Refund Overview

Payhub supports refunding a paid Klarna payment through the new refund endpoint:

• POST /api/payhub/v1/payment/{paymentId}/refund

The endpoint accepts:

• Serialnumber header (required)

• Software header (required)

• Idempotency-Key header (optional)

• amount (required; must be greater than 0 and must not exceed the paid payment amount)

• reason (optional, max 255 chars)

This refund flow is temporary Klarna-only.

On success, the endpoint returns 201 Created with a response payload containing:

• refundRequestId

• referenceCode

• status (Requested, Succeeded, Failed)

• providerRefundId (optional)

• paymentId

• requestedAt

Successful Klarna refunds also return this response header:

• Refund-Id: the Klarna refund identifier for the created refund

Payhub uses Refund-Id to populate providerRefundId in the JSON response body. The Klarna response body is not used for refund id extraction.

💡 Flow: Merchant-Initiated Klarna Refund

✅ Refund Rules

• Refund is supported only when provider is klarna.

• Serialnumber and Software headers are required.

• Idempotency-Key is optional and passed to Klarna as Klarna-Idempotency-Key when present.

• Payment must exist and belong to a valid payment request.

• amount is required and must be greater than 0.

• amount cannot exceed the selected payment amount.

• Merchant can only refund payments that belong to their registration.

💡 Registration Overview

Payhub exposes a read-only endpoint so business platforms can retrieve the provider and webhook configuration of the registration behind their API key:

• GET /api/payhub/v1/registration/{registrationId}

Only fields that are safe to expose are returned — no passwords, secrets, application keys, or FTP credentials. A merchant can only retrieve their own registration; the registrationId in the URL must match the registration bound to the calling API key.

💡 Flow: Merchant Retrieves Registration Details

✅ Registration Rules

• The registration returned is always the one bound to the caller's API key — a different registrationId in the URL returns 403.

• Serialnumber and Software headers are required, same as every other API-key endpoint.

• webhook is null when no webhook endpoint is configured for the registration (not an error).

🔗 API Base URLs

🔗 Payhub URLs

🔑 Sandbox Worldline Credentials

• Sandbox-Url: https://developer.cardlink.gr/login-register/#/register

🔑 Sandbox Klarna Credentials and QR

• Username: 3f0fa93f-3302-4009-b749-977834e88e49

• Password: klarna_test_api_IzVHJHQpeTJJc3QqL3ZlP2d3d3B2P2ppY1Y5VTdKbXosM2YwZmE5M2YtMzMwMi00MDA5LWI3NDktOTc3ODM0ZTg4ZTQ5LDEsOFFQai9mM3ZKRnZIRFV2aUNYVVQ2dDNLM205QkhHaWx4c1hDZGkxRUdLRT0

• StaticQR

🔑 Sandbox API Key

ePay: Fixed payment type only

• Scope — Applies to every payment request created with "Provider": "epay". ePay accepts the Fixed payment type only; Open, DynamicQR, StaticQR, FixedOpen, and SplitPay are not supported.

• Impact — A request with any non-Fixed payment type is rejected at validation with 400 Bad Request and the message For epay, payment type must be one of the following: Fixed. The payment request is never forwarded to ePay, so no paylink is issued. Open-amount and QR-based checkouts cannot be created through ePay.

• Workaround — Send "PaymentType": "Fixed" together with a positive Amount. If you need an open-amount or QR-based flow, route those requests to a provider that supports them (e.g. DIAS or OnePay for Open, Klarna for DynamicQR/StaticQR).