Support & Documentation

Build with the K-Payments API

Reference for our public REST API, webhooks, and SDKs. Need a human? Our support team responds within one business day.

API versionv1— current

Getting started

Once your merchant application is approved, your dashboard surfaces a publishable key (pk_test_…) and a secret key (sk_test_…). Use the publishable key in browser code, and keep the secret key on your server.

The base URL for every request is https://api.k-payments.com. All endpoints accept and return JSON.

Authentication

Authenticate every request with a Bearer token in the Authorization header. Missing or invalid keys return 401 authentication_error. Rotate keys any time from the dashboard — old keys remain valid for 24 hours after rotation.

header

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx

Idempotency

Mutating endpoints (POST /v1/charges, POST /v1/refunds) accept an Idempotency-Key header. Replays with the same key return the original response without creating a duplicate. Use a UUID v4 per business operation; keys are scoped to your merchant and remembered for 24 hours.

Webhooks

Register an HTTPS endpoint via /v1/webhook_endpoints and subscribe to one or more event types. Every delivery is signed with HMAC-SHA256 using the endpoint's signing_secret:

header

K-Payments-Signature: t=1749651729,v1=5257a869e7ec...

# signed_payload = "${timestamp}." + raw_body
# v1 = hex( HMAC_SHA256( signing_secret, signed_payload ) )

Reject signatures older than 5 minutes to defeat replay attacks. Failed deliveries are retried with exponential backoff (1m, 5m, 30m, 2h, 6h, 12h, 24h) for up to 72 hours, then abandoned.

Supported event types

charge.succeededcharge.failedcharge.refundedrefund.createdrefund.updatedpayout.createdpayout.paidpayout.faileddispute.createddispute.updateddispute.closed

Errors

The API uses standard HTTP status codes. Error responses share a single envelope:

json

{
  "error": {
    "type": "invalid_request_error",
    "message": "Validation failed.",
    "details": { "fieldErrors": { "amount": ["min 50"] } }
  }
}

400 — invalid_request_error
401 — authentication_error
402 — card_error (declined)
404 — not_found
429 — rate_limit_error
5xx — internal_error (safe to retry)

Charges

POST

/v1/charges

Run a one-time charge against a card. Supports idempotent retries via the Idempotency-Key header.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.
Idempotency-Key	string	no	Unique key (UUID recommended). Replays return the original response.
Content-Type	string	yes	application/json

Body parameters

Name	Type	Required	Description
amount	integer	yes	Amount in cents. Min 50, max 10,000,000.
currency	string	no	"USD" (default and only value today).
source	object	yes	Card details: { number, exp_month, exp_year, cvc }.
billing_address	object	yes	US billing address: { line1, line2?, city, state, postal_code, country: "US" }.
description	string	no	Up to 500 chars, surfaced in the dashboard.
metadata	object	no	Arbitrary key/value pairs (strings, numbers, booleans).

Example request

curl

curl https://api.k-payments.com/v1/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f4c2e1a-..." \
  -d '{
    "amount": 4999,
    "currency": "USD",
    "source": {
      "number": "4242424242424242",
      "exp_month": 12,
      "exp_year": 2030,
      "cvc": "123"
    },
    "billing_address": {
      "line1": "1 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "description": "Order #1024",
    "metadata": { "order_id": "1024" }
  }'

GET

/v1/charges/:id

Fetch a single charge and any refunds applied to it.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Path parameters

Name	Type	Required	Description
id	string	yes	Charge id.

Example request

curl

curl https://api.k-payments.com/v1/charges/c8b3e1a4-... \
  -H "Authorization: Bearer sk_test_..."

Refunds

POST

/v1/refunds

Refund a succeeded charge, fully or partially. Refunding more than the remaining balance returns a 400.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.
Content-Type	string	yes	application/json

Body parameters

Name	Type	Required	Description
charge	string	yes	Charge id (uuid) to refund.
amount	integer	no	Amount in cents. Defaults to remaining refundable balance.
reason	string	no	One of "requested_by_customer", "duplicate", "fraudulent", "other".
notes	string	no	Up to 1000 chars, internal only.

Example request

curl

curl https://api.k-payments.com/v1/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "charge": "c8b3e1a4-...", "amount": 1000, "reason": "requested_by_customer" }'

GET

/v1/refunds

