PaygateDeveloper documentation

Create Payment

POST/api/v1/payments
operationId
payments.CreatePayment
Permission
payment.create
Idempotency
required

An Idempotency-Key header is required.

Parameters

FieldinTypeRequiredDescription
Idempotency-KeyheaderstringYes
PG-Versionheaderstring

Request body

application/json

FieldTypeRequiredDescription
amountMoney
checkoutboolean
client_ipstring
customerobject
customer.emailstring
customer.namestring
customer.phonestring
descriptionstring
expires_in_minutesinteger
metadataobject
methodenumValues: `promptpay`, `truemoney`, `linepay`, `shopeepay`, `bank_transfer`, `direct_debit`, `installment`
referencestring
return_urlstring

Example

A reviewed example request.

{
  "amount": {
    "minor": 125000,
    "currency": "THB"
  },
  "method": "promptpay",
  "reference": "DOCS-0001",
  "description": "One canonical payment",
  "customer": {
    "name": "Somchai Jaidee",
    "email": "cust1@example.com",
    "phone": "+66810001234"
  },
  "expires_in_minutes": 30
}

Responses

201 OK

Payment

Response headers: `X-Request-Id`

FieldTypeRequiredDescription
amountMoney
checkout_urlstring
created_atstring (date-time) (date-time)
customerobject
customer.emailstring
customer.namestring
customer.phonestring
descriptionstring
expires_atstring (date-time) (date-time)
idstring
lateboolean
metadataobject
methodenumValues: `promptpay`, `truemoney`, `linepay`, `shopeepay`, `bank_transfer`, `direct_debit`, `installment`
modestring
next_actionanyderived from current attempt action_type and action_payload
numberstring
referencestring
refunded_minorinteger
return_urlstring
statusenumValues: `created`, `requires_action`, `failed`, `processing`, `succeeded`, `expired`, `canceled`
succeeded_atstring (date-time) (date-time)
{
  "amount": {
    "currency": "string",
    "minor": 0
  },
  "checkout_url": "string",
  "created_at": "2026-10-01T09:00:00Z",
  "customer": {
    "email": "string",
    "name": "string",
    "phone": "string"
  },
  "description": "string",
  "expires_at": "2026-10-01T09:00:00Z",
  "id": "string",
  "late": false,
  "metadata": {},
  "method": "promptpay",
  "mode": "string",
  "next_action": null,
  "number": "string",
  "reference": "string",
  "refunded_minor": 0,
  "return_url": "string",
  "status": "created",
  "succeeded_at": "2026-10-01T09:00:00Z"
}

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
payments.invalid_expiry400
payments.invalid_method400
payments.invalid_outcome400
payments.separation_of_duties403
payments.not_found404
payments.duplicate_reference409
payments.merchant_not_active409
payments.refund_cancel_not_allowed409
payments.refund_not_allowed409
payments.resolve_not_allowed409
payments.amount_mismatch422
payments.attempt_not_allowed422
payments.blocked_by_risk422
payments.cancel_not_allowed422
payments.evidence_required422
payments.invalid_amount422
payments.invalid_reason422
payments.invalid_reason_code422
payments.provider_unavailable422
payments.too_many_attempts422

Try it

POST/payments

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/payments' \
  -H 'Authorization: Bearer pg_test_…' \
  -H 'PG-Version: 2026-10-01' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid v7>' \
  -d '{
  "amount": {
    "minor": 125000,
    "currency": "THB"
  },
  "method": "promptpay",
  "reference": "DOCS-0001",
  "description": "One canonical payment",
  "customer": {
    "name": "Somchai Jaidee",
    "email": "cust1@example.com",
    "phone": "+66810001234"
  },
  "expires_in_minutes": 30
}'