Payers

A payer is the bank account of one of your end users. Every pay-in and payout refers to a payer.

• For pay-ins, the payer’s account helps match the incoming transfer, so it should be the account the user actually pays from.
• For payouts, the payer’s account is where the money is sent.

You can create payers in two ways:

• Inline, on first use (recommended). Send the bank account as payer: { bankCode, accountNumber, accountName } when you create a pay-in or payout. The payer is created the first time and reused for later requests with the same bankCode and accountNumber. The response contains its payerId.
• Up front with POST /v1/payers below, then send payerId.

Both use the same validation and checks. Store the id with the user in your system if you want to refer to the payer later.

A payer’s stored name is never changed by an inline payer, because the name is used to match incoming transfers; a different name only produces a payer_name_differs warning. Use PATCH /v1/payers/{id} to change it.

Method	Path	Purpose
GET	/v1/banks	Supported banks
POST	/v1/payers	Create a payer
GET	/v1/payers/{id}	Retrieve a payer
GET	/v1/payers	Search payers
PATCH	/v1/payers/{id}	Update a payer (omitted fields keep their value)
DELETE	/v1/payers/{id}	Delete a payer that has no payments
GET	/v1/payers/{id}/payments	All pay-ins and payouts of a payer

Supported banks

GET /v1/banks

Returns the full list in one response (no pagination). Use code as bankCode when you create payers. The list rarely changes: cache it and refresh it from time to time.

{
  "data": [
    { "object": "bank", "code": "SCB", "name": "Siam Commercial Bank", "localName": "ธนาคารไทยพาณิชย์" },
    { "object": "bank", "code": "KBANK", "name": "Kasikorn Bank", "localName": "ธนาคารกสิกรไทย" }
  ],
  "requestId": "req_..."
}

Create a payer

POST /v1/payers

Field	Required	Description
bankCode	yes	Bank code from GET /v1/banks
accountNumber	yes	Account number, digits only, no dashes (max 32 digits)
accountName	yes	Account holder name as shown by the bank (max 200 characters)
accountNameEn	no	Account holder name in English
status	no	active (default) or inactive. Inactive payers cannot be used for new payments
referralCode	no	Referral code, if any (max 64 characters)

{
  "bankCode": "SCB",
  "accountNumber": "1234567890",
  "accountName": "สมชาย สบายดี",
  "accountNameEn": "Somchai Sabuydee"
}

Response (201):

{
  "data": {
    "object": "payer",
    "id": "payer_7c0a4b8e2f3d4a1b9c8d7e6f5a4b3c2d",
    "bankCode": "SCB",
    "bankName": "Siam Commercial Bank",
    "accountNumber": "1234567890",
    "accountName": "สมชาย สบายดี",
    "accountNameEn": "Somchai Sabuydee",
    "status": "active",
    "referralCode": null,
    "createdAt": "2026-01-01T00:00:00.000Z"
  },
  "requestId": "req_..."
}

Update a payer

PATCH /v1/payers/{id}

Send only the fields you want to change (same fields as create). Omitted fields keep their value. For example, to deactivate a payer:

{ "status": "inactive" }

Search payers

GET /v1/payers?accountNumber=4567&bankCode=SCB

Parameter	Description
accountNumber	Account number contains this text
accountName	Account name contains this text, case-insensitive
bankCode	Bank code
limit, cursor	Pagination

Delete a payer

DELETE /v1/payers/{id}

Only payers without any pay-in or payout can be deleted; otherwise you get 409 payer_has_payments. Set status to inactive instead.

{ "data": { "id": "payer_7c0a4b8e2f3d4a1b9c8d7e6f5a4b3c2d", "deleted": true }, "requestId": "req_..." }

A payer’s payments

GET /v1/payers/{id}/payments?status=succeeded

Returns pay-ins and payouts mixed, newest first. Check the object field ("payin" or "payout") of each item. Accepts status, reference, createdFrom, createdTo, limit and cursor.

Common errors

HTTP	code	Meaning
400	parameter_missing, parameter_invalid	A field is missing or malformed, e.g. an account number with non-digits; see error.param
404	resource_not_found	Unknown payer, or not yours
409	payer_has_payments	The payer has payments and cannot be deleted
422	bank_not_found	bankCode is not in the bank list
422	referral_code_not_found, referrer_inactive	Unknown referral code, or the referrer is inactive
422	payer_blocked	This account is blocked