Customer RAG

กลุ่มเป้าหมาย

• สำหรับ: ทีมบริการลูกค้าและฝ่ายปฏิบัติการ
• วัตถุประสงค์: ค้นหาปัญหาจาก code และ responseCode ที่ merchant รายงานได้อย่างรวดเร็ว และให้แนวทางการจัดการ
• เอกสารสำหรับนักพัฒนา: สำหรับความหมายมาตรฐานของ code และแนวปฏิบัติการ integrate โปรดดู รหัสการตอบกลับข้อผิดพลาด

ตัวยึดตำแหน่ง

รหัสข้อผิดพลาดด้านล่างสะท้อนสิ่งที่ระบบภายนอกได้รับจริง {1} เป็นตัวยึดตำแหน่งแบบไดนามิกที่จะถูกแทนที่ด้วยเนื้อหาเฉพาะเมื่อ runtime

รหัสที่ไม่ได้ครอบคลุม

เอกสารนี้ไม่ได้ขยายรายละเอียด code = "01" (กำลังดำเนินการ) และ code = "15" (หมดเวลา) โปรดดู รหัสการตอบกลับข้อผิดพลาด และใช้ API สอบถามสถานะเพื่อตรวจสอบความคืบหน้าของออเดอร์

สำหรับข้อผิดพลาดด้านการยืนยันตัวตน โปรดดู คู่มือลายเซ็น

---

การถอดรหัส responseCode

responseCode is a 7-character string composed of three parts:

responseCode = HTTP status (3 digits) + service code (2 digits) + caseCode (2 digits)

Service Code Reference

Service Code	API Path	Description
90	v2.0/transaction/pay-in	Pay-in
91	v2.0/disbursement/pay-out	Pay-out
92	v2.0/inquiry-status	Status inquiry

code to HTTP Status Mapping

code	HTTP Status Prefix	Category
00	200	Success
10	400	Invalid request parameters
11	404	Resource not found
12	401	Authentication failure
13	429	Rate limit exceeded
14	403	Transaction forbidden
16	400	Insufficient balance
20	502	External channel error
99	500	Internal system error

---

ดัชนีด่วน

ดัชนีหลักจัดกลุ่มตาม code รายละเอียดระดับ message อยู่ใน รายละเอียดรหัสข้อผิดพลาด

code	responseCode Pattern	Category	First Action	Escalation	Details
00	20090xx / 20091xx / 20092xx	Success	No action needed	Self-service	#code-00
10	40090xx / 40091xx / 40092xx	Bad request	Check message for field	Self-service	#code-10
11	40490xx / 40491xx / 40492xx	Not found	Verify path or merchant ID	Self-service	#code-11
12	40190xx / 40191xx / 40192xx	Unauthorized	Check signature / Token	Self-service → Tech support	#code-12
13	42990xx / 42991xx / 42992xx	Too many requests	Reduce frequency or check status	Self-service	#code-13
14	40390xx / 40391xx / 40392xx	Forbidden	Must read message	Varies by scenario	#code-14
16	40090xx / 40091xx / 40092xx	Insufficient balance	Ask merchant to top up	Self-service	#code-16
20	50290xx / 50291xx / 50292xx	External channel error	Retry later	Self-service → Tech support	#code-20
99	50090xx / 50091xx / 50092xx	System error	Log full payload	Escalate to tech support	#code-99

---

รายละเอียดรหัสข้อผิดพลาด

code = "00" — Success

responseCode	message	Service	Handling
2009000	Successful	Pay-in	Request accepted; no action needed
2009100	Successful	Pay-out	Request accepted; no action needed
2009200	Successful	Status inquiry	Request accepted; order status returned

---

code = "10" — Invalid Request Parameters

The most common merchant errors. Support can usually resolve these directly.

Invalid field format / invalid parameters (caseCode = 01)

Pay-in (serviceCode = 90)

responseCode	message	Trigger Scenario	Handling
4009001	Invalid Field Format [{1}]	Gateway validation: invalid timestamp, special chars in orderNo, merchant ID mismatch	Check timestamp (within 24h); orderNo must use letters, digits, underscore, hyphen only; header and body merchant ID must match
4009001	Invalid request parameter: [{1}]	Trade validation: request body fails Bean Validation	Fix the field named in {1}
4009001	Unsupported area [{1}]	Requested region is not supported	Confirm whether pay-in is available in that region
4009001	Unsupported currency [{1}]	Requested currency is not supported	Check supported currencies for the region
4009001	Currency does not match area	Currency does not match the region	Use a currency supported by the region
4009001	Duplicate pay order	Duplicate pay-in orderNo	Query order status first; do not resubmit if already successful
4009001	Invalid settlement amount	Invalid pay-in settlement amount	Verify amount is positive with correct decimal places

