Skip to content

External Provider

External Provider

External Provider is not a third-party PSP - it is a generic Payouts integration where Corefy calls a small, fixed HTTP/JSON API hosted by your own backend to process payouts.

Supports in this guide: Payouts

Note

No public provider website applies here - "External Provider" is an internal Corefy account type, not an external company. Your own system is the "provider" that Corefy connects to.

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

  1. Build a small HTTP/JSON endpoint on your own side implementing the contract described below (or use an existing integration if one of the two supported platforms applies to you).
  2. Connect in Dashboard as a Provider account, pointing Corefy at your endpoint.
  3. Send a Payout API request.

Prerequisites: get from your own backend

Unlike a regular connector, these values are not issued by a third party - you define them on your own API endpoint and enter them into Corefy so it knows how to reach and authenticate to your system.

  • Account ID -> Corefy field account_id -> an identifier your own backend uses to recognize the account; also used as the HTTP Basic Auth username.
  • API password -> Corefy field api_password -> HTTP Basic Auth password.
  • API URL -> Corefy field api_url -> base URL of your own endpoint (no trailing slash).
  • Method -> Corefy field method -> currently a fixed choice of Pokermatch or Slotoking. This selects which payout service/route becomes available on the connection - it is not a free-text value.

UAH only.

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Account ID
  • API password
  • API URL
  • Method -> choose Pokermatch or Slotoking

Success

You have connected External Provider Provider account!

First request to Corefy API (MIN)

What it does: creates a payout-invoice. Depending on the Method chosen when connecting the account, only one service is available on it - pokermatch_account_uah or slotoking_account_uah.

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "a1c9f6a0-2d5e-4a7b-9b1e-6a3f0d8c7b2a",
      "service": "pokermatch_account_uah",
      "currency": "UAH",
      "amount": 100,
      "customer": {
        "reference_id": "cus_123"
      },
      "fields": {
        "account": "77777777777777"
      }
    }
  }
}

Important

  • fields are passed through to your own endpoint as-is (see the /create call below) - Corefy does not validate or interpret their contents itself.
  • There are no Constants for this connector - if a customer field is missing, it is simply not sent.

Payout - MAX

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "d4b8e2f1-7c6a-4e9d-8f3b-1a2c5d6e7f8a",
      "service": "slotoking_account_uah",
      "currency": "UAH",
      "amount": 250,
      "customer": {
        "reference_id": "cus_456"
      },
      "fields": {
        "account": "77777777777777"
      }
    }
  }
}

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional details required by your own endpoint's fields contract - Include optional fields required by your specific flow

Refunds

External Provider does not support refunds - it only implements the Payouts side.

Additional info

How this connector actually works

Most connectors integrate Corefy with a third-party PSP that already runs its own API. External Provider is the reverse: your backend must implement a small, fixed JSON API, and Corefy (via the api_url/account_id/api_password you provide) calls it with HTTP Basic Auth. Every request's Content-Type is application/json.

Corefy call Your endpoint Method When it happens
Check balance GET {api_url}/balance GET Periodic balance polling
Validate before payout POST {api_url}/validate POST Before invoking a payout, and on manual verification
Create payout POST {api_url}/create POST When a payout-invoice is created
Process payout POST {api_url}/process POST Follow-up processing step, if your /create response needs it
Check payout status GET {api_url}/check/{transaction_id} GET Active reconciliation

/create and /validate request body sent by Corefy: 

{
  "service": "pokermatch_account",
  "amount": 100.0,
  "currency": "UAH",
  "reference_id": "a1c9f6a0-2d5e-4a7b-9b1e-6a3f0d8c7b2a",
  "fields": {
    "account": "77777777777777"
  }
}
(reference_id is omitted on /validate; fields always carries through every field you received in the payout-invoice's own fields object.)

Expected response from your endpoint (for /create, /process, /check): 

{
  "status": "processed",
  "transaction_id": "123456",
  "reference_id": "po_jkfjdfkj1212",
  "amount": 1,
  "fee": 0.05,
  "currency": "USD"
}
Or, on failure: 
{
  "error": "insufficient_funds",
  "status": "failed",
  "transaction_id": "123456",
  "reference_id": "po_jkfjdfkj1212",
  "amount": 1,
  "fee": null,
  "currency": "USD"
}

status values your endpoint can return (mapped to Corefy payout statuses):

Your status Corefy status
registered created
pending pending
processed success
failed failed

error/resolution codes your endpoint can return on failure:

Code Meaning
ok no error
insufficient_funds insufficient funds
expired operation expired
general_decline declined
transaction_not_found operation not found
incorrect_transaction invalid request

/validate response status values (used for account/payout verification):

Your status Meaning
payable account can receive this payout
blocked account blocked
not_found account not found
currency_not_available currency not supported by this account
amount_restricted amount not allowed

Your HTTP status code matters too: 200/201 are treated as success, 409 is treated as success (and must idempotently return the same data /check would), 401 as invalid credentials, 403 as IP forbidden, 404 as operation not found, 503/408/other 5xx as a temporary transport error (safe to retry).

Important

Your /balance response may list several currencies, but only a balance reported in UAH is turned into a usable Corefy deposit account - other currencies in that response are currently ignored.

  1. Active reconciliation is available - Corefy can call your /check/{transaction_id} endpoint to refresh a payout's status.
  2. No Payments, no recurring - this connector only implements Payouts; there is no card/HPP flow and no token saving.
  3. Method is fixed, not extensible from the Dashboard - only Pokermatch and Slotoking exist as selectable values today; adding a new platform requires a code change on Corefy's side, not just a new Dashboard account.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify account_id and api_password match what your own endpoint expects for HTTP Basic Auth
  • Connection test fails -> Corefy calls your /validate endpoint with a test payload during connection setup; make sure it responds with a recognized status value and HTTP 200/201
  • Payout stuck / not progressing -> check that your /check/{transaction_id} endpoint returns a valid status and the required fields (status, transaction_id, reference_id, amount, fee, currency)
  • Balance not appearing in Corefy -> only a UAH entry in your /balance response is picked up
  • Refund fails -> External Provider does not support refunds through Corefy

Question

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