Skip to content

Logo

XPAY

One application managing your finances

Supports in this guide: Payments

Provider website: xpay.com.ua

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

  1. Get your credentials (from XPAY)
  2. Generate and share a key pair
  3. Connect in Dashboard
  4. Send an API request

Prerequisites: get from XPAY

Contact XPAY support (via their website, hotline, Telegram, Facebook, or the XPAY application) to get your account verified and receive the following credentials.

  • Wallet ID -> Corefy field wallet_id -> issued by XPAY; also used as the fallback Terminal ID if one isn't set.
  • Terminal ID (optional) -> Corefy field terminal_id -> issued by XPAY; falls back to Wallet ID if not set.
  • Partner Token -> Corefy field partner_token.

Generate your own RSA key pair (2048 bits, PKIX-packaged, .pem format): 

openssl genrsa -out keypair.pem 2048
openssl rsa -in keypair.pem -pubout -out publickey.crt
Share the generated public key with XPAY and receive their public key in return.

  • API Public Key -> Corefy field api_public_key -> upload XPAY's public key (used to encrypt data sent to XPAY).
  • API Secret Key -> Corefy field api_secret_key -> upload your own private key (used to sign your requests); never share this one with XPAY.

Important

You require to provide a white list of IPs for connecting XPAY, so be sure to include the Corefy IP addresses on the list. To configure your account, XPAY may also request the following fixed URLs for payment status checking and callbacks:

  • https://psp-ext.paycore.io/xpayua/check as the Check request URL
  • https://psp-ext.paycore.io/xpayua/callback as the Pay request URL

UAH only.

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

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Wallet ID
  • Terminal ID (optional)
  • Partner Token
  • API Public Key (upload XPAY's public key)
  • API Secret Key (upload your own private key)
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected XPAY 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. XPAY processes this as a card-to-wallet transfer, topping up the wallet identified by customer.reference_id.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "1f2e3d4c-5b6a-4978-8c01-2d3e4f5a6b7c",
      "service": "payment_card_uah_hpp",
      "currency": "UAH",
      "amount": 100,
      "customer": {
        "reference_id": "recipient-wallet-123"
      }
    }
  }
}

Important

customer.reference_id is required - XPAY uses it directly as the recipient wallet ID for the card-to-wallet transfer, not merely as an internal reference.

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "2a3b4c5d-6e7f-4089-8d12-3e4f5a6b7c8d",
      "service": "payment_card_uah_hpp",
      "currency": "UAH",
      "amount": 100,
      "description": "Order #12345",
      "customer": {
        "reference_id": "recipient-wallet-123",
        "name": "Ivanov Ivan Ivanovych",
        "individual_tax_id": "1234567890"
      }
    }
  }
}

Important

  • customer.name is parsed into first/middle/last name parts according to the Customer Name Format option below.
  • customer.individual_tax_id is forwarded as the customer's tax ID.
  • description is sent as the payment purpose, when set.
  • Your own merchant details (company name, legal entity identifier, IBAN - taken automatically from your Corefy merchant profile) are included in every request.

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_name_format -> optional, enum (LAST, FIRST, MIDDLE, FIRST, MIDDLE, LAST, LAST, MIDDLE, FIRST, LAST, FIRST, FIRST, LAST) - how to split customer.name into first/middle/last name parts; defaults to LAST, FIRST, MIDDLE.
  • send_order -> optional, boolean - additionally sends your Commerce invoice reference as a separate order field.
  • payment_purpose (exposed in the Dashboard, but has no effect for this connector) -> this connector always derives the payment purpose from description instead; setting this option does not change the request sent to XPAY.

Refunds

XPAY supports partial refunds, but only one refund per payment (no multiple partial refunds against the same payment).

Additional info

  1. Active reconciliation is available - an active status request can be used to retrieve the current payment status.
  2. No recurring - this connector does not support saving/charging a token through Corefy.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify Wallet ID, Partner Token and the API key pair for the selected environment (test_mode)
  • Payment stuck or recipient not found -> confirm customer.reference_id matches a real wallet ID on XPAY's side - it's used directly as the transfer recipient
  • Setting payment_purpose has no effect -> this is expected for this connector; use description instead to control the payment purpose sent to XPAY
  • Currency or service is not supported -> confirm allowed currencies/features in your XPAY account and in Corefy - only UAH is available
  • Refund fails with multiple attempts -> only one refund per payment is allowed

Question

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