Pay-out (serviceCode = 91)

responseCode	message	Trigger Scenario	Handling
4009101	Invalid Field Format [{1}]	Gateway validation: invalid timestamp, special chars in orderNo	Check timestamp; orderNo must use letters, digits, underscore, hyphen only
4009101	Invalid request parameter: [{1}]	Trade validation: request body fails rules	Fix the field named in {1}
4009101	Unsupported area [{1}]	Requested region is not supported	Confirm whether pay-out is available in that region
4009101	Unsupported currency [{1}]	Requested currency is not supported	Check supported currencies for the region
4009101	Currency does not match area	Currency does not match the region	Use a currency supported by the region
4009101	Duplicate payout order	Duplicate pay-out orderNo	Query order status first
4009101	Invalid payout amount	Invalid pay-out amount	Verify amount is positive and within limits

Status inquiry (serviceCode = 92)

responseCode	message	Trigger Scenario	Handling
4009201	Invalid Field Format [{1}]	Gateway validation: invalid request format	Check request parameter format
4009201	Invalid request parameter: [{1}]	Trade validation: request body fails rules	Fix the field named in {1}

Missing mandatory fields (caseCode = 02)

responseCode	message	Service	Handling
4009002	Invalid Mandatory Field [{1}]	Pay-in	Add the missing field named in {1}
4009102	Invalid Mandatory Field [{1}]	Pay-out	Same as above
4009202	Invalid Mandatory Field [{1}]	Inquiry	Same as above

Commonly missing fields: Content-Type, X-TIMESTAMP, X-SIGNATURE, X-PARTNER-ID, Authorization

---

code = "11" — Resource Not Found

Invalid routing (caseCode = 01)

responseCode	message	Service	Trigger Scenario	Handling
4049001	Invalid Routing	Pay-in	URL path does not match any service	Confirm path is v2.0/transaction/pay-in
4049101	Invalid Routing	Pay-out	URL path does not match any service	Confirm path is v2.0/disbursement/pay-out
4049201	Invalid Routing	Inquiry	URL path does not match any service	Confirm path is v2.0/inquiry-status

Merchant not found (caseCode = 02)

responseCode	message	Service	Trigger Scenario	Handling
4049002	Partner ：{merchantId} Not Found	Pay-in	Merchant does not exist or is disabled	① Verify merchant ID; ② Check merchant status in admin
4049102	Partner ：{merchantId} Not Found	Pay-out	Merchant does not exist or is disabled	Same as above
4049202	Partner ：{merchantId} Not Found	Inquiry	Merchant does not exist or is disabled	Same as above

---

code = "12" — Authentication Failure

Security-related errors. Escalate to technical support if support cannot resolve.

Unauthorized (caseCode = 00)

responseCode	message	Service	Trigger Scenario	Handling
4019000	Unauthorized. [{1}]	Pay-in	RSA signature failure, missing public key, IP not whitelisted	① Verify RSA public key; ② Confirm SHA256withRSA; ③ Verify signature string order
4019100	Unauthorized. [{1}]	Pay-out	Same as above	Same as above
4019200	Unauthorized. [{1}]	Inquiry	Same as above	Same as above

Invalid token (caseCode = 01)

responseCode	message	Service	Trigger Scenario	Handling
4019001	Invalid Token [{1}]	Pay-in	JWT token invalid or expired	① Verify Access Token; ② Refresh token; ③ Ensure token is in Authorization header
4019101	Invalid Token [{1}]	Pay-out	Same as above	Same as above
4019201	Invalid Token [{1}]	Inquiry	Same as above	Same as above

---

code = "13" — Too Many Requests

responseCode	message	Service	Trigger Scenario	Handling
4299000	TOO_MANY_REQUESTS	Pay-in	Rate limit exceeded, or same order is processing	Reduce frequency and retry; if order is processing, query status first
4299100	TOO_MANY_REQUESTS	Pay-out	Same as above	Same as above
4299200	TOO_MANY_REQUESTS	Inquiry	Rate limit exceeded	Reduce frequency and retry

---

code = "14" — Transaction Forbidden

The most complex category. Always read the message content.

Transaction expired (caseCode = 00)

responseCode	message	Service	Trigger Scenario	Handling
4039000	Transaction Expired	Pay-in	Pay-in order exceeded valid payment window	Inform merchant the order expired; create a new order

