Skip to main content

Main API Documentation

Overview​

The Villa Payment Main API provides endpoints for payment processing, order management, and user operations. This API is the primary interface for the Villa Market payment system.

Base URL​

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

Authentication​

All endpoints require API key authentication via the X-API-Key header.

X-API-Key: your-api-key-here

Rate Limiting​

  • Rate Limit: 1000 requests per minute per API key
  • Burst Limit: 100 requests per second
  • Headers: Rate limit information is included in response headers

Endpoints​

Payment Processing​

Card Payment​

  • POST /cardpayment - Process credit card payments
  • Content-Type: application/x-www-form-urlencoded
  • Authentication: None (public endpoint)

QR Payment​

  • POST /qrpayment - Generate QR codes for payment
  • Content-Type: application/json
  • Authentication: API Key required

Order Management​

Calculate Cost​

  • POST /calculate-cost - Calculate order costs
  • Content-Type: application/json
  • Authentication: API Key required

Check Status​

  • GET /checkstatus/{orderId} - Check payment status
  • Authentication: API Key required

KBank Integration​

Create Order​

  • POST /kbank/createorder - Create order in KBank
  • Content-Type: application/json
  • Authentication: API Key required

Create User​

  • POST /kbank/createuser - Create user in KBank
  • Content-Type: application/json
  • Authentication: API Key required

Get User​

  • GET /kbank/user/{userId} - Get user information
  • Authentication: API Key required

Response Format​

Success Response​

{
  "statusCode": 200,
  "body": {
    // Response data
  }
}

Error Response​

{
  "statusCode": 400,
  "body": {
    "error": "Error message",
    "code": "ERROR_CODE",
    "details": {
      // Additional error details
    }
  }
}

Error Codes​

CodeHTTP StatusDescription
INVALID_INPUT400Invalid input parameters
MISSING_FIELD400Required field missing
UNAUTHORIZED401Invalid API key
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
RATE_LIMITED429Rate limit exceeded
INTERNAL_ERROR500Internal server error
SERVICE_UNAVAILABLE503External service unavailable

SDKs and Examples​

JavaScript SDK​

import { VillaPaymentAPI } from '@villa/payment-sdk';

const api = new VillaPaymentAPI({
  apiKey: 'your-api-key',
  environment: 'production'
});

// Process card payment
const payment = await api.cardPayment({
  orderId: '482500007436',
  userId: 'user-123',
  amount: 1000.00,
  token: 'payment-token'
});

Python SDK​

from villa_payment import VillaPaymentAPI

api = VillaPaymentAPI(
    api_key='your-api-key',
    environment='production'
)

# Process card payment
payment = api.card_payment(
    order_id='482500007436',
    user_id='user-123',
    amount=1000.00,
    token='payment-token'
)

cURL Examples​

Card Payment​

curl -X POST https://api.villamarket.com/cardpayment \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "orderId=482500007436&userId=user-123&amount=1000.00&token=payment-token"

QR Payment​

curl -X POST https://api.villamarket.com/qrpayment \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "orderId": "482500007436",
    "userId": "user-123",
    "amount": 1000.00,
    "customerId": "customer-123"
  }'

Webhooks​

Payment Status Updates​

  • URL: https://your-domain.com/webhooks/payment-status
  • Method: POST
  • Content-Type: application/json

Webhook Payload​

{
  "event": "payment.status.updated",
  "data": {
    "orderId": "482500007436",
    "status": "paid",
    "amount": 1000.00,
    "timestamp": "2024-01-01T12:00:00Z"
  }
}

Testing​

Sandbox Environment​

  • Base URL: https://api-sandbox.villamarket.com
  • Test API Key: test-api-key-123
  • Test Cards: Use test card numbers provided in documentation

Test Data​

{
  "testCards": {
    "visa": "4111111111111111",
    "mastercard": "5555555555554444",
    "amex": "378282246310005"
  },
  "testUsers": {
    "userId": "test-user-123",
    "customerId": "test-customer-123"
  }
}

Changelog​

Version 2.0.0​

  • Added comprehensive API documentation
  • Enhanced error handling
  • Added webhook support
  • Improved rate limiting

Version 1.5.0​

  • Added QR payment support
  • Enhanced security
  • Added SDK support
  • Improved monitoring

Version 1.0.0​

  • Initial API release
  • Card payment processing
  • Basic order management
  • KBank integration