Callback API Documentation

Overview

The Villa Payment Callback API handles payment callbacks from external payment providers. This API is used by payment gateways to notify the system about payment status updates.

Base URL

• Development: https://callback-dev.villamarket.com
• Production: https://callback.villamarket.com

Authentication

Callback endpoints do not require authentication as they are called by external payment providers. Security is maintained through:

• IP Whitelisting: Only approved payment provider IPs
• Signature Verification: HMAC signatures for request validation
• Timestamp Validation: Request timestamp validation

Endpoints

Card Payment Callbacks

Credit Card Callback

• POST /callback - Handle credit card payment callbacks
• Content-Type: application/x-www-form-urlencoded
• Authentication: None (IP whitelisted)

American Express Callback

• POST /amexcallback - Handle Amex payment callbacks
• Content-Type: application/json
• Authentication: None (IP whitelisted)

Bank App Callback

• POST /bankappcallback - Handle bank app payment callbacks
• Content-Type: application/json
• Authentication: None (IP whitelisted)

QR Payment Callbacks

QR Payment Callback

• POST /qrcallback - Handle QR payment callbacks
• Content-Type: application/json
• Authentication: None (IP whitelisted)

Wallet Payment Callbacks

Wallet Payment Callback

• POST /walletcallback - Handle wallet payment callbacks
• Content-Type: application/json
• Authentication: None (IP whitelisted)

Callback Payloads

Credit Card Callback

POST /callback
Content-Type: application/x-www-form-urlencoded

objectId=chrg_xxx&token=tokn_xxx&status=true&message=&saveCard=false

Note: The callback is invoked by KBank with a fixed payload. To customise the redirect URL, pass the callback parameter when calling POST /cardpayment — we store it in the payment record and read it when the callback runs. See Callback URL App Integration.

QR Payment Callback

{
  "paymentId": "qr_pay_123456789",
  "status": "success",
  "amount": 1000.0,
  "orderId": "482500007436",
  "timestamp": "2024-01-01T12:00:00Z",
  "signature": "abc123"
}

Wallet Payment Callback

{
  "walletId": "wallet_123456789",
  "status": "success",
  "amount": 1000.0,
  "orderId": "482500007436",
  "timestamp": "2024-01-01T12:00:00Z",
  "signature": "abc123"
}

Response Format

Success Response

{
  "statusCode": 200,
  "body": {
    "message": "Callback processed successfully",
    "orderId": "482500007436",
    "status": "processed"
  }
}

Error Response

{
  "statusCode": 400,
  "body": {
    "error": "Invalid callback data",
    "message": "Missing required field: orderId"
  }
}

Security

Signature Verification

All callbacks must include a valid HMAC signature:

const crypto = require("crypto");

function generateSignature(payload, secret) {
  return crypto.createHmac("sha256", secret).update(payload).digest("hex");
}

// Verify signature
function verifySignature(payload, signature, secret) {
  const expectedSignature = generateSignature(payload, secret);
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex")
  );
}

IP Whitelisting

Only requests from approved IP addresses are accepted:

• KBank: 203.154.xxx.xxx/24
• Visa: 54.xxx.xxx.xxx/16
• Mastercard: 52.xxx.xxx.xxx/16

Error Handling

Common Errors

Error	Description	Resolution
INVALID_SIGNATURE	Invalid HMAC signature	Check signature generation
INVALID_IP	Request from unauthorized IP	Add IP to whitelist
MISSING_FIELD	Required field missing	Include all required fields
INVALID_TIMESTAMP	Timestamp too old	Ensure timestamp is recent
ORDER_NOT_FOUND	Order ID not found	Verify order exists

Retry Logic

• Max Retries: 3 attempts
• Retry Delay: Exponential backoff (1s, 2s, 4s)
• Dead Letter Queue: Failed callbacks are sent to DLQ

Testing

Test Callbacks

Use the following test data for development:

{
  "testCallbacks": {
    "success": {
      "status": "success",
      "orderId": "test_order_123",
      "amount": "100.00",
      "transactionId": "test_txn_123"
    },
    "failure": {
      "status": "failed",
      "orderId": "test_order_123",
      "amount": "100.00",
      "error": "Insufficient funds"
    }
  }
}

Local Testing

# Test credit card callback
curl -X POST http://localhost:3000/callback \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "status=success&orderId=test_order_123&amount=100.00&transactionId=test_txn_123"

# Test QR callback
curl -X POST http://localhost:3000/qrcallback \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "test_qr_123",
    "status": "success",
    "amount": 100.00,
    "orderId": "test_order_123"
  }'

Monitoring

Metrics

• Callback Volume: Number of callbacks received
• Success Rate: Percentage of successful callbacks
• Processing Time: Average callback processing time
• Error Rate: Percentage of failed callbacks

Alerts

• High Error Rate: > 5% callback failures
• Processing Delays: > 30 seconds processing time
• Missing Callbacks: Expected callbacks not received

Integration Guide

For Payment Providers

1. Register IP Address: Contact Villa team to whitelist your IP
2. Get Secret Key: Receive HMAC secret key for signature generation
3. Implement Callbacks: Send callbacks to appropriate endpoints
4. Handle Responses: Process success/error responses appropriately

Callback Requirements

1. Timing: Send callbacks within 30 seconds of payment completion
2. Retry: Implement retry logic for failed callbacks
3. Idempotency: Handle duplicate callbacks gracefully
4. Security: Always include valid signatures

Changelog

Version 2.0.0

• Added comprehensive callback documentation
• Enhanced security measures
• Added signature verification
• Improved error handling

Version 1.5.0

• Added QR payment callbacks
• Enhanced monitoring
• Added retry logic
• Improved testing support

Version 1.0.0

• Initial callback API
• Credit card callbacks
• Basic error handling
• IP whitelisting