Skip to content

Logo

Payball

Supports in this guide: Payments

Provider website: payball.com

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

  1. Get your credentials (from Payball)
  2. Connect in Dashboard
  3. Send an API request

Prerequisites: get from Payball

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

  • Merchant ID -> Corefy field merchant_id.
  • Payment method GUID -> Corefy field payment_method_id.
  • Private key -> Corefy field private_key.

USD, GBP, EUR.

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

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Merchant ID
  • Payment method GUID
  • Private key
  • Currency / Features -> choose values available for your account (USD, GBP, EUR)
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected Payball 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": "6be05631-8710-4b14-a369-1928a2b70eda",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123"
      }
    }
  }
}

Important

customer must be present in the request (even with just reference_id) - Payball's own request-building code reads customer.email, customer.phone and customer.date_of_birth without a null-safe check on the customer object itself, so a request with customer omitted entirely fails locally rather than falling back cleanly to Constants.

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",
        "date_of_birth": "1990-01-01",
        "address": {
          "full_address": "Main street 1",
          "country": "US",
          "region": "NY",
          "city": "New York",
          "post_code": "10001"
        }
      }
    }
  }
}

Important

  • customer.name is split into first/last name; if missing, the card's own embossed cardholder name is used instead.
  • customer.address.country is converted to its 3-letter (alpha-3) code before being sent to Payball.
  • Any field still missing after that falls back to the matching Constant below, then is simply left out of the request.

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

  • ignore_callback -> optional, boolean - for cascading to work correctly, ignores Payball's asynchronous callback and relies only on an active status request to finalize the payment.

Constants (fallback fields)

Constants are static values that Corefy can send to Payball 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)

  • FIRST_NAME / LAST_NAME -> parsed from customer.name
  • EMAIL -> customer.email
  • PHONE -> customer.phone
  • FULL_ADDRESS -> customer.address.full_address
  • CITY -> customer.address.city
  • REGION -> customer.address.region
  • COUNTRY -> customer.address.country (alpha-3 code, e.g. USA)
  • POST_CODE -> customer.address.post_code
  • DATE_OF_BIRTH -> customer.date_of_birth

Refunds

Payball does not support refunds.

Additional info

  1. Active reconciliation is available - both the asynchronous callback and an active status request can finalize the payment, unless ignore_callback is enabled.
  2. No recurring - this connector does not support saving/charging a token through Corefy.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify Merchant ID, Payment method GUID and Private key for the selected environment (test_mode)
  • Currency or service is not supported -> confirm allowed currencies/features in your Payball account and in Corefy - only USD, GBP and EUR are available
  • Request fails with missing customer data -> make sure customer.reference_id is sent even when no other customer fields apply
  • Refund fails -> Payball does not support refunds through Corefy

Question

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