Skip to main content

Kurv API integration guide

This guide covers how Payofy integrates with the Kurv payment rail, based directly on the official Kurv Developer Documentation.

1. Environments and credentials​

Kurv provides two isolated environments:

EnvironmentBase URLAPI Key Prefix
Sandbox (Test)https://api-sandbox.kurv.app/kp_test_
Production (Live)https://api.kurv.app/kp_live_

How authentication works​

All requests to Kurv require HTTPS and an HTTP Bearer header:

Authorization: Bearer kp_test_w3Lwv3CZIZzye4cYxxr0

2. Core API resources​

Payment requests (/payment-requests)​

Payofy initiates payments through Kurv payment requests. When a customer checks out:

  1. Payofy sends a POST https://api-sandbox.kurv.app/payment-requests with:
    • amount: Transaction total (for example 15).
    • currency: 3-letter ISO currency code (for example "USD").
    • reference_number: Payofy payment ID used for correlation.
    • request_methods: Array of delivery options (["EMAIL", "SMS", "WEB"]).
    • response_url: Webhook callback URL on Payofy where Kurv posts the result (https://api.payofy.si/v1/webhooks/kurv).
    • redirect_url: Where customer is sent after successful payment.
    • cancel_url: Where customer is sent if they click cancel.
  2. Kurv responds with a transaction_id and payment link.
  3. The customer completes payment via credit card, Apple Pay, Google Pay, or Kurv wallet.

Payment response (Webhook notification)​

After payment completes, Kurv makes an HTTP POST request to the response_url provided in the payment request.

Kurv sends a POST parameter called response containing stringified JSON:

{
  "response": "{\"status\":\"ACK\",\"result\":\"ACK\",\"payment_id\":\"cs2u7fv0i4793pdn8g20\",\"transaction_id\":\"1072539PO\",\"reference_number\":\"123\",\"payment_type\":\"CC.DB\",\"currency\":\"USD\",\"amount\":15,\"result_code\":100,\"result_description\":\"Transaction success.\",\"email\":\"customer@example.com\"}"
}

Payofy parses this payload:

  • result === "ACK": Successful payment. Payofy updates payment status to succeeded and posts ledger credits.
  • result === "NOK": Failed payment. Payofy marks the payment as failed and triggers merchant dunning.

Payment history and refunds (/payment-history)​

  • Query history: GET /payment-history?start_date=2026-01-01&end_date=2026-01-31
  • Lookup transaction: GET /payment-history/{payment_id}
  • Refund transaction: POST /payment-history/{payment_id}/refund with body {"amount": 10, "reason": "Customer return"}
  • Capture authorization: POST /payment-history/{payment_id}/capture

3. Merchant onboarding on Kurv​

To process live payments for merchants:

  1. Register your software application in the Kurv Developer Dashboard.
  2. Obtain your kp_test_ sandbox key and kp_live_ production key.
  3. Connect your merchant accounts to your application in the dashboard.
  4. Set application status to Published.
  5. Merchants must enable your application in their Kurv dashboard settings.