List refunds for your merchant, newest first. Optionally filter by charge.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Query parameters

Name	Type	Required	Description
limit	integer	no	1-100, default 20.
charge	string	no	Only return refunds for this charge id.

Example request

curl

curl "https://api.k-payments.com/v1/refunds?limit=20" \
  -H "Authorization: Bearer sk_test_..."

GET

/v1/refunds/:id

Fetch a single refund by id.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Path parameters

Name	Type	Required	Description
id	string	yes	Refund id.

Example request

curl

curl https://api.k-payments.com/v1/refunds/re_9f... \
  -H "Authorization: Bearer sk_test_..."

Payouts

GET

/v1/payouts

List your settlement payouts, newest first.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Query parameters

Name	Type	Required	Description
limit	integer	no	1-100, default 20.

Example request

curl

curl "https://api.k-payments.com/v1/payouts?limit=20" \
  -H "Authorization: Bearer sk_test_..."

GET

/v1/payouts/:id

Fetch a single payout plus its itemised line items (charges, refunds, fees).

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Path parameters

Name	Type	Required	Description
id	string	yes	Payout id.

Example request

curl

curl https://api.k-payments.com/v1/payouts/po_... \
  -H "Authorization: Bearer sk_test_..."

Webhook endpoints

GET

/v1/webhook_endpoints

List all webhook endpoints configured for your merchant.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Example request

curl

curl https://api.k-payments.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..."

POST

/v1/webhook_endpoints

Register a new HTTPS endpoint to receive events. The response includes the signing secret — store it now; it cannot be retrieved later.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.
Content-Type	string	yes	application/json

Body parameters

Name	Type	Required	Description
url	string	yes	HTTPS URL, max 2048 chars.
enabled_events	array<string>	no	Up to 50 event types. Omit or use ["*"] for all.
description	string	no	Up to 200 chars.

Example request

curl

curl https://api.k-payments.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks", "enabled_events": ["charge.succeeded","refund.created"] }'

GET

/v1/webhook_endpoints/:id

Fetch a single endpoint (signing_secret is never returned here).

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Path parameters

Name	Type	Required	Description
id	string	yes	Endpoint id.

Example request

curl

curl https://api.k-payments.com/v1/webhook_endpoints/we_... \
  -H "Authorization: Bearer sk_test_..."

PATCH

/v1/webhook_endpoints/:id

Update url, enabled events, description, or enable/disable the endpoint.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.
Content-Type	string	yes	application/json

Path parameters

Name	Type	Required	Description
id	string	yes	Endpoint id.

Body parameters

Name	Type	Required	Description
url	string	no	New HTTPS URL.
enabled_events	array<string>	no	Replace the event list (max 50).
description	string	no	Up to 200 chars.
status	string	no	"enabled" or "disabled".

Example request

curl

curl -X PATCH https://api.k-payments.com/v1/webhook_endpoints/we_... \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

DELETE

/v1/webhook_endpoints/:id

Permanently delete an endpoint. Pending deliveries are abandoned.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Path parameters

Name	Type	Required	Description
id	string	yes	Endpoint id.

Example request

curl

curl -X DELETE https://api.k-payments.com/v1/webhook_endpoints/we_... \
  -H "Authorization: Bearer sk_test_..."

Events

GET

/v1/events

List recent events for your merchant. Useful for replay and debugging.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Query parameters

Name	Type	Required	Description
limit	integer	no	1-100, default 20.
type	string	no	Filter by exact type, e.g. "charge.succeeded".

Example request

curl

curl "https://api.k-payments.com/v1/events?type=charge.succeeded&limit=20" \
  -H "Authorization: Bearer sk_test_..."

GET

/v1/events/:id

Fetch a single event by id.

Version

Headers

Name	Type	Required	Description
Authorization	string	yes	Bearer <secret_api_key>. Use a sk_test_ or sk_live_ key from your dashboard.

Path parameters

Name	Type	Required	Description
id	string	yes	Event id.

Example request

curl

curl https://api.k-payments.com/v1/events/evt_... \
  -H "Authorization: Bearer sk_test_..."

Support

Reach a real human, fast.

Email support

Typical response within one business day.

support@k-payments.com

Status & incidents

Subscribe to real-time updates on processing and dashboard availability.

status.k-payments.com