Payment Request

/api/payhub/v1/payment/request

Creates a new payment request with the provided details

Request parameters

{
	"Debtor": {
		"CompanyName": "Softone S.A.",
		"Name": "John Doe",
		"VRN": "094123456",
		"Email": "john.doe@example.com",
		"Phone": "+302101234567"
	},
	"Currency": "EUR",
	"Country": "GR",
	"Locale": "el-GR",
	"Provider": "dias",
	"PaymentType": "Fixed",
	"Amount": 125.50,
	"Description": "Invoice INV-2026-0042",
	"Store": {
		"Code": "ATH001",
		"TerminalCode": "TERM1234",
		"Address": {
			"City": "Athens",
			"Country": "GR",
			"Postal_code": "10434",
			"Street_address": "Ermou 12"
		}
	}
}

{
	"Provider": "dias",
	"PaymentType": "Fixed",
	"Amount": 100.00
}

{
	"Provider": "onepay",
	"PaymentType": "Fixed",
	"Amount": 100.00
}

{
	"Provider": "paygate",
	"PaymentType": "Fixed",
	"Amount": 100.00
}

{
	"Provider": "klarna",
	"PaymentType": "DynamicQR",
	"Amount": 100.00,
	"TaxAmount": 0.00,
	"Store": {
		"Code": "ATH001",
		"TerminalCode": "TERM1234",
		"Address": {
			"City": "Athens",
			"Country": "GR",
			"Postal_code": "10434",
			"Street_address": "Ermou 12"
		}
	},
	"OrderLines": [
		{
			"Name": "Item 1",
			"Quantity": 1,
			"UnitPrice": 100.00,
			"TotalAmount": 100.00,
			"Type": "physical"
		}
	]
}

{
	"Provider": "klarna",
	"PaymentType": "StaticQR",
	"ShortCode": "STORE-ATHENS-01",
	"Amount": 100.00,
	"TaxAmount": 0.00,
	"Store": {
		"Code": "ATH001",
		"TerminalCode": "TERM1234",
		"Address": {
			"City": "Athens",
			"Country": "GR",
			"Postal_code": "10434",
			"Street_address": "Ermou 12"
		}
	},
	"Description": "Static QR checkout",
	"OrderLines": [
		{
			"Name": "Item 1",
			"Quantity": 1,
			"UnitPrice": 100.00,
			"TotalAmount": 100.00,
			"Type": "physical"
		}
	]
}

{
	"Provider": "worldline",
	"PaymentType": "Fixed",
	"Amount": 100.00,
	"Debtor": {
		"Email": "john.doe@example.com"
	}
}

{
	"Provider": "viva",
	"PaymentType": "Fixed",
	"Amount": 100.00
}

{
	"Provider": "nexi",
	"PaymentType": "Fixed",
	"Amount": 100.00
}

{
	"Provider": "dias",
	"PaymentType": "Fixed",
	"Amount": 100.00,
	"Metadata": {
		"invoiceNumber": "INV-2026-0042",
		"customerId": "CUST-12345",
		"priority": 3,
		"isReconciled": false,
		"notes": null
	}
}

Responses

{
  "paymentRequestId": 27,
  "paycode": "RF49923973001012300035905",
  "paylink": "https://uat-paygate.be24.gr/?RequestGuid=8246a88d-c06a-436f-87f0-8dd2795b6b56&ProcessGuid=402b5dda-9cb7-4572-9dc8-d21b61c75040&LanID=2",
  "qr": null,
  "createdDate": "2026-09-02T13:29:03.3254151+03:00"
}

{
  "type": "https://www.rfc-editor.org/rfc/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "instance": "/api/payhub/v1/payment/request",
  "traceId": "0HNEBBR7M8HMA:00000004",
  "detail": null,
  "errors": [
    {
      "name": "paymentType",
      "reason": "Payment type must be one of the following: Fixed, Open, FixedOpen, SplitPay",
      "code": null,
      "severity": null
    }
  ]
}

{
  "type": "https://www.rfc-editor.org/rfc/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "instance": "/api/payhub/v1/payment/request",
  "traceId": null,
  "detail": "No registration found",
  "errors": [
    {
      "name": "Authorization",
      "reason": "No registration found with apikey or invalid registration ID format.",
      "code": null,
      "severity": null
    }
  ]
}

{
  "type": "https://www.rfc-editor.org/rfc/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "instance": "/api/payhub/v1/payment/request",
  "traceId": null,
  "detail": "No registration found for Provider 'dias'",
  "errors": [
    {
      "name": "Registration",
      "reason": "No registration found",
      "code": null,
      "severity": null
    }
  ]
}

{
  "type": "https://www.rfc-editor.org/rfc/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 500,
  "instance": "/api/payhub/v1/payment/request",
  "traceId": null,
  "detail": "Exception",
  "errors": [
    {
      "name": "Server",
      "reason": "Internal server error",
      "code": null,
      "severity": null
    }
  ]
}

Custom metadata

The optional Metadata field lets merchants attach arbitrary key/value pairs to a payment request. Payhub stores the bag verbatim and returns it on every GET /payment/request/{id}.

Validation rules

Constraint	Limit
Top-level shape	Must be a JSON object (or `null` /omitted). Numbers, strings, arrays, and booleans at the top level are rejected.
Number of pairs	Up to 20 per request
Key length	1.. 50 characters
Key characters	Letters (A–Z, a–z), digits (0–9), and underscore (`_`) only — regex `^[A-Za-z0-9_]+$`. Not allowed: hyphens (`-`), dots (`.`), spaces, colons, slashes, unicode letters, emoji, or any other punctuation.
Value length	Up to 500 characters (strings)
Value type	`string`, `number`, `boolean`, `null` (no nested objects or arrays)

Requests violating any of the rules above are rejected with 400 Bad Request and a per-key error message; the response includes traceId in extensions.

`null`, omitted, and empty object

Sent on `POST`	Stored	Returned on `GET`	Sent on webhook
field omitted	`null`	`"metadata": null`	field omitted
`"metadata": null`	`null`	`"metadata": null`	field omitted
`"metadata": {}`	`{}`	`"metadata": {}`	`"metadata": {}`
`"metadata": { … }`	verbatim JSON	verbatim JSON	verbatim JSON

Last modified: 21 September 2026