Skip to content

Logo

iCard

Supports in this guide: Payments

Provider website: icard.com

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

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

Choose account type

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

  • If you do H2H card payments -> choose H2H Merchant account

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

Prerequisites: get from iCard

Get the following values for your iCard project/account:

  • Merchant ID -> Corefy field merchant_id -> example: 000000000012345 -> where to find: iCard backoffice / issued by iCard manager. Sent as mid on every PAY-IN API request (authorization, capture, refund, reversal, and reconciliation) — identifies your outlet/site to iCard.
  • Merchant NMI ID -> Corefy field merchant_nmi_id -> example: MID3DS0001 -> where to find: iCard backoffice / issued by iCard manager. A separate identifier for iCard's EMV 3-D Secure service — sent as merchantidentifier on every version-check/authentication request during the 3-D Secure step. Distinct from the Merchant ID above.
  • User ID -> Corefy field user_id -> example: partner_01 -> where to find: iCard backoffice / issued by iCard manager. Sent as the User-ID header on every PAY-IN API request — tells iCard which pre-shared secret to validate the request signature against.
  • Shared Secret -> Corefy field shared_secret -> example: sh_9F3kD82jLxQ1vR7Z -> where to find: iCard backoffice / issued by iCard manager. The pre-shared secret Corefy uses to HMAC-SHA256-sign every request (JWT bearer token plus a body_hash header), per iCard's authentication scheme.
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Merchant ID
  • Merchant NMI ID
  • User ID
  • Shared Secret
  • Test Mode -> (enable if you are using sandbox credentials)

Choose Currency and Features. You can set these parameters according to available currencies and features for your iCard account, but it is necessary to check details of the connection with your Corefy account manager.

Success

You have connected iCard H2H Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10.04,
      "customer": {
        "reference_id": "cus_123",
        "email": "johnsmith@gmail.com",
        "name": "John Smith"
      },
      "browser_info": {
        "browser_ip": "195.114.222.200",
        "browser_accept_header": "text/html,application/xhtml+xml",
        "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "browser_language": "en-US",
        "browser_color_depth": "24",
        "browser_screen_height": "1080",
        "browser_screen_width": "1920",
        "browser_java_enabled": false,
        "browser_tz": "-120",
        "device_channel": "02"
      }
    }
  }
}

Every card sale goes through EMV 3-D Secure 2.0 authentication before iCard's own PAY-IN API ever sees it — none of the fields above are enforced by Corefy's own validation, but browser_info (and, to a lesser extent, customer.email/customer.name) feed the 3-D Secure risk engine that decides whether the cardholder gets a frictionless pass or a challenge. Sending accurate values reduces the chance of a forced challenge or a failed authentication; omitting them doesn't fail the request, but risks a worse 3-D Secure outcome. payment_card_eur_hpp is currently the only service code — iCard only supports EUR for this connector.

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

Options are configured on the Corefy side and affect how Corefy builds provider requests or processes responses.

Currently available options (1)

  • is_reconcile_original_icard_id_check_enabled - blocks a Reconcile request for a payment that's still mid-3-D-Secure.
is_reconcile_original_icard_id_check_enabled

What it does: Before reconciling, checks whether the payment's stored original ID is still the 3-D Secure server transaction ID rather than iCard's own transaction reference (trn) — meaning the 3-D Secure authentication step never completed and Complete Sale was never called. If enabled and that's the case, Reconcile fails immediately with an explicit error instead of calling iCard.

When to use: enable it if you want Reconcile to surface this specific "stuck mid-3DS" state explicitly, rather than letting iCard's own Transaction Retrieval command respond as if nothing unusual happened.

Default: "false"

Allowed values: true / false

Additional info

  1. Card payments are authenticated through EMV 3-D Secure 2.0, run via iCard's own third-party 3-D Secure service (currently Endeavour, at threedsecurempi.com) — not a Corefy subsystem. This happens automatically for every sale using your Merchant NMI ID; no separate merchant-side 3DS/MPI account setup is needed on Corefy's side. When a card requires a challenge, the cardholder is redirected to iCard's 3-D Secure page to complete it before the payment can be captured.

  2. Refunds require the original card data (pan/expiry) to be resubmitted, not just a reference to the original sale. iCard allows a partial refund, but only one refund can be processed per payment — a second refund against the same sale isn't supported.

  3. For sandbox testing, iCard's own EMV 3-D Secure test environment accepts the test identifier HighRiskTest (as merchant_nmi_id) with a fixed challenge PIN of 555, letting you borrow iCard's published test cards for 3-D Secure scenarios.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify you used the correct Merchant ID / Merchant NMI ID / User ID / Shared Secret for the chosen environment (sandbox vs production)
  • Currency or service is not supported -> iCard currently supports EUR only for this connector; confirm this matches your iCard account and Corefy configuration
  • 3-D Secure authentication fails or the payment is declined with no clear reason -> confirm your iCard MID is registered for 3D transactions (an unregistered MID declines all 3D transactions), and check that browser_info was sent accurately
  • Missing customer data fields -> provide them directly in the API request (this connector has no Constants fallback configured)
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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