Skip to content

Logo

Mercuryo

The payment engine behind top web3 business

Supports in this guide: Payments, Payouts

Provider website: mercuryo.io

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

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

Choose account type

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

  • If you do H2H card payments (card data sent directly, non-3DS cards only) -> choose H2H Merchant account
  • If you do hosted-widget payments (card or crypto, customer completes the purchase on Mercuryo's own page) -> choose Merchant account
  • If you do payouts -> choose Provider account

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

Prerequisites: get from Mercuryo

For H2H Merchant account:

  • Login -> Corefy field login.
  • API Key -> Corefy field api_key.
  • Secret Key -> Corefy field secret_key -> used to sign every request.

For Merchant account:

  • Client ID -> Corefy field client_id.
  • Client Secret -> Corefy field client_secret.
  • Webhook Secret -> Corefy field webhook_secret -> used to verify callback notifications from Mercuryo.

For Provider account:

  • Service ID -> Corefy field service_id.
  • Secret Key -> Corefy field secret_key.
  • Currency -> Corefy field currency -> single-select, choose from the currencies enabled for your account.
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Login
  • API Key
  • Secret Key
  • Test Mode -> (enable if you are using sandbox credentials)
  • API URL (optional) -> overrides the default API host.
  • Merchant URL (optional) -> overrides the domain of the success/failure redirect Corefy sends to Mercuryo, so the customer is redirected back through your own domain instead of Corefy's default one.

Choose Currency and Features. USD and EUR are confirmed; check with your Corefy account manager which are enabled for your account.

Success

You have connected Mercuryo 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": "8e3dbbb0-17af-4c9a-bedb-93bdac6900a2",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "address": {
          "country": "DE",
          "city": "Berlin",
          "full_address": "1 Main street",
          "post_code": "10115"
        }
      }
    }
  }
}

Important

Unlike most H2H connectors, customer here is not optional. Mercuryo rejects the sale outright unless Corefy can resolve customer.name (first/last), customer.email, and a full customer.address (city/country/full_address/post_code) - either from the request or from the Constants below (email has no Constants fallback - always send it in the request). For US/CA/AU addresses specifically, customer.address.region must also resolve to a valid state - if it can't, the sale fails with "Region not found".

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6795502c-e27d-4d07-85e0-93245aab9a3f",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "address": {
          "country": "US",
          "region": "California",
          "city": "Los Angeles",
          "full_address": "1 Main street",
          "post_code": "90001"
        }
      }
    }
  }
}

Important

Mercuryo does not support 3D Secure - if the issuer determines the card requires a 3DS challenge, the sale is declined immediately rather than stepping up. This connector is only suitable for cards your customers can authenticate without 3DS.

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

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)

  • CUSTOMER_FIRST_NAME -> customer.name (first part)
  • CUSTOMER_LAST_NAME -> customer.name (second part)
  • CUSTOMER_COUNTRY -> customer.address.country
  • CUSTOMER_CITY -> customer.address.city
  • CUSTOMER_ADDRESS_LINE_1 -> customer.address.full_address
  • CUSTOMER_POST_CODE -> customer.address.post_code
  • CUSTOMER_REGION -> customer.address.region (only read for US/CA/AU)
Payments processing (connect Merchant account, create payment-invoice)

Connect Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Client ID
  • Client Secret
  • Webhook Secret
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected Mercuryo Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice and returns a redirect link to Mercuryo's hosted widget, where the customer buys with a card or crypto and completes any KYC Mercuryo itself requires.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "8e3dbbb0-17af-4c9a-bedb-93bdac6900a2",
      "service": "mercuryo_usd_hpp",
      "currency": "USD",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6795502c-e27d-4d07-85e0-93245aab9a3f",
      "service": "mercuryo_usd_hpp",
      "currency": "USD",
      "amount": 10
    }
  }
}

customer is not used on this flow at all - Mercuryo collects the customer's details and KYC itself on its own hosted widget. This connector also supports EUR and BTC (use mercuryo_eur_hpp/mercuryo_btc_hpp as the service code).

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

No Options or Constants are configured for this flow.

Payouts processing (connect Provider account, create payout-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Service ID
  • Secret Key
  • Currency -> single-select
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected Mercuryo Provider account!

First request to Corefy API (MIN)

What it does: creates a payout-invoice and sends funds to a card.

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "0dde9e79-2c64-4703-adaf-93d710633401",
      "service": "payment_card_eur",
      "currency": "EUR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith"
      },
      "fields": {
        "card_number": "4111111111111111"
      }
    }
  }
}

Payout - MAX

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "7976b4ce-fadd-4585-baa0-6b02c65351dc",
      "service": "payment_card_eur",
      "currency": "EUR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "metadata": {
          "date_of_birth": "1990-01-01"
        }
      },
      "fields": {
        "card_number": "4111111111111111"
      }
    }
  }
}

fields.card_number is required; the cardholder's name is derived from customer.name. customer.phone, customer.email, and customer.metadata.date_of_birth are all optional. This connector also supports USD, GBP, UAH, KZT, and RUB (use payment_card_<ccy> as the service code).

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

No Options or Constants are configured for this flow.

Additional info

  1. Callback routing. For H2H Merchant account, callback routing is handled automatically - Corefy generates the callback URL per transaction. For Merchant account (Payments), callback signatures are verified using the Webhook Secret. For Provider account (Payouts), callback routing is also automatic.
  2. No 3D Secure on the H2H flow. This is the main limitation of the H2H Merchant account - any card the issuer flags for 3DS is declined rather than challenged. If you need 3DS-eligible cards covered, route them to a different connector, or use the Merchant account (hosted widget) flow instead, where Mercuryo itself handles authentication.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify credentials for the selected environment and account type
  • H2H payment declined immediately -> the card likely requires 3D Secure, which this connector's H2H flow doesn't support
  • H2H payment rejected for missing customer details -> customer.name, customer.email, and a full customer.address are required (email has no fallback Constant); for US/CA/AU the address region must also resolve
  • Currency or service is not supported -> confirm allowed currencies/features in your Mercuryo account and in Corefy
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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