Payment Links

Payment links are how you initiate a transaction through Kashia. Create a payment link, then redirect the buyer to pay. When payment is confirmed, an escrow is automatically created.

amount is the base amount (what the seller charges). The buyer pays fees.total_amount (base + platform + marketplace fees). See Fees for details.

Amounts are in the smallest currency unit (kobo for NGN, cents for USD).

Amount format

Display Amount	API Amount (kobo)
₦100	10000
₦1,000	100000
₦10,000	1000000
₦100,000	10000000
₦1,000,000	100000000

Endpoints

POST/api/v1/external/payment-links

Create a new payment link. Redirect the buyer to payment_url after creation.

Request example (single-vendor)

bash

curl -X POST https://api.kashiahq.com/api/v1/external/payment-links \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_user_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "iPhone 15 Pro Max",
    "description": "256GB, Blue Titanium, Brand New",
    "amount": 150000000,
    "currency": "NGN",
    "metadata": {
      "order_id": "ORD-12345",
      "product_id": "PROD-678"
    },
    "redirect_url": "https://yourstore.com/order/confirmed"
  }'

Request body (JSON)

json

{
  "buyer_user_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "iPhone 15 Pro Max",
  "description": "256GB, Blue Titanium, Brand New",
  "amount": 150000000,
  "currency": "NGN",
  "metadata": {
    "order_id": "ORD-12345",
    "product_id": "PROD-678"
  },
  "redirect_url": "https://yourstore.com/order/confirmed"
}

Request example (marketplace)

bash

curl -X POST https://api.kashiahq.com/api/v1/external/payment-links \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_user_id": "buyer-uuid",
    "seller_user_id": "seller-uuid",
    "title": "Web Design Service",
    "description": "Landing page and brand kit",
    "amount": 50000000,
    "currency": "NGN",
    "merchant_fee_percentage": 10.0,
    "merchant_fee_cap": 20000000,
    "metadata": {
      "order_id": "ORD-12345",
      "product_id": "PROD-678"
    },
    "redirect_url": "https://yourstore.com/order/confirmed"
  }'

Request body (JSON)

json

{
  "buyer_user_id": "buyer-uuid",
  "seller_user_id": "seller-uuid",
  "title": "Web Design Service",
  "description": "Landing page and brand kit",
  "amount": 50000000,
  "currency": "NGN",
  "merchant_fee_percentage": 10.0,
  "merchant_fee_cap": 20000000,
  "metadata": {
    "order_id": "ORD-12345",
    "product_id": "PROD-678"
  },
  "redirect_url": "https://yourstore.com/order/confirmed"
}

Response

json

{
  "success": true,
  "data": {
    "id": "...",
    "reference": "PL-a1b2c3d4",
    "payment_url": "https://pay.kashiahq.com/PL-a1b2c3d4",
    "title": "iPhone 15 Pro Max",
    "amount": 150000000,
    "currency": "NGN",
    "fees": {
      "platform_fee": 2250000,
      "merchant_fee": 0,
      "total_fees": 2250000,
      "total_amount": 152250000
    },
    "status": "active",
    "buyer": {
      "id": "...",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "seller": {
      "id": "...",
      "email": "seller@example.com",
      "first_name": "...",
      "last_name": "..."
    },
    "expires_at": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Parameters
Parameter	Type	Required	Description
`buyer_user_id`	string (UUID)	Yes	The buyer's customer ID
`seller_user_id`	string (UUID)	No	Seller's customer ID. Auto-filled for single-vendor merchants.
`title`	string	Yes	Short description of the product/service
`description`	string	No	Detailed description
`amount`	integer	Yes	Base amount in kobo (seller price, before fees)
`currency`	string	No (default: "NGN")	Currency code
`merchant_fee_percentage`	number	No	Marketplace only — override commission % for this link (0–20)
`merchant_fee_cap`	integer	No	Marketplace only — override commission cap in kobo for this link
`metadata`	object	No	Custom key-value data attached to the transaction
`redirect_url`	string	No	URL to redirect buyer after payment
`callback_url`	string	No	Webhook URL for this payment (overrides default)

GET/api/v1/external/payment-links/:reference

Retrieve a payment link by reference.

Response

json

{
  "success": true,
  "data": {
    "id": "...",
    "reference": "PL-a1b2c3d4",
    "payment_url": "https://pay.kashiahq.com/PL-a1b2c3d4",
    "title": "iPhone 15 Pro Max",
    "amount": 150000000,
    "currency": "NGN",
    "fees": {
      "platform_fee": 2250000,
      "merchant_fee": 0,
      "total_fees": 2250000,
      "total_amount": 152250000
    },
    "status": "active",
    "buyer": {
      "id": "...",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "seller": {
      "id": "...",
      "email": "seller@example.com",
      "first_name": "...",
      "last_name": "..."
    },
    "expires_at": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

GET/api/v1/external/payment-links

List payment links with optional filtering and pagination.

Parameters
Parameter	Type	Required	Description
`status`	string	No (default: all)	Filter: active, completed, expired, cancelled
`page`	integer	No (default: 1)	Page number
`per_page`	integer	No (default: 20)	Items per page (max 100)

Response

json

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

POST/api/v1/external/payment-links/:reference/cancel

Cancel an active (unpaid) payment link.