Skip to content

Payout Gateway

Payout Gateway is a part of PayCore.io® Payment Infrastructure to initiate and manage payouts. This gateway enables you to securely initiate financial transactions within connected payment providers in order to send payments to a large number of recipients simultaneously. There are two ways to initiate a financial transaction: payout and payout request.

Payout operation

It's a low-level operation that initiates a financial transaction in the defined payment provider using the specified payment method, it simply provides communication with an external provider and the mapping of statuses. It is also allowing to receive a processed payment amount that in some cases may be less rather than the initiated payment amount.

Payout request operation

Payout request is an operation with rich functionality to initiate a financial transaction due to the use of routing and exchange rate schemes. For example, this use enables to apply an exchange rate if a payout is made in the different currency then the currency of the deposit account where it is initiated from. The routing or failover conditions can be applied or changed using web interface in the in the appropriate Routing Scheme settings at the Dashboard. Those conditions will influence the selection of a deposit account from which a financial transaction will be initiated and the amount, which will be debited from this deposit account.

Whensoever a payout request is initiated it creates at least one payout operation. For example, if a payout operation fails or 'split mode' is set then multiple payout operations may be created to finalise the payout request until the final status is obtained. You can find all created payouts for every initiated payout request in the Payout Request tab in the Operations menu at the Dashboard.

Below you can find the list of statuses for both payout and payout request operations.

Create a payout request

To create your first payout request, follow these steps:

  1. Create a payout point and set currencies of the payout point.
  2. Connect a test provider account;
  3. Generate an API key. The API key does not expire. If an API is compromissed, you can revoke it and generate a new one.

NOTES:

  1. If you require to add a currency of payout point, which is not listed in the drop down menu, then please write us a message to [email protected] to support this currency.
  2. A payout point currency is used mainly for accounting and reporting but you should specify at least one. The payout currency is a mandatory attribute ('point_currency') in a payout request, but it doesn't mean you can not initiate a financial transaction in the currency, which is different from the currency of the payout point.

PayCore.io® has a test mode you should use for testing. It operates separately from live mode, so you can make changes without affecting your live data. Using a test provider account it is possible only to initiate test payout requests. Payout and payment requests can be initiated from live deposit accounts only when you connect at least one provider, which supports payouts from the list of established integrations. You can request a new integration by contacting our Customer Service team.

This example shows how to create a Payout Request:

POST /v1/payout-gateway/payout-requests HTTP/1.1
Host: api.paycore.io
Content-Type: application/json

{
  "data": {
    "type": "payout-request",
    "attributes": {
      "point_amount": 1,
        "point_id": "pop_SHZxNhPrDHtCf8hH",
      "point_currency": "USD",
      "service": "test_usd",
      "test_mode": true,
      "fields": {
          "account":"some_random_string"
      }
    }
  }
}

The full list of properties and atributes available in the PayCore.io® Public API documentation. The content of fields must be set according to 'payout-service'. The list of available payout services can be found in the Payout Gateway on the Dashboard the Payout Routes tab. The payout service fields can be found in the Payout Services tab.

Here is a list of terms we use and their definitions on payouts.

DefinitionDescription
Payoutrefers to the financial return or monetary disbursement of investment or annuity.
Payout PointAn aggregation entity that sets a configuration for processing a payout request through links to the exchange rate scheme and the routing scheme that are set for it.
Payout requestOperation for abstraction from route and payout. Allows dynamic routing and failover for payouts.
Payout Request Event Event log for a specific request for payout. Gives detailed information about the process for requesting payout.
Payout Routing Scheme Aggregation entity responsible for routing configuration. Consists of a set of routing rules for each payout method
Payout Routing RuleRoute processing rule for the payout method currency. Sets the route processing strategy and the conditions under which this strategy will be active.

Routing

Definition

Routing Engine - is a system component which is indended to determine the route of processed operation.

Routing engine is responsible for automating dynamic Routing Rules and Routing Strategies.

Routing rules are defined in the Routing Scheme, which is set for the Payout Point.

Definition

Routing Scheme - contains dynamic Routing rules that are executed when the conditions match, which are defined for context attributes.

Routing logic diagram

Routing

Routing Strategy

Info

Payout Routing Strategy describes how payouts are routed.

If all the conditions of the rule are met, the routing strategy is established for it's available routes.

Routing Strategy Types

TypeDescriptionDiagram
Optimal Funds are debited in equal shares from each route
Load balancing
(Weight)
Funds are debited proportionally (as a percentage) from each route
It is available to set load percentage manualy
Optimisation By Deposit Account Balance & LimitsThe funds are debited off from routes as the balance decreases (taking into account limits).
Stages:
1) Filter routes for which you can write off for a specific amount
2) Choosing a route with maximum balance
3) Performing an operation
Optimisation By Conversion
Optimization By Cost