Developer & Business Integration

What is the KIA-PAY API?

The KIA-PAY API is a secure integration layer for businesses that want to accept KIATOKEN through their own website, customer portal, e-commerce workflow, invoicing system, POS, CRM/ERP platform, SaaS product, or mobile application.

External systems do not receive or use the merchant's KIA-PAY username and password. A trusted business server uses a merchant-owned Developer API key to communicate with KIA-PAY.

Basic integration flow

1. Create or use an approved KIA-PAY merchant account.
2. Create a Developer API key for the appropriate environment.
3. Store the API key only on your trusted server.
4. Send a server-side request to create a payment.
5. Open or redirect the customer to the returned payment URL.
6. Use a signed webhook as the primary automatic update mechanism.
7. Use the status endpoint for checks and reconciliation.
8. Treat a payment as paid only after KIA-PAY marks it Completed.

Production API endpoints

Supported payment input

Example create-payment request

POST /api/v1/payments
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: order-1001

{
  "amount": 100,
  "currency": "USD",
  "merchant_reference": "ORDER-1001",
  "customer_name": "Example Customer",
  "customer_email": "customer@example.com",
  "customer_phone": "555-123-4567",
  "customer_address": "123 Example Street",
  "customer_id_type": "drivers_license",
  "customer_id_number": "EXAMPLE1234",
  "customer_note": "Payment for Order 1001",
  "merchant_note": "Online order",
  "apply_tax": true,
  "tax_name": "Sales Tax",
  "tax_rate": "5"
}

A successful request returns payment information including a unique KIA-PAY payment ID and a hosted payment_urlthat can be opened for the customer.

Status, verification & expiration

Retrieve a payment through GET /api/v1/payments/{paymentId}. The response provides payment status and core payment details for the authenticated merchant.

Current Developer API and merchant-created payment requests use a 24-hour expiration period.

Automatic business updates

Webhooks allow KIA-PAY to notify your business system when a verified event occurs. The primary payment event is payment.completed.

Webhook delivery headers

Content-Type: application/json
User-Agent: KIA-PAY-Webhooks/1.0
KIA-Pay-Event-Id: evt_...
KIA-Pay-Timestamp: <unix seconds>
KIA-Pay-Signature: v1=<hex HMAC-SHA256>

Webhook endpoints must use a public HTTPS URL. Your handler should validate the signature, timestamp, event identity, and replay/duplicate behavior before applying a business action. Webhook processing should be idempotent.

Receipts & verification

Completed KIA-PAY payments support receipt information, receipt-hash verification, and automatic receipt email when an eligible customer email is available.

Receipt hashes are created only for completed payments. They are not created for pending, expired, cancelled, or failed payment requests.

Low-code business integration

The KIATOKEN KIA-PAY WordPress plugin provides a server-side bridge between a WordPress business website and the KIA-PAY Developer API. The API key remains in the plugin/server configuration rather than being exposed to the customer.

1. Install the KIATOKEN KIA-PAY plugin.
2. Create a KIA-PAY Developer API key.
3. Store the connection in the plugin settings.
4. Use the KIA-PAY portal, payment shortcode, or Elementor widget.
5. Publish and test payment creation.
6. Confirm the hosted page belongs to the correct merchant.
7. Complete a controlled payment and verify status and receipt behavior.

Integrate from your trusted backend

KIA-PAY can be integrated with Node.js / Next.js, PHP / Laravel, Python / Django, ASP.NET, Java, and other server-side environments capable of making HTTPS requests.

Customer Browser
      ↓
Business Portal Backend
      ↓
KIA-PAY Developer API
      ↓
payment_id + payment_url
      ↓
Business Portal Backend
      ↓
Open KIA-PAY Hosted Payment Page

After payment creation, use the webhook as the primary automatic update mechanism and the payment-status endpoint for checks, reconciliation, and recovery workflows.

Integration requirements

• Keep API keys and webhook secrets server-side.
• Use separate keys per merchant and environment where appropriate.
• Revoke and replace any exposed API key.
• Use a unique Idempotency-Key for payment creation.
• Verify webhook signatures and protect against replay and duplicate events.
• Do not authorize a payment only from merchant_reference.
• Do not log plaintext API keys, webhook secrets, or full customer ID numbers.
• For fixed-price commerce, derive or verify the amount on the trusted server.
• Use verified KIA-PAY Completed status as payment authority.