CrystalBank

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

• External system ID
• Login
• Password
• SSL certificate
• SSL certificate private key
• API URL (optional)
• Google Pay Merchant ID (optional)
• Test Mode -> (enable if you are using sandbox credentials)

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. Card, Apple Pay, and Google Pay are all supported on this same connection. CrystalBank may return a 3D Secure challenge redirect depending on the card.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "1709718547",
      "service": "payment_card_uah_hpp",
      "currency": "UAH",
      "amount": 100
    }
  }
}

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "1709718211",
      "service": "payment_card_uah_hpp",
      "currency": "UAH",
      "amount": 100,
      "customer": {
        "reference_id": "1709718211",
        "name": "Vlad Ivanov",
        "address": {
          "full_address": "7 rue dissoire-22",
          "country": "UA",
          "city": "Kyiv",
          "post_code": "65001"
        }
      }
    }
  }
}

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

• flow_type -> optional, enum (ecom, c2a) - ecom (default) is a standard card payment; c2a (card-to-account) additionally sends recipient account details (see Constants below) with the transaction.
• priority_send_customer_name -> optional, enum (customer_name, cardholder) - which name source wins when both are available: customer_name (default) prefers customer.name, falling back to the card's embossed name; cardholder does the opposite.
• customer_name_format -> optional, enum (LAST, FIRST, MIDDLE, FIRST, MIDDLE, LAST, LAST, MIDDLE, FIRST, LAST, FIRST, FIRST, LAST) - how to split the resolved name into parts; defaults to LAST, FIRST, MIDDLE.
• send_reference_id -> optional, boolean - sends customer.reference_id (or the REFERENCE_ID Constant) to CrystalBank; always sent automatically when flow_type is c2a.
• send_fm_data_on_refund -> exposed in the Dashboard, but currently has no effect on requests.

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)

• LANGUAGE -> 2-letter language code
• REFERENCE_ID -> fallback for customer.reference_id when send_reference_id is enabled (or always, in c2a mode)
• IBAN -> recipient account number for c2a mode; falls back to your own Corefy merchant profile IBAN if not set
• RECIPIENT_NAME -> recipient name for c2a mode - there is no request field for this, so it must be set here if you use c2a
• RECIPIENT_ACCOUNT_TYPE -> recipient account type for c2a mode; default 02
• RECIPIENT_COUNTRY -> recipient country (numeric ISO 3166-1) for c2a mode; default 804 (Ukraine)
• FUNDING_OR_PAYMENT_TRANSACTION_TYPE_INDICATOR -> transaction type indicator for c2a mode; default F52

Used only for Apple Pay / Google Pay: LANGUAGE, REFERENCE_ID, IBAN, RECIPIENT_NAME, RECIPIENT_ACCOUNT_TYPE - same meaning as above.

Refunds

CrystalBank supports partial and multiple refunds, with one exception: a refund requested on the same day as the original payment must be for the full amount (it's processed as a same-day reversal); partial refunds are only possible from the next day onward.