Payments

Track payments from external payment providers. When a payment is confirmed via webhook, the system automatically generates a receipt.

Providers

Provider	Code
Kasikorn Bank	`KBANK`
SCB Bank	`SCB`
Bangkok Bank	`BBL`
Krungthai Bank	`KTB`

Payment Statuses

Status	Meaning
`NOT_SENT`	Payment created, not yet sent to provider
`SUBMITTING`	Being sent to provider
`PENDING`	Awaiting provider confirmation
`SUCCEEDED`	Payment confirmed by provider
`FAILED_TECHNICAL`	Technical failure
`FAILED_BUSINESS`	Business-rule failure (e.g. insufficient funds)
`EXPIRED`	Payment window expired

POST /api/v1/payments

POST /api/v1/payments

Headers

Header	Required	Description
`X-API-Key`	✓	Your API key
`X-Idempotency-Key`	✓	Unique key per request
`Content-Type`	✓	`application/json`

Request Body

Field	Type	Required	Notes
`sourceId`	string	✓	Your source code
`sourcePaymentId`	string	✓	Your unique payment ID (max 128 chars)
`amount`	number	✓	Positive number
`currency`	string	✓	3 uppercase letters (e.g. `THB`)
`provider`	enum	—	Payment provider code. Uses source default if omitted
`description`	string	—	Max 255 chars
`metadata`	object	—	Free-form key-value

Example

curl -X POST https://dev-etax.siamprop.app/api/v1/payments \
  -H "X-API-Key: sk_etax_your_key" \
  -H "X-Idempotency-Key: idem-pay-2026-001" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "TESTSRC",
    "sourcePaymentId": "PAY-ORDER-12345",
    "amount": 1070,
    "currency": "THB",
    "description": "Order #12345",
    "metadata": { "orderId": "12345" }
  }'

Response — 202 Accepted

{
  "id": "cmmje4qjf000lou0k06atfrsi",
  "sourcePaymentId": "PAY-ORDER-12345",
  "provider": "KBANK",
  "amount": 1070,
  "currency": "THB",
  "providerStatus": "NOT_SENT"
}

Error Cases

errorCode	HTTP	Cause
`DUPLICATE_PAYMENT`	409	`sourcePaymentId` already exists
`PAYMENT_PROVIDER_NOT_CONFIGURED`	422	No provider configured for source
`PAYMENT_PROVIDER_NOT_ALLOWED`	422	Specified provider is not enabled for this source
`UNSUPPORTED_PAYMENT_PROVIDER`	422	Specified provider code is not recognized

GET /api/v1/payments/:id

GET /api/v1/payments/{paymentId}?sourceId=TESTSRC

Example

curl "https://dev-etax.siamprop.app/api/v1/payments/cmmje4qjf000lou0k06atfrsi?sourceId=TESTSRC" \
  -H "X-API-Key: sk_etax_your_key"

GET /api/v1/payments

List payments.

GET /api/v1/payments?sourceId=TESTSRC&page=1&limit=20

Parameter	Required	Default	Description
`sourceId`	✓	—	Your source code
`provider`	—	all	Filter by provider
`status`	—	all	Filter by `providerStatus`
`sourcePaymentId`	—	—	Filter by your payment ID
`page`	—	`1`	—
`limit`	—	`20`	Max 100