API Integration

Processing Only mode uses dedicated HUB2 API endpoints that are different from our traditional aggregation model. The main difference is that transactions are processed directly through your provider accounts instead of our aggregated accounts. Available endpoint are availble at:

Delegation API

Authentication

Your integration uses the same HUB2 API keys for authentication but the key must have new permissions:
  • Api.delegated_payment_create
  • Api.delegated_transfer_create

Permissions Configuration

Transaction Flow

1. Transaction Request

When you initiate a transaction, HUB2 will:
  1. Validate Request: Check your API key and request format
  2. Route to Provider: Direct the request to your configured provider account
  3. Process Transaction: Execute the transaction using your provider credentials
  4. Return Response: Provide a unified response format regardless of the provider

2. Provider Processing

The actual transaction processing happens directly with your provider:

API Endpoints

Processing Only mode uses dedicated creation endpoints, while reading endpoints remain the same as traditional ones:

Payments

  • POST /delegated/payments - Create a payment using your provider account Unlike classic payments, there’s no need to create a payment intent first before attempting a payment. Here, you directly make the payment attempt. Here’s an example.
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://failed.com",
        "onFinishRedirectionUrl": "https://success.com",
        "workflow": "redirection"
    }
}'

Payments integration guide

Transfers

  • POST /delegated/transfers - Create a transfer using your provider accounts. Below is an example. Only the endpoint changes here in the request.
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": "+225000000000",
    "provider": "orange"
  }
}'
  • POST /delegated/transfers/irt - Create an IRT transfer using your provider accounts
  • GET /transfers - List transfers (same as classic transfers)
  • GET /transfers/{id}/status - Get transfer status (same as classic transfers)

Transfers integration guide

Webhooks

This uses the same webhooks as the classic circuit. If you’ve already configured webhooks for payments/ transfers, no extra steps are required. Else, see:

Webhooks integration guide