Payout Callback API

Overview

Payout Callback API is used to receive order status change notifications. When an order status changes, Veloraya sends an asynchronous notification to the merchant so the merchant can update order status in time.

How to test callbacks in the testing environment?

Provide the order number and contact operations for manual operation.

Callback Mechanism

Trigger conditions

• Payment success
• Payment failure

Retry mechanism

Item	Description
Max retries	11 times (including the first push)
Interval	30 seconds (first 6 retries)
Interval	3 minutes (last 5 retries)
Timeout	30 seconds
Retry condition	HTTP status != 200, business code != 10000, or network error
Success criteria	HTTP 200 with business response {"code": 10000, "message": "Success"}

Callback Request

Method

• Method: POST
• Content-Type: application/json
• Encoding: UTF-8

Headers

Header	Type	Required	Description
Content-Type	string	Y	application/json
Timestamp	string	Y	Timestamp (milliseconds)
Nonce	string	Y	Random string (UUID without dashes)
Signature	string	Y	Signature generated with Veloraya private key, used to verify callback authenticity

Callback Parameters (body)

Parameter	Type	Required	Description
merchantId	string	Y	Merchant ID
orderId	string	Y	Platform order ID
merchantOrderId	string	Y	Merchant order ID
orderStatus	string	Y	Order status, see order status enum
amount	BigDecimal	Y	Order amount
currency	string	Y	Currency code
fee	BigDecimal	Y	Fee
errorCode	string	N	Error code (on failure)
errorMsg	string	N	Error message (on failure)
createDatetime	string	Y	Order create time, format: yyyy-MM-dd HH:mm:ss
completionDatetime	string	N	Order completion time, format: yyyy-MM-dd HH:mm:ss

Order status enum

Value	Description
SUCCESS	Success
FAILED	Failed

Callback Example

Success callback

{
  "amount": 500.00,
  "completionDatetime": "2025-11-19 18:04:55",
  "createDatetime": "2025-11-19 17:59:54",
  "currency": "THB",
  "fee": 55.00,
  "merchantId": "601091",
  "merchantOrderId": "ORDER5187977827671717",
  "orderId": "PAYIN1991084006458683392",
  "orderStatus": "SUCCESS"
}

Callback Response

Success response

The merchant must return HTTP 200 with business code 10000 to acknowledge:

{
  "code": 10000,
  "message": "Success"
}

Failure response

If processing fails, return an error message (the system will keep retrying):

{
  "code": 40001,
  "message": "Processing failed"
}

Note

Only returning {"code": 10000, "message": "Success"} stops the retry. Any other response (including non-200 HTTP status) triggers the retry mechanism.

Signature Verification

Verification steps

1. Extract signature: get the Signature header
2. Build verification content: timestamp={timestamp},nonce={nonce},body={bodyJson}
   • Note: the verification content does NOT include merchantId, only timestamp, nonce and body
3. Verify with Veloraya public key: verify the signature with the public key provided by Veloraya
4. Use the unified guide: reuse the "Callback Verification Guide" and Appendix B sample code in API Signature

Key notes

• Veloraya public key: provided by Veloraya, used to verify callback signatures
• Algorithm: SHA256withRSA
• Encoding: UTF-8 + Base64

Business Processing

Order status handling

• SUCCESS: update order to paid, record arrival time
• FAILED: update order to failed, release frozen funds

Error Handling

Common errors

• Network timeout: callback request timed out
• Server error: merchant server returned 5xx
• Business error: merchant business logic failed
• Signature error: signature verification failed

Suggestions

• Logging: log all callback requests and responses
• Exception handling: handle exceptions properly
• Monitoring: set up monitoring and alerting
• Manual intervention: provide a manual intervention mechanism for unhandled cases

Notes

• Callback URL configuration: the callback URL must be provided to the Veloraya team before go-live and must be accessible and stable
• Signature verification: always verify callback signature legitimacy; use the unified callback verification logic per API Signature
• Idempotency: implement idempotency to avoid duplicate processing; dedupe by orderId or merchantOrderId
• Response format: must return {"code": 10000, "message": "Success"} to stop retries
• Logging: log all callback requests, responses and processing time