Skip to main content

Credit Card Payments

This guide explains how to process credit card payments through the Villa Payment API using the KBank SDK. You submit an HTML form that POSTs to our /cardpayment endpoint; the KBank script renders the payment UI, tokenizes the card, and handles 3D Secure.

Prerequisites​

Before processing credit card payments:

  1. Create a KBank user using the KBank User Management API
  2. Obtain the customer_id / user_id for the payer
  3. Have a valid order in your system (or use bypass_order for testing)
  4. KBank API key and merchant ID (MID) for your environment

How It Works​

  1. Your page renders an HTML form that POSTs to https://shop.villamarket.com/api/payment3.../cardpayment
  2. You add hidden inputs for orderId, userId, customerId, grandTotal, basketId, mid, and optionally callback and bypass_order
  3. You load the KBank script (kpayment.min.js) inside the form with data-* attributes for amount, currency, MID, etc.
  4. KBank SDK renders the card input UI, tokenizes the card, and injects a token field when the user submits
  5. The form POSTs to our API; we charge the card and redirect the user to your callback URL or the default thank-you page

Endpoints​

EnvironmentURL
Devhttps://shop.villamarket.com/api/payment3devapi/cardpayment
Prodhttps://shop.villamarket.com/api/payment3/cardpayment

Method: POST
Content-Type: application/x-www-form-urlencoded (form submit)

Required Form Fields​

FieldTypeDescription
orderIdstringYour order ID
userIdstringKBank user ID / customer ID
customerIdstringSame as userId (KBank customer identifier)
grandTotalstringOrder total amount (e.g. 74.00 or 74)
basketIdstringUnique basket/session identifier
midstringKBank merchant ID

The KBank script adds token (and paymentMethods) when the user completes the payment form. Do not add these yourself.

KBank Script Attributes​

Load the script inside your form:

<script
  type="text/javascript"
  src="https://dev-kpaymentgateway.kasikornbank.com/ui/v2/kpayment.min.js"
  data-apikey="YOUR_KBANK_API_KEY"
  data-amount="74.00"
  data-currency="THB"
  data-payment-methods="card"
  data-name="Your Shop Name"
  data-mid="401394788145001"
  data-customer-id="cust_test_xxx"
></script>
AttributeDescription
data-apikeyKBank API key (dev or prod)
data-amountAmount as string, e.g. 74.00
data-currencyTHB
data-payment-methodscard
data-nameMerchant/shop display name
data-midMerchant ID
data-customer-idKBank customer ID

Prod script URL: https://kpaymentgateway.kasikornbank.com/ui/v2/kpayment.min.js

Example: React Component​

import { useEffect, useRef } from "react";

const CreditcardPaymentForm = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    containerRef.current.innerHTML = "";

    const form = document.createElement("form");
    form.method = "POST";
    form.action = "https://shop.villamarket.com/api/payment3devapi/cardpayment";

    // Required fields
    const fields: [string, string][] = [
      ["orderId", "002200049689"],
      ["userId", "cust_test_cd785f18d71349bfad9a6d516dcd26ea"],
      ["customerId", "cust_test_cd785f18d71349bfad9a6d516dcd26ea"],
      ["grandTotal", "74"],
      [
        "basketId",
        "basket_test_" + Math.random().toString(36).substring(2, 15),
      ],
    ];

    // Optional: custom redirect URL (see Callback URL section)
    // fields.push(["callback", "yourapp://payments"]);

    // Optional: skip order verification for testing (see Bypass Order section)
    // fields.push(["bypass_order", "1"]);

    fields.forEach(([name, value]) => {
      const input = document.createElement("input");
      input.type = "hidden";
      input.name = name;
      input.value = value;
      form.appendChild(input);
    });

    const script = document.createElement("script");
    script.type = "text/javascript";
    script.src =
      "https://dev-kpaymentgateway.kasikornbank.com/ui/v2/kpayment.min.js";
    script.setAttribute(
      "data-apikey",
      "pkey_test_22211JYBY6Vj43HyQhp2rK7pK3FEQpkwPz7D8"
    );
    script.setAttribute("data-amount", "74.00");
    script.setAttribute("data-currency", "THB");
    script.setAttribute("data-payment-methods", "card");
    script.setAttribute("data-name", "Your Shop Name");
    script.setAttribute("data-mid", "401394788145001");
    script.setAttribute(
      "data-customer-id",
      "cust_test_cd785f18d71349bfad9a6d516dcd26ea"
    );

    form.appendChild(script);
    containerRef.current.appendChild(form);

    return () => {
      if (containerRef.current) containerRef.current.innerHTML = "";
    };
  }, []);

  return <div ref={containerRef} />;
};

export default CreditcardPaymentForm;

Callback URL​

By default, after payment we redirect users to https://shop.villamarket.com/thankyou?orderId=...&status=...&amount=....

To redirect to your app (e.g. mobile deep link or your domain), add a hidden callback field with the base URL only:

callback valueRedirect target
yourapp://paymentsyourapp://payments/thankyou?orderId=...&status=...&amount=...
https://app.yourdomain.comhttps://app.yourdomain.com/thankyou?orderId=...&status=...&amount=...
(omitted)https://shop.villamarket.com/thankyou?orderId=...&status=...&amount=...
const callbackInput = document.createElement("input");
callbackInput.type = "hidden";
callbackInput.name = "callback";
callbackInput.value = "yourapp://payments"; // or "https://app.yourdomain.com"
form.appendChild(callbackInput);

For full details, see Card Payment Callback — App Integration Guide.

Bypass Order​

For testing without a real order in the system, add bypass_order=1:

const bypassInput = document.createElement("input");
bypassInput.type = "hidden";
bypassInput.name = "bypass_order";
bypassInput.value = "1";
form.appendChild(bypassInput);

When bypass_order=1:

  • Cardpayment — Skips OrderTable lookup; uses orderId and grandTotal from the form. No real order required.
  • Callback — Skips OrderTable lookup; redirects using values from the payment record.

Use only for testing redirect flows. See Callback URL App Integration for details.

Flow Overview​

sequenceDiagram
    participant User
    participant App as Your App
    participant API as /cardpayment API
    participant KBank as KBank

    User->>App: Enters card in KBank form
    App->>API: Form POST (orderId, grandTotal, callback, token)
    API->>KBank: Charge + 3DS
    KBank->>User: 3DS challenge (if required)
    User->>KBank: Completes 3DS
    KBank->>API: Callback (payment result)
    API->>User: Redirect to {callback}/thankyou?...

Testing​

  • Use KBank dev API key and dev script URL
  • Test card numbers: 4111111111111111 (Visa), 5555555555554444 (Mastercard)
  • Use bypass_order=1 to test without creating a real order
  • Use callback=yourapp://payments to test app deep links