GumballPay

Supports in this guide: Payments | Payouts

Provider website: finera.com

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

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

Choose account type

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

If you do card payments, or use local payment methods (iDEAL, Apple Pay, Google Pay, Open Banking) -> choose H2H Merchant account
If you do payouts -> choose Provider account

Unlike most connectors on this platform, card payments and local payment methods share the same H2H Merchant account connection — there's no separate account type for local methods. The underlying mechanisms are still genuinely different (direct card submission vs. redirect), and each has its own separate Options/Constants (see below). If you're not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from GumballPay

GumballPay issues separate credentials for each account type below.

For H2H Merchant account:

Login -> Corefy field login -> where to find: GumballPay backoffice / issued by GumballPay manager
Control Key -> Corefy field control_key -> where to find: GumballPay backoffice / issued by GumballPay manager -> used to sign every request/callback (HMAC-style secret)
Endpoint ID -> Corefy field endpoint_id -> your GumballPay endpoint identifier, appended to every request URL
Test Mode -> Corefy field test_mode
Multi-Currency Integration -> Corefy field is_multi_currency_integration -> enable only if GumballPay set up your endpoint for multi-currency — changes the request URL shape (adds a /group/ segment)
API URL -> optional, Corefy field api_url -> overrides the default production host

For Provider account:

Login -> Corefy field login
Control Key -> Corefy field control_key
Private Key -> optional, Corefy field private_key -> upload as a file; stored base64-encoded
Endpoint ID -> optional, Corefy field endpoint_id
Test Mode -> Corefy field test_mode
Multi-Currency Integration -> Corefy field is_multi_currency_integration
Disable Balance -> Corefy field disable_balance -> disables balance checks/reporting for this connection
API URL -> optional, Corefy field api_url

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

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

Login
Control Key
Endpoint ID
Test Mode
Multi-Currency Integration
API URL -> (optional)

Choose Currency. For direct card payments, GumballPay supports CAD, EUR, ZAR, NOK, NZD, USD, and AZN — check with your Corefy account manager which are enabled for your account. Local payment methods (iDEAL, Apple Pay, Google Pay, Open Banking) are EUR-only.

Success

You have connected GumballPay 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": 100,
      "customer": {
        "reference_id": "55041b5b-adfd-4073-a92b-fd8b495a4cc1"
      },
      "reference_id": "86e68af6-6b95-4cc0-be16-e4df8044604c"
    }
  }
}

customer itself must be present (even with just reference_id) — GumballPay's own request builder doesn't handle a fully-missing customer object gracefully. Every field inside customer is optional, but not blank if omitted: name defaults to John Doe, and address/phone/email fall back to a fixed placeholder (a German test address, a Russian test phone number, and a fixed test email) rather than being left empty. Send real values if you don't want GumballPay to receive placeholder data instead of your customer's.

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "bc75bc54-5023-4f98-8c0d-ec5ed7e8f380",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "date_of_birth": "1990-05-14",
        "address": {
          "country": "DE",
          "region": "Berlin",
          "city": "Berlin",
          "post_code": "10115",
          "full_address": "1st Street 1"
        }
      },
      "reference_id": "08f5e97c-1170-4bda-9625-3bde3c6dcd20"
    }
  }
}

customer.name is split into first/last name for GumballPay. customer.address.region is optional for most countries, but GumballPay's own API requires it (as state) for US, Canada, and Australia billing addresses. GumballPay also supports CAD, ZAR, NOK, NZD, USD, and AZN (use payment_card_<currency>_hpp as the service code, lowercase currency).

GumballPay also offers local payment methods over this same H2H Merchant account connection: iDEAL (ideal_eur_hpp), Apple Pay (applepay_eur_hpp), Google Pay (googlepay_eur_hpp), and Open Banking (openbanking_eur_hpp) — all EUR-only, all redirect flows (no card data submitted). They read the same customer fields shown above, but have their own separate Options/Constants (see below).

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 (direct card payments)

Options are configured on the Corefy side and affect how Corefy builds provider requests or processes responses. These apply to direct card payments only.

Currently available options (4)

ignore_callback - rejects every inbound callback from GumballPay without processing it
use_default_browser_info - fills in any missing browser/device fingerprint field with a fixed fallback instead of omitting it
allow_callback_for_all_transaction_types - broadens which callback events GumballPay sends (adds chargebacks/reversals, not just the final result)
custom_finalization_logic - prevents an "approved" response from being treated as an error even if it also carries an error code

ignore_callback

What it does: when enabled, Corefy rejects every inbound callback from GumballPay outright — nothing is processed from it, and the connection falls back to status polling/reconciliation only.

When to use: if you'd rather rely purely on reconciliation and don't want callback-driven updates for this connection.

Default: "false"

Allowed values: true, false

use_default_browser_info

What it does: when enabled, any browser/device fingerprint field Corefy doesn't have real data for is filled in with a fixed fallback value instead of being left out of the request.

When to use: enable if GumballPay requires a complete browser-info block and your integration doesn't reliably supply full browser data.

Default: "false"

Allowed values: true, false

