Integration

Integrate Processing Only mode into your application

API integration

Processing Only mode uses dedicated HUB2 API endpoints, distinct from the standard aggregation model. The main difference is that transactions are processed through your own provider accounts instead of the HUB2 aggregated accounts. The available endpoints are documented here:

Delegation API

Go to the Delegation API reference

Authentication

Your integration uses the same HUB2 API keys, but the key must have the following permissions:

• Api.delegated_payment_create
• Api.delegated_transfer_create

Permissions configuration

Go to the API key permissions configuration guide

Transaction flow

1. Transaction request

When you initiate a transaction, HUB2:

1. Validates the request: checks your API key and the request format.
2. Routes it to the provider: sends the request to your configured provider account.
3. Processes the transaction: executes it with your provider credentials.
4. Returns the response: in the same format whatever the provider.

2. Provider processing

The transaction itself is processed directly by your provider:

API endpoints

Processing Only mode uses dedicated creation endpoints. The read endpoints are the same as in the standard circuit.

Payments

• POST /delegated/payments: creates a payment with your provider account. Unlike a standard payment, there is no need to create a payment intent first: this single request creates the payment intent and attempts the payment. Example:

Curl

curl --location 'https://api.hub2.io/delegated/payments' \
--header 'Environment: sandbox' \
--header 'MerchantId: [REDACTED]' \
--header 'Content-Type: application/json' \
--header 'ApiKey: [REDACTED]' \
--data '{
    "customerReference": "<YOUR_INTERNAL_CUSTOMER_REFERENCE>",
    "purchaseReference": "<YOUR_INTERNAL_REFERENCE>",
    "amount": 120,
    "currency": "XOF",
    "paymentMethod": "mobile_money",
    "country": "CI",
    "provider": "orange",
    "mobileMoney": {
        "msisdn": "00000001",
        "onCancelRedirectionUrl": "https://example.com/payment/canceled",
        "onFinishRedirectionUrl": "https://example.com/payment/finished",
        "workflow": "redirection"
    }
}'

• POST /delegated/payments/sync: creates a payment with your provider account in synchronous mode (see the synchronous circuit).
• GET /payments: lists payments (same endpoint as for standard payments). Set isDelegated=true to return only Processing Only payments. With isDelegated, from is required and the range must be shorter than one year, otherwise the API returns a 400 error.
• GET /payments/{id}/status: returns the status of a payment (same endpoint as for standard payments).

Payments integration guide

Go to the payments integration guide

Transfers

• POST /delegated/transfers: creates a transfer with your provider account. Only the endpoint differs from a standard transfer request. Example:

Curl

curl --location --request POST 'https://api.hub2.io/delegated/transfers' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "<YOUR_INTERNAL_REFERENCE>",
  "amount": 2000,
  "currency": "XOF",
  "description": "<YOUR_DESCRIPTION>",
  "destination": {
    "type": "mobile_money",
    "country": "CI",
    "recipientName": "John Doe",
    "msisdn": "[phone]",
    "provider": "orange"
  }
}'

• POST /delegated/transfers/irt: creates an IRT transfer with your provider account.
• GET /transfers: lists transfers (same endpoint as for standard transfers).
• GET /transfers/{id}/status: returns the status of a transfer (same endpoint as for standard transfers).

Transfers integration guide

Go to the transfers integration guide

Webhooks

Processing Only mode uses the same webhooks as the standard circuit. If webhooks are already configured for payments and transfers, no extra step is needed. Otherwise, see:

Webhooks integration guide

Go to the webhooks integration guide