Skip to content

Logo

KhanPay

Online payments made easy

Supports in this guide: Payments

Provider website: khanpay.kz

What you need to do for start processing transactions (brief summary)

  1. Get your credentials (from KhanPay)
  2. Connect in Dashboard
  3. Send an API request

Prerequisites: get from KhanPay

Contact your KhanPay account manager to get your account verified and receive the following credentials.

  • Point ID -> Corefy field point_id.
  • Service ID -> Corefy field service_id.
  • Certificate -> Corefy field certificate -> optional, uploaded as a file (a PKCS#12 bundle used for mutual TLS).
  • Certificate password -> Corefy field certificate_password -> optional, required together with Certificate.

EUR, USD, KZT, TRY.

Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

Open KhanPay in the provider directory and press Connect at KhanPay Provider Overview page in the New connection section.

Step 2 - Fill in fields and select settings

  • Point ID
  • Service ID
  • Certificate -> optional
  • Certificate password -> optional
  • Currency / Features -> choose values available for your account (EUR, USD, KZT, TRY)
  • Test Mode -> (enable if you are using sandbox credentials)
  • Customer data validation -> optional, choose which customer fields (see Options below) KhanPay should strictly require

Success

You have connected KhanPay H2H Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice; card data itself is collected and submitted separately by Corefy's checkout/SDK layer, not as part of this request.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6be05631-8710-4b14-a369-1928a2b70eda",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "199be985-c243-478a-86a8-4b8c902e5bb6",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Doe",
        "email": "name@example.com",
        "phone": "+380680786663",
        "address": {
          "full_address": "Main street 1",
          "country": "KZ",
          "city": "Almaty",
          "region": "Almaty",
          "post_code": "050000"
        }
      }
    }
  }
}

Important

  • Every customer/address field above is optional by default - if missing, Corefy sends the matching Constant instead, and if that's unset too, the field is simply left out of the request to KhanPay. There is no hardcoded fallback value.
  • A field only becomes required (rejected if still missing after the Constants fallback) when you select it in the Customer data validation option. By default nothing is required beyond the card data itself.
  • KhanPay may respond with a 3-D Secure redirect; Corefy forwards the customer to it automatically as part of the payment flow.

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional customer details for compliance/reconciliation - Positively influence conversion rate - Include optional fields required by your specific flow

Options

  • customer_data_validation -> optional, multi-select (Name, Email, Phone, Address, City, Country, Region, Postcode) - for each field you select here, Corefy requires it to be present (from the request or a Constant) before sending the payment to KhanPay; fields you don't select stay optional.

Constants (fallback fields)

Constants are static values that Corefy can send to the provider instead of dynamic data from your API request, when those fields are missing in the request.

Priority (predictable rule): 1. If a value is present in the request -> Corefy uses the request value 2. Else if the constant is set -> Corefy uses the constant 3. Else -> provider may reject the request or apply its defaults (depends on provider)

Currently available constants (constant -> Corefy API field)

  • NAME -> customer.name
  • EMAIL -> customer.email
  • PHONE -> customer.phone
  • FULL_ADDRESS -> customer.address.full_address
  • CITY -> customer.address.city
  • COUNTRY -> customer.address.country
  • REGION -> customer.address.region
  • POST_CODE -> customer.address.post_code

Refunds

KhanPay supports full-amount refunds only - no partial refunds, and only one refund per payment.

Additional info

  1. Active reconciliation only, no callback - KhanPay has no asynchronous callback; Corefy resolves the payment status via an active status request.
  2. No recurring - this connector does not support saving/charging a token through Corefy.
  3. Insecure fallback without a certificate - if you don't upload a Certificate/Certificate password, Corefy connects to KhanPay without verifying its SSL certificate. Uploading a certificate enables mutual TLS and full certificate verification - recommended for production use.
  4. The API protocol between Corefy and KhanPay is XML, not JSON - this is purely an internal implementation detail and doesn't change how you call the Corefy API.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the Point ID and Service ID
  • Connection works but transactions fail SSL verification -> upload a valid Certificate and Certificate password
  • Currency or service is not supported -> confirm allowed currencies/features in your KhanPay account and in Corefy - only EUR, USD, KZT, and TRY are available
  • A customer field is required unexpectedly -> check whether that field is selected in the Customer data validation option
  • Refund fails with multiple attempts -> only one, full-amount refund is allowed per payment

Question

Still looking for help connecting your KhanPay account? Please contact our support team!