Skip to content

KUNA Pay

KUNA Pay

A flexible crypto payment platform that lets businesses accept card payments settled as crypto, and convert accepted payments into EUR or Tether.

Supports in this guide: Payments, Payouts

Provider website: pay.kuna.io

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

  1. Choose account type
  2. Get your credentials (from KUNA Pay)
  3. Connect in Dashboard
  4. Send an API request

Choose account type

KUNA Pay can be connected in different ways (depending on your needs):

  • If you do direct card payments (H2H, no redirect) -> choose H2H Merchant account
  • If you do redirect payments (hosted page), or need Payouts -> choose Provider account

If you're not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from KUNA Pay

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

  • Commerce account / Commerce ID -> Corefy field commerce_account (H2H Merchant account) or commerce_id (Provider account).
  • API key -> Corefy field api_key.
  • Callback key -> Corefy field key_for_callback (H2H Merchant account) or secret_key_callback (Provider account) -> used to verify the signature of callbacks sent by KUNA Pay.
  • API URL -> Corefy field api_url -> KUNA Pay's own API endpoint for your account; unlike most connectors this is not a fixed domain, so you must get the exact URL from KUNA Pay yourself.

H2H Merchant account currencies: UAH, RUB, EUR, USD.

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

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

Open KUNA Pay in the provider directory and press Connect at KUNA Pay Provider Overview page in the New connection section. Choose H2H Merchant account.

Step 2 - Fill in fields and select settings

  • Commerce account
  • API key
  • Callback key
  • API URL
  • Currency / Features -> choose values available for your account (UAH, RUB, EUR, USD)
  • Send metadata -> (optional)
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected KUNA Pay 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_uah_hpp",
      "currency": "UAH",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "199be985-c243-478a-86a8-4b8c902e5bb6",
      "service": "payment_card_uah_hpp",
      "currency": "UAH",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Doe",
        "email": "name@example.com"
      }
    }
  }
}

Important

If generate_random_customer_data is enabled and a customer field is still missing, KUNA Pay receives a realistic randomly generated value instead - this is opt-in, not a silent always-on default.

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

  • ignore_callback -> optional, boolean - for cascading to work correctly, ignores KUNA Pay's asynchronous callback and relies only on an active status request to finalize the payment.
  • save_provider_instant_token -> optional, boolean - saves a provider-side token for Recurring.
  • generate_random_customer_data -> optional, boolean - generates a realistic random customer identity when customer fields are missing from the request.
  • transliterate_customer_data -> optional, boolean - transliterates customer name fields before sending them to KUNA Pay.
  • set_description -> optional, boolean - sends a transaction description to KUNA Pay.
  • transliterate_card_holder -> optional, boolean - transliterates the cardholder name.
  • duplicate_original_resolution -> optional, boolean - duplicates the original transaction's resolution code on related operations.

Refunds

Important

KUNA Pay does not actually dispatch refunds, even though partial refunds appear allowed in the connection settings. The underlying gateway code only sends a refund request to KUNA Pay when a separate internal flag is explicitly turned on for a connector, and this flag is not turned on for KUNA Pay - so any refund attempt will fail rather than reaching KUNA Pay.

Payments and Payouts processing (connect Provider account, create payment-invoice / payout-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

Open KUNA Pay in the provider directory and press Connect at KUNA Pay Provider Overview page in the New connection section. Choose Provider account.

Step 2 - Fill in fields and select settings

  • Commerce ID
  • API key
  • Callback key
  • API URL
  • Send metadata -> (optional)
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected KUNA Pay Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice and redirects the customer to KUNA Pay's hosted checkout, or a payout-invoice for a card payout.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "209a2d42-8bad-4b50-bf27-c8da59b3878e",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 100
    }
  }
}

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "efbf0a2b-5590-42b7-b10b-94d49452147d",
      "service": "payment_card_eur",
      "currency": "EUR",
      "amount": 150,
      "customer": {
        "reference_id": "cus_123"
      }
    }
  }
}

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

Refunds

KUNA Pay does not support refunds on Payouts. On Payments, the same dispatch limitation described above for the H2H Merchant account applies here too - no refund actually reaches KUNA Pay.

Additional info

  1. Active reconciliation is available on both account types, in addition to the asynchronous callback.
  2. The API URL is account-specific, not fixed - unlike most connectors, KUNA Pay's endpoint isn't hardcoded; you must obtain the exact URL from your KUNA Pay account manager and enter it yourself.
  3. There is a separate, independently documented connector, KUNA Pay Crypto, for merchants who need wallet-based crypto payment/payout flows rather than card-based ones - it is a distinct connection in the Dashboard with its own credentials, not an option on this one.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the API key, callback key, and that the API URL exactly matches what KUNA Pay issued you
  • Callback not received -> check the API URL is correct and reachable; verify the callback key matches
  • Refund fails or has no effect -> KUNA Pay does not currently support refunds through Corefy on either account type
  • Looking for a crypto wallet flow instead of card payments? -> ask your Corefy account manager about the separate KUNA Pay Crypto connector

Question

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