allow_callback_for_all_transaction_types

What it does: switches which callback registration GumballPay uses for this connection — off (default) registers for the final transaction result only; on registers for a broader event set, including chargebacks and reversals.

When to use: enable if you need to be notified of chargebacks/reversals via callback rather than only through reconciliation.

Default: "false"

Allowed values: true, false

custom_finalization_logic

What it does: GumballPay can return a response marked "approved" that also carries an error-code-shaped field. With this option enabled, Corefy always treats such a response as successful rather than as an error.

When to use: enable if you're seeing payments that should have succeeded incorrectly reported as failed.

Default: "false"

Allowed values: true, false

Note

If you are not sure which value to select, please contact our support team!

Options (local payment methods)

site_url_metadata_key -> optional, names a metadata key on your payment-invoice request whose value Corefy should use as the order description sent to GumballPay (an alternative to the URL constant below)

Constants (fallback fields, direct card payments)

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 -> Corefy's own built-in placeholder is used (see Payment - MIN above) — GumballPay never receives a blank field

Currently available constants (constant -> Corefy API field)

ADDRESS -> customer.address.full_address
CITY -> customer.address.city
POST_CODE -> customer.address.post_code
COUNTRY -> customer.address.country
PHONE -> customer.phone
EMAIL -> customer.email
DATE_OF_BIRTH -> customer.date_of_birth
Several BROWSER_* constants (color depth, screen size, timezone, language, user agent, etc.) -> only used when the use_default_browser_info option above is enabled

Constants (fallback fields, local payment methods)

Local payment methods (iDEAL/Apple Pay/Google Pay/Open Banking) use a separate set of Constants, configured per service code — identical schema for all four:

FIRST_NAME -> customer.name
LAST_NAME -> customer.name
ADDRESS -> customer.address.full_address
CITY -> customer.address.city
ZIP -> customer.address.post_code
COUNTRY -> customer.address.country
PHONE -> customer.phone
EMAIL -> customer.email
IP -> customer's IP address
URL -> used as the order description sent to GumballPay, falling back to your payment's description/reference if unset

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields (provider -> Corefy)

Login -> login
Control Key -> control_key
Private Key -> private_key -> (optional, upload a file)
Endpoint ID -> endpoint_id -> (optional)
Test Mode -> test_mode
Multi-Currency Integration -> is_multi_currency_integration
Disable Balance -> disable_balance

Success

You have connected GumballPay Provider account!

First request to Corefy API (MIN)

What it does: creates a payout-invoice. GumballPay supports card payouts only, in EUR.

Payout - MIN

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "service": "payment_card_eur",
      "currency": "EUR",
      "amount": 100,
      "fields": {
        "card_number": "4111111111111111"
      },
      "reference_id": "86e68af6-6b95-4cc0-be16-e4df8044604c"
    }
  }
}

fields.card_number is required — nothing else is. The card's expiry and holder name come from Corefy's own card data when available; see Additional info for what happens if they're missing.

Payout - MAX

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "service": "payment_card_eur",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "55041b5b-adfd-4073-a92b-fd8b495a4cc1",
        "name": "John Smith"
      },
      "fields": {
        "card_number": "4111111111111111"
      },
      "reference_id": "08f5e97c-1170-4bda-9625-3bde3c6dcd20"
    }
  }
}

customer.name is used for the receiver's first/last name and the card's printed name — if omitted, these are simply sent blank rather than defaulting to placeholder data.

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

Additional info

H2H Merchant account:

Multi-Currency Integration changes the request URL GumballPay receives requests on (adds a /group/ segment) — only enable it if GumballPay specifically set up your endpoint this way.
Refunds are supported for direct card payments — partial refunds are allowed, but only one refund per transaction (not multiple partial refunds against the same payment).
Callbacks (for both direct card payments and local payment methods) are signed — Corefy verifies the signature automatically using your Control Key; there's nothing for you to configure.

Provider account:

GumballPay payouts support card payouts in EUR only — no bank transfer or e-wallet payout method is available through this connection.
Always send the card's real expiry date via your card data source when creating a payout. If it's missing, GumballPay receives a guessed expiry (the current month, one year out) instead of the card's actual one — this will likely be wrong and can cause the payout to fail.
Payout callbacks are signed the same way as payment callbacks, verified automatically.

FAQ / Troubleshooting

Invalid credentials / auth error -> verify your Login/Control Key/Endpoint ID match the selected environment (test vs live) and account type
Payment declined - invalid CVV -> GumballPay doesn't support CVV-less card payments; make sure CVV is captured and submitted
Refund rejected after a previous refund -> GumballPay only allows one refund per transaction; a second refund attempt on the same payment will fail
Billing/address data looks wrong on GumballPay's side -> if customer fields were left out of the request, GumballPay received Corefy's built-in placeholder data instead — send real values if you need accurate billing data recorded
Payout failed / wrong card expiry -> confirm your card data source actually supplies the card's real expiry — GumballPay payouts silently default to a guessed expiry if it's missing (see Additional info)
Not sure which account type to use? -> ask your Corefy account manager

Question

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