Credit Card Payments

This guide explains how to process credit card payments through the Villa Payment API.

Prerequisites

Before processing credit card payments, you must:

1. Create a KBank user using the KBank User Management API
2. Obtain the user_id from the KBank user creation response

Processing a Payment

To process a credit card payment:

curl -X POST {{API_BASE_URL}}/cardpayment \
  -H "Authorization: YOUR_COGNITO_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "THB",
    "user_id": "usr_1234567890",
    "card": {
      "number": "4111111111111111",
      "expiry_month": "12",
      "expiry_year": "2025",
      "cvv": "123"
    },
    "description": "Payment for order #123",
    "metadata": {
      "order_reference": "ORDER123"
    }
  }'

Request Parameters

Parameter	Type	Description
amount	integer	Amount in smallest currency unit (e.g., satang for THB)
currency	string	Three-letter ISO currency code (e.g., "THB")
user_id	string	KBank user ID (required)
card	object	Credit card details
card.number	string	Card number
card.expiry_month	string	Two-digit expiry month (01-12)
card.expiry_year	string	Four-digit expiry year
card.cvv	string	Card security code
description	string	Payment description
metadata	object	Additional payment metadata (optional)
metadata.order_reference	string	Your internal order reference

Response

{
  "payment_id": "pay_1234567890",
  "amount": 1000,
  "currency": "THB",
  "status": "succeeded",
  "user_id": "usr_1234567890",
  "created_at": 1647123456,
  "metadata": {
    "order_reference": "ORDER123"
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 500: Internal Server Error

Example error response:

{
  "error": {
    "code": "invalid_card",
    "message": "Invalid card number."
  }
}

Best Practices

1. Always validate card details before submission
2. Implement proper error handling
3. Store transaction IDs for reconciliation
4. Follow PCI DSS guidelines for card data handling
5. Use HTTPS for all API calls

Testing

For testing credit card payments:

1. Use test card numbers:
   • 4111111111111111 (Visa)
   • 5555555555554444 (Mastercard)
2. Use any future expiry date
3. Use any 3-digit CVV
4. Test with small amounts
5. Verify error handling

Support

Need help with card payments? Please contact our support team for assistance.