KPAY API

Card-to-card payment gateway API. Accept payments without needing traditional payment gateways.

Authentication

Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Authentication

POST/auth/register

Register

Create a new user account

Request Body

Parameter	Type	Description
`name`*	string	Full name
`mobile`*	string	Mobile number (09xxxxxxxxx)
`password`*	string	Password (min 6 chars)

Response

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "bearer"
}

POST/auth/login

Login

Authenticate and get access token

Request Body

Parameter	Type	Description
`username`*	string	Mobile number
`password`*	string	Password

Response

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "bearer"
}

GET/auth/meAuth Required

Get Current User

Get current authenticated user info

Response

{
  "id": "uuid",
  "name": "string",
  "mobile": "string",
  "merchant_id": "string",
  "created_at": "datetime"
}

Shops

GET/shopsAuth Required

List Shops

Get all shops for current user

Response

{
  "shops": "Shop[]",
  "total": "number"
}

POST/shopsAuth Required

Create Shop

Create a new shop

Request Body

Parameter	Type	Description
`name`*	string	Shop name
`website`	string	Website URL
`phone`	string	Support phone

Response

{
  "id": "uuid",
  "name": "string",
  "api_key": "string",
  "is_active": "boolean"
}

POST/shops/{id}/regenerate-keyAuth Required

Regenerate API Key

Generate a new API key for shop

Response

{
  "api_key": "string"
}

Cards

GET/cardsAuth Required

List Cards

Get all bank cards for current user

Response

{
  "cards": "Card[]",
  "total": "number"
}

POST/cardsAuth Required

Add Card

Add a new bank card

Request Body

Parameter	Type	Description
`card_number`*	string	16-digit card number
`owner_name`*	string	Card owner name
`shaba`	string	IBAN (Shaba) number

Response

{
  "id": "uuid",
  "card_number": "string",
  "owner_name": "string",
  "bank_name": "string",
  "is_active": "boolean"
}

Transactions

POST/transactions/createAuth Required

Create Transaction

Create a new payment transaction

Request Body

Parameter	Type	Description
`shop_id`*	uuid	Shop ID
`card_id`*	uuid	Card ID to receive payment
`amount`*	number	Amount in Rials
`callback_url`*	string	Redirect URL after payment
`description`	string	Payment description
`factor_number`	string	Invoice number
`fee_side`	string	Who pays fee: customer/merchant

Response

{
  "id": "uuid",
  "authority": "string",
  "amount": "number",
  "final_amount": "number",
  "fee": "number",
  "status": "pending",
  "payment_url": "string"
}

GET/transactions/payment/{authority}

Get Payment Info

Get payment details for buyer (public endpoint)

Response

{
  "authority": "string",
  "amount": "number",
  "final_amount": "number",
  "status": "string",
  "card_number": "string",
  "owner_name": "string",
  "shop_name": "string",
  "remaining_seconds": "number"
}

POST/transactions/verify

Verify Transaction

Verify payment status

Request Body

Parameter	Type	Description
`authority`*	string	Transaction authority code

Response

{
  "id": "uuid",
  "authority": "string",
  "status": "string",
  "amount": "number",
  "paid_at": "datetime"
}

GET/transactions/check/{authority}

Check Status

Quick status check (for polling)

Response

{
  "authority": "string",
  "status": "string",
  "is_paid": "boolean"
}

GET/transactionsAuth Required

List Transactions

Get all transactions for current user

Query Parameters

Parameter	Type	Description
`shop_id`	uuid	Filter by shop
`status`	string	Filter by status
`page`	number	Page number
`per_page`	number	Items per page

Response

{
  "transactions": "Transaction[]",
  "total": "number",
  "page": "number",
  "per_page": "number"
}

Crypto Gateway

GET/gateway/currencies

Supported Currencies

Get list of all supported cryptocurrencies and networks

Response

{
  "currencies": [
    {
      "code": "btc",
      "name": "Bitcoin",
      "symbol": "BTC",
      "network": "bitcoin",
      "icon": "₿",
      "decimals": 8
    }
  ]
}

POST/gateway/paymentsAuth Required

Create Crypto Payment

Create a new cryptocurrency payment request

Request Body

Parameter	Type	Description
`order_id`*	string	Your unique order reference
`currency`*	string	Currency code (btc, eth, usdt_trc20, ...)
`amount_usd`	number	Amount in USD (auto-converts to crypto)
`amount_crypto`	number	Direct crypto amount
`callback_success`	string	Success redirect URL
`callback_failed`	string	Failed redirect URL
`webhook_url`	string	Webhook notification URL
`expires_minutes`	number	Expiration time (default: 60)

Response

{
  "id": "uuid",
  "order_id": "string",
  "currency": "string",
  "requested_amount": "decimal",
  "deposit_address": "string",
  "memo": "string | null",
  "status": "created",
  "expires_at": "datetime",
  "payment_url": "string"
}

GET/gateway/payments/{id}

Get Payment Status

Check cryptocurrency payment status and confirmations

Response

{
  "id": "uuid",
  "order_id": "string",
  "currency": "string",
  "status": "pending | confirming | completed | expired | failed",
  "requested_amount": "decimal",
  "received_amount": "decimal | null",
  "confirmations": "number",
  "required_confirmations": "number",
  "tx_hash": "string | null",
  "paid_at": "datetime | null"
}

GET/gateway/balancesAuth Required

Get Merchant Balances

Get all cryptocurrency balances available for withdrawal

Response

{
  "balances": [
    {
      "currency": "string",
      "available_balance": "decimal",
      "pending_balance": "decimal",
      "total_received": "decimal",
      "total_withdrawn": "decimal"
    }
  ]
}

POST/gateway/withdrawalsAuth Required

Request Withdrawal

Request cryptocurrency withdrawal to external wallet

Request Body

Parameter	Type	Description
`currency`*	string	Currency to withdraw
`amount`*	decimal	Amount to withdraw
`destination_address`*	string	Wallet address
`memo`	string	Memo/tag (for XRP, etc.)

Response

{
  "id": "uuid",
  "currency": "string",
  "amount": "decimal",
  "fee": "decimal",
  "net_amount": "decimal",
  "destination_address": "string",
  "status": "pending"
}