Cyberpay

Supports in this guide: Payments

Provider website: cyberpay.link

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

Choose account type
Get your credentials (from Cyberpay)
Connect in Dashboard
Send an API request

Choose account type

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

If you do direct card payments (H2H, card data sent directly) -> choose H2H Merchant account
If you do bank transfer or Cyberpay wallet redirect payments -> choose Provider account

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

Prerequisites: get from Cyberpay

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

API key -> Corefy field api_key -> both account types.
Signature key -> Corefy field signature_key -> both account types.
Merchant ID -> Corefy field merchant_id -> Provider account only.
Method -> Corefy field payment_method -> Provider account only, choose Bank Transfer or Cyberpay Wallet - this selects which service(s) become available on the connection.

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

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

API key
Signature key
Currency / Features -> choose values available for your account
Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected Cyberpay 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. Depending on the card and amount, Cyberpay may require a redirect step (for example for 3-D Secure) - Corefy handles this transparently as part of the same payment.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6be05631-8710-4b14-a369-1928a2b70eda",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "199be985-c243-478a-86a8-4b8c902e5bb6",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Doe",
        "email": "test@test.com",
        "phone": "+380680786663",
        "address": {
          "full_address": "Main street 1",
          "country": "GB",
          "city": "London",
          "post_code": "W1J 5AX"
        }
      }
    }
  }
}

Important

If a customer field is missing, it falls back to the matching Constant below; if neither is set, Cyberpay simply does not receive that field.

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 Cyberpay 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)

NAME -> customer.name
EMAIL -> customer.email
PHONE -> customer.phone
IP -> customer.metadata.ip, falls back further to the request's own origin IP if neither is set
STREET -> customer.address.full_address
COUNTRY -> customer.address.country
CUSTOMER_COUNTRY -> customer.address.country (a separate constant used for a second, internal country field Cyberpay expects)
POST_CODE -> customer.address.post_code
CITY -> customer.address.city
LANG -> not tied to any customer field - a fixed language code sent on every request

Refunds

Cyberpay supports refunds, but only the full amount, one refund per payment (partial and multiple refunds are not allowed), and no original transaction ID is required. There is no active refund-reconciliation - once a refund is submitted, its outcome is taken from that same response rather than a later status check.

Payments processing (connect Provider account, create payment-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

Merchant ID
API key
Signature key
Method -> choose Bank Transfer (EUR only) or Cyberpay Wallet (30+ local currencies)
Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected Cyberpay Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice and redirects the customer to Cyberpay's hosted payment page. Which services are available on the connection depends entirely on the Method chosen above: bank_transfer_aggregated_eur_hpp for Bank Transfer, or one cyberpay_wallet_<currency>_hpp service per supported currency for Cyberpay Wallet (for example cyberpay_wallet_brl_hpp, cyberpay_wallet_mxn_hpp, cyberpay_wallet_try_hpp, cyberpay_wallet_uah_hpp, and many more).

Payment - MIN

POST /api/payment-invoices

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

Important

customer.reference_id is required for every Payment on this flow - a request without it fails.

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "b8f1b6a2-6df3-4041-a083-8572bf055b03",
      "service": "cyberpay_wallet_brl_hpp",
      "currency": "BRL",
      "amount": 100,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Doe",
        "email": "test@test.com",
        "phone": "+380680786663",
        "address": {
          "full_address": "Main street 1",
          "country": "GB",
          "region": "London",
          "city": "London",
          "post_code": "W1J 5AX"
        }
      }
    }
  }
}

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 Cyberpay 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)

NAME -> customer.name
EMAIL -> customer.email
PHONE -> customer.phone
IP -> customer.metadata.ip
STREET -> customer.address.full_address
CITY -> customer.address.city
REGION -> customer.address.region
POST_CODE -> customer.address.post_code
COUNTRY -> customer.address.country
CUSTOMER_COUNTRY -> customer.address.country (a separate constant used for a second, internal country field Cyberpay expects)
LANG -> not tied to any customer field - one of EN, ES, PT, IN
USER_DEVICE -> not tied to any customer field - one of MOBILE, DESKTOP, TABLET
USER_AGENT -> not tied to any customer field - a fixed browser user-agent string

Refunds

Cyberpay does not support refunds on this account type.

Additional info

Active reconciliation and callbacks are both available on each flow independently - Corefy generates and sends the callback/notification URL to Cyberpay automatically with every request, so nothing needs to be configured on Cyberpay's side.
No recurring - this connector does not support saving/charging a token through Corefy.
No hardcoded fallback values exist for missing customer data on either flow - a field that isn't sent and has no matching Constant is simply left out of the request to Cyberpay.

FAQ / Troubleshooting

Invalid credentials / auth error -> verify the API key and Signature key for the selected environment (test_mode)
Provider account shows no available services -> confirm the Method (Bank Transfer or Cyberpay Wallet) selected when connecting matches the service/currency you're trying to use
Payment rejected for a Provider account -> confirm customer.reference_id is present - it is required for every Payment on that flow
Refund fails -> on H2H Merchant account, only one full-amount refund per payment is allowed; Provider account does not support refunds at all
Not sure which account type to use? -> ask your Corefy account manager

Question

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