Pay-out and status inquiry do not involve transaction expiry.

Blacklist block (caseCode = 01)

responseCode	message	Service	Trigger Scenario	Handling
4039001	Do Not Honor, [{1}]	Pay-in	IP, email, account, or ID blacklist	Escalate to security team
4039101	Do Not Honor, [{1}]	Pay-out	Same as above	Escalate to security team
4039201	Do Not Honor, [{1}]	Inquiry	Same as above	Escalate to security team

Transaction not permitted (caseCode = 02)

Pay-in (serviceCode = 90)

responseCode	message	Trigger Scenario	Handling
4039002	Transaction Not Permitted.[{1}]	Risk decline (105), invalid merchant status (109), failed order (131), operation not allowed (132)	Interpret {1} for root cause
4039002	Transaction declined by risk control	Risk rules triggered	Escalate to risk team
4039002	Merchant status is invalid	Merchant disabled or abnormal	Check merchant status in admin
4039002	Pay order has failed	Operation on a failed order	Inform merchant the order has failed
4039002	Pay order operation not allowed in current status	Operation not allowed in current state	Guide merchant to check order status

Pay-out (serviceCode = 91)

responseCode	message	Trigger Scenario	Handling
4039102	Transaction Not Permitted.[{1}]	Risk decline (105), invalid merchant status (109)	Interpret {1} for root cause
4039102	Transaction declined by risk control	Risk rules triggered	Escalate to risk team
4039102	Merchant status is invalid	Merchant disabled or abnormal	Check merchant status in admin
4039102	Payout order operation not allowed in current status	Operation not allowed in current state	Guide merchant to check order status

Status inquiry (serviceCode = 92)

responseCode	message	Trigger Scenario	Handling
4039202	Transaction Not Permitted.[{1}]	Same as above	Interpret {1} for root cause

Merchant blacklist / IP whitelist (caseCode = 03)

responseCode	message	Service	Trigger Scenario	Handling
4039003	Merchant Blacklisted. {1}	Pay-in	Merchant server IP not in whitelist	① Confirm IP change; ② Collect new IP and escalate to tech support
4039103	Merchant Blacklisted. {1}	Pay-out	Same as above	Same as above
4039203	Merchant Blacklisted. {1}	Inquiry	Same as above	Same as above

Insufficient configuration (caseCode = 04)

Pay-in (serviceCode = 90)

responseCode	message	Trigger Scenario	Handling
4039004	Insufficient configuration permission. [{1}]	Pay product unavailable (121), no active pay channel (122)	Guide merchant to admin → Channel Config; enable at least one channel
4039004	Pay product config unavailable	Pay product not configured	Guide merchant to configure pay product
4039004	No active pay channel	All pay channels unavailable	Check channel status; inform merchant if under maintenance

Pay-out (serviceCode = 91)

responseCode	message	Trigger Scenario	Handling
4039104	Insufficient configuration permission. [{1}]	Pay-out config unavailable (141), no active pay-out channel (142)	Guide merchant to check pay-out channel config in admin
4039104	Payout config unavailable	Pay-out product not configured	Guide merchant to configure pay-out product
4039104	No active payout channel	All pay-out channels unavailable	Check pay-out channel status

Status inquiry (serviceCode = 92)

responseCode	message	Trigger Scenario	Handling
4039204	Insufficient configuration permission. [{1}]	Incomplete merchant configuration	Guide merchant to complete configuration

---

code = "16" — Insufficient Balance

responseCode	message	Service	Trigger Scenario	Handling
4009003	Insufficient Balance. [{1}]	Pay-in	Merchant available balance insufficient	Inform merchant to top up
4009103	Insufficient Balance. [{1}]	Pay-out	Insufficient balance to freeze pay-out amount	Inform merchant to top up before pay-out
4009203	Insufficient Balance. [{1}]	Inquiry	Merchant available balance insufficient	Inform merchant to top up

---

code = "20" — External Channel Error

Pay-in (serviceCode = 90)

responseCode	message	Trigger Scenario	Handling
5029000	External request error: {1}	Gateway downstream call failed	Temporary channel issue; retry later. Escalate if frequent
5029000	Callback notify failed, [{1}]	Merchant callback URL unreachable	Verify merchant callback URL is reachable
5029000	Pay channel timeout or interrupted	Channel call timed out	Temporary issue; retry later
5029000	Unknown pay status	Unrecognized channel status	Escalate to tech support

Pay-out (serviceCode = 91)

