PaygateDeveloper documentation

Create Payment Link

POST/api/v1/payment-links
operationId
checkout.CreatePaymentLink
Permission
paymentlink.create
Idempotency
required

An Idempotency-Key header is required.

Parameters

FieldinTypeRequiredDescription
Idempotency-KeyheaderstringYes
PG-Versionheaderstring

Request body

application/json

FieldTypeRequiredDescription
amountobject
amount.currencystring
amount.fixedMoney
amount.maxMoney
amount.minMoney
amount.typeenumValues: `fixed`, `open`
collectobject
collect.emailenumValues: `required`, `optional`, `off`
collect.nameenumValues: `required`, `optional`, `off`
collect.phoneenumValues: `required`, `optional`, `off`
descriptionstring
expires_atstring (date-time) (date-time)
max_usesinteger
metadataobject
return_urlstring

Example

Generated from the schema — a shape, not a sample.

{
  "amount": {
    "currency": "string",
    "fixed": {
      "currency": "string",
      "minor": 0
    },
    "max": {
      "currency": "string",
      "minor": 0
    },
    "min": {
      "currency": "string",
      "minor": 0
    },
    "type": "fixed"
  },
  "collect": {
    "email": "required",
    "name": "required",
    "phone": "required"
  },
  "description": "string",
  "expires_at": "2026-10-01T09:00:00Z",
  "max_uses": 0,
  "metadata": {},
  "return_url": "string"
}

Responses

201 OK

PaymentLink

Response headers: `X-Request-Id`

FieldTypeRequiredDescription
amountMoney
amount_typeenumValues: `fixed`, `open`
codestring
collect_emailenumValues: `required`, `optional`, `off`
collect_nameenumValues: `required`, `optional`, `off`
collect_phoneenumValues: `required`, `optional`, `off`
created_atstring (date-time) (date-time)
currencystring
descriptionstring
expires_atstring (date-time) (date-time)
idstring
max_amountMoney
max_usesinteger
metadataobject
min_amountMoney
modestring
numberstring
return_urlstring
statusenumValues: `active`, `disabled`
usesinteger
{
  "amount": {
    "currency": "string",
    "minor": 0
  },
  "amount_type": "fixed",
  "code": "string",
  "collect_email": "required",
  "collect_name": "required",
  "collect_phone": "required",
  "created_at": "2026-10-01T09:00:00Z",
  "currency": "string",
  "description": "string",
  "expires_at": "2026-10-01T09:00:00Z",
  "id": "string",
  "max_amount": {
    "currency": "string",
    "minor": 0
  },
  "max_uses": 0,
  "metadata": {},
  "min_amount": {
    "currency": "string",
    "minor": 0
  },
  "mode": "string",
  "number": "string",
  "return_url": "string",
  "status": "active",
  "uses": 0
}

default Error

Problem

FieldTypeRequiredDescription
codestringYes
detailstring
detailsobject
errorsobject[]
errors.codestring
errors.fieldstring
errors.messagestring
instancestring
statusintegerYes
titlestringYes
typestring
{
  "code": "string",
  "detail": "string",
  "details": {},
  "errors": [
    {
      "code": "string",
      "field": "string",
      "message": "string"
    }
  ],
  "instance": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}

Errors

Derived from the modules this operation touches, because the snapshot carries no x-errors list yet — it may list codes this operation cannot return.

CodeStatus
checkout.bad_cursor400
checkout.link_not_found404
checkout.logo_not_found404
checkout.no_qr404
checkout.session_not_found404
checkout.link_unavailable409
checkout.amount_out_of_range422
checkout.invalid_branding422
checkout.invalid_payment_link422
checkout.return_url_not_allowed422

Try it

POST/payment-links

Makes a real call in test mode with your own key. The key stays in this tab and is never sent anywhere but the API.

No API base URL is configured for this environment, so try-it is unavailable.

Starts with pg_test_. A live key is refused before any request is made.

curl -X POST '<API_BASE_URL>/api/v1/payment-links' \
  -H 'Authorization: Bearer pg_test_…' \
  -H 'PG-Version: 2026-09-01' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid v7>' \
  -d '{
  "amount": {
    "currency": "string",
    "fixed": {
      "currency": "string",
      "minor": 0
    },
    "max": {
      "currency": "string",
      "minor": 0
    },
    "min": {
      "currency": "string",
      "minor": 0
    },
    "type": "fixed"
  },
  "collect": {
    "email": "required",
    "name": "required",
    "phone": "required"
  },
  "description": "string",
  "expires_at": "2026-10-01T09:00:00Z",
  "max_uses": 0,
  "metadata": {},
  "return_url": "string"
}'