responseCode	message	Trigger Scenario	Handling
5029100	External request error: {1}	Gateway downstream call failed	Temporary channel issue; retry later
5029100	Callback notify failed, [{1}]	Merchant callback URL unreachable	Verify merchant callback URL is reachable
5029100	Payout channel timeout or interrupted	Pay-out channel timed out	Temporary issue; retry later
5029100	Unknown payout status	Unrecognized pay-out channel status	Escalate to tech support

Status inquiry (serviceCode = 92)

responseCode	message	Trigger Scenario	Handling
5029200	External request error: {1}	Gateway downstream call failed	Temporary channel issue; retry later

---

code = "99" — General System Error

Internal system errors. Log the full payload and escalate to technical support.

Pay-in (serviceCode = 90)

responseCode	message Example	Root Cause	Handling
5009000	Payment method: XXX inactive for merchant: XXX	Payment method not activated	Guide merchant to activate payment method in admin
5009000	Failed to generate order number	Order number generation failure	Temporary system issue; retry later
5009000	Unable to create pay order	Failed to create pay-in order	Log orderNo/tradeNo and escalate
5009000	Pay channel error: {1}	Channel rejection	Escalate to tech support
5009000	Pay order not found	Pay-in order not found	Verify orderNo/tradeNo
5009000	The requested pay order was not found	Platform order not found	Verify order number
5009000	System error: {1}	Generic system error	Log full payload; escalate immediately

Pay-out (serviceCode = 91)

responseCode	message Example	Root Cause	Handling
5009100	Payment method: XXX inactive for merchant: XXX	Payment method not activated	Guide merchant to activate payment method in admin
5009100	Failed to generate order number	Order number generation failure	Temporary system issue; retry later
5009100	Unable to create payout order	Failed to create pay-out order	Log orderNo/tradeNo and escalate
5009100	Payout channel error: {1}	Channel rejection	Escalate to tech support
5009100	Payout order not found	Pay-out order not found	Verify order number
5009100	The requested payout order was not found	Platform pay-out order not found	Verify order number
5009100	The requested withdrawal order was not found	Withdrawal order not found	Verify withdrawal order number
5009100	System error: {1}	Generic system error	Log full payload; escalate immediately

Status inquiry (serviceCode = 92)

responseCode	message Example	Root Cause	Handling
5009200	Order not found	Order not found	Verify orderNo/tradeNo
5009200	System error: {1}	Generic system error	Log full payload; escalate immediately

---

สคริปต์ตอบกลับด่วน

Parameter errors (code = 10 / 11)

Scenario	Applicable code	Script
Invalid parameter format	10	"Your request has a parameter format issue: {reason}. Please check and retry."
Missing mandatory field	10	"Your request is missing required field {fieldName}. Please add it and retry."
Duplicate order	10	"Order {orderNo} was already processed. Please query its status before resubmitting."
Merchant not found	11	"Merchant ID {merchantId} does not exist or is disabled. Please verify and retry."
Invalid routing	11	"The request path is invalid. Pay-in: v2.0/transaction/pay-in; Pay-out: v2.0/disbursement/pay-out"

Authentication (code = 12 / 13)

Scenario	Applicable code	Script
Signature failure	12	"Signature verification failed. Please check: ① RSA public key; ② SHA256withRSA algorithm; ③ signature string order per documentation."
Invalid token	12	"Access Token is expired or invalid. Please obtain a new token and retry."
Rate limit	13	"Request frequency is too high. Please retry later and reduce call frequency."
Order processing	13	"This order is being processed. Please query order status before resubmitting."

Risk and limits (code = 14 / 16)

Scenario	Applicable code	Script
Transaction expired	14	"The order has expired. Please create a new order."
Blacklist block	14	"Your request was blocked by security policy. We need to verify further. Please provide merchant ID and request time." → Security team
Risk decline	14	"The transaction was declined by risk control. We need further review." → Risk team
IP whitelist	14	"Your server IP is not whitelisted. Please confirm your IP or contact technical support to add it."
Incomplete config	14	"Your merchant account does not have complete pay-in/pay-out channel configuration. Please enable at least one channel in admin."
Insufficient balance	16	"Your merchant account balance is insufficient. Please top up before pay-out."

System errors (code = 20 / 99)

Scenario	Applicable code	Script
Channel error	20	"The third-party payment channel is temporarily unavailable. Please retry later. We will investigate if it persists." → Tech support
System error	99	"A system error occurred. We have logged the details and escalated to our technical team. Please retry later." → Log full payload, escalate