Integration

A payment is collected in five steps:

Create a payment intent (PaymentIntent).
Attempt a payment on it.
(Optional) On the client side, authenticate the payment attempt.
HUB2 processes the payment with the provider.
Retrieve the status of the PaymentIntent.

Create a payment intent

The PaymentIntent object represents the intent to collect a payment from a customer. It keeps track of the fees and of every payment attempt made during processing. The PaymentIntent must be created on the merchant server with an amount, a currency, a customer reference (customerReference) and a purchase reference (purchaseReference). Create a payment intent Sample request:

curl --location --request POST 'https://api.hub2.io/payment-intents' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerReference": "Test_01",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "amount": 200,
    "currency": "XOF"
}'

import fetch from 'node-fetch';

async function postPaymentIntents() {
    const response = await fetch('https://api.hub2.io/payment-intents', {
        method: 'POST',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "customerReference": "Test_01",
            "purchaseReference": "Test_YYYY_MM_DD_01",
            "amount": 200,
            "currency": "XOF"
        })
    });

    if (response.ok) {
        const result = await response.json();
        console.log(result);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

postPaymentIntents();

import requests
import json

url = 'https://api.hub2.io/payment-intents'

headers = {
    'ApiKey': '[REDACTED]',
    'MerchantId': '[REDACTED]',
    'Environment': 'sandbox',
    'Content-Type': 'application/json',
}

data = {
    "customerReference": "Test_01",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "amount": 200,
    "currency": "XOF"
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.ok:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

Store the id and the token returned in the response on the merchant side: the next steps require them.

The id is the unique reference of the PaymentIntent. It is used to attempt payments.
The token is a JSON Web Token (JWT) that authenticates the payment requests. It expires 30 minutes after the PaymentIntent is created: a payment attempt or an authentication sent with an expired token is refused with a 401 error (bad_payment_intent_token).

{
    "id": "pi_tffiDaXyWQu203rIXhujW",
    "createdAt": "2022-07-18T06:35:25.932Z",
    "updatedAt": "2022-07-18T06:35:25.944Z",
    "merchantId": "[REDACTED]",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "customerReference": "Test_01",
    "amount": 200,
    "currency": "XOF",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "status": "payment_required",
    "payments": [],
    "mode": "sandbox"
}

Attempt a payment on the payment intent

Once the PaymentIntent is created, collect the payment information from the end customer and attempt a Payment. To attempt a Payment, specify the paymentMethod and every required field described in the API reference. Attempt a payment This endpoint accepts the JWT token instead of your private API key, so the payment request can be sent directly from the client side (by the customer’s application), using the token retrieved previously.

curl --location --request POST 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "mobile_money",
    "country": "CI",
    "provider": "orange",
    "mobileMoney": {
        "msisdn": "00000001"
    }
}'

import fetch from 'node-fetch';

async function postPaymentIntents() {
    const response = await fetch('https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
            "paymentMethod": "mobile_money",
            "country": "CI",
            "provider": "orange",
            "mobileMoney": {
                "msisdn": "00000001"
            }
        })
    });

    if (response.ok) {
        const result = await response.json();
        console.log(result);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

postPaymentIntents();

import requests
import json

url = 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments'

headers = {
    'Content-Type': 'application/json',
}

data = {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "mobile_money",
    "country": "CI",
    "provider": "orange",
    "mobileMoney": {
        "msisdn": "00000001"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.ok:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

If the request succeeds, the API returns HTTP 201 with the full PaymentIntent object in the response body. The status is now processing and the payments array contains the new Payment attempt. Save the payment id to identify this attempt in the list: several payments can be attempted on one PaymentIntent.

{
    "id": "pi_tffiDaXyWQu203rIXhujW",
    "createdAt": "2022-07-18T06:35:25.932Z",
    "updatedAt": "2022-07-18T06:39:21.471Z",
    "merchantId": "[REDACTED]",
    "purchaseReference": "Test_YYYY_MM_DD_01",
    "customerReference": "Test_01",
    "amount": 200,
    "currency": "XOF",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "status": "processing",
    "payments": [
        {
            "id": "pay_GBc53h6dHvuuq4vlcP6dY",
            "intentId": "pi_tffiDaXyWQu203rIXhujW",
            "createdAt": "2022-07-18T06:39:20.721Z",
            "updatedAt": "2022-07-18T06:39:21.471Z",
            "amount": 207,
            "currency": "XOF",
            "status": "created",
            "method": "mobile_money",
            "country": "CI",
            "provider": "orange",
            "number": "00000001",
            "fees": [
                {
                    "currency": "XOF",
                    "id": "fee_drJQNmGYKQAqT7oulY519",
                    "label": "payments.customer_fee",
                    "rate": 3,
                    "rateType": "percent",
                    "amount": 7
                }
            ]
        }
    ],
    "mode": "sandbox"
}

Retrieve Payment status

After the payment attempt, HUB2 contacts the payment provider and updates the payment object according to its response. From this point, the payment status can be retrieved in two ways.

1. Register a webhook for payment events (recommended)

Use webhooks rather than polling the PaymentIntent for status updates. See Webhooks integration to implement them. Subscribe to the payment.* or payment_intent.* events. With this method, the merchant server is notified as soon as the Payment or the PaymentIntent is updated. No polling mechanism is needed, no rate limit applies and latency issues are avoided. Under high payment traffic, it also reduces the load on both the merchant servers and the HUB2 servers.

2. Status polling

Poll the payment status with the dedicated endpoint. Retrieve the status payment object

This endpoint is rate limited (5 requests per 5 seconds for a given payment) to prevent denial-of-service attacks. Beyond that limit, the API returns HTTP 429 - Too Many Requests. Take this into account when implementing status polling.

Sample request:

curl --location --request GET 'https://api.hub2.io/payments/pay_GBc53h6dHvuuq4vlcP6dY/status' \
--header 'ApiKey: [REDACTED]' \
--header 'MerchantId: [REDACTED]' \
--header 'Environment: sandbox'

import fetch from 'node-fetch';

async function getPaymentStatus() {
    const response = await fetch('https://api.hub2.io/payments/pay_GBc53h6dHvuuq4vlcP6dY/status', {
        method: 'GET',
        headers: {
            'ApiKey': '[REDACTED]',
            'MerchantId': '[REDACTED]',
            'Environment': 'sandbox'
        }
    });

    if (response.ok) {
        const result = await response.json();
        console.log(result);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

getPaymentStatus();

import requests

url = 'https://api.hub2.io/payments/pay_GBc53h6dHvuuq4vlcP6dY/status'

headers = {
    'ApiKey': '[REDACTED]',
    'MerchantId': '[REDACTED]',
    'Environment': 'sandbox',
}

response = requests.get(url, headers=headers)

if response.ok:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

This request returns the status of a payment. A separate endpoint returns the status of a payment intent. Retrieve a payment intent status

Important

Poll only while PaymentIntent.status is processing or action_required. Continuously polling a PaymentIntent whose status is payment_required, successful, failed or canceled will get the source IP address throttled or temporarily banned.

In most cases, the next PaymentIntent status is action_required. This status means that the customer must perform a manual action to authenticate or validate the payment.

Handle the customer action

The Payment object contains a nextAction object that describes the action required from the customer.

{
    "id": "pi_tffiDaXyWQu203rIXhujW",
    "...": "...",
    "amount": 200,
    "currency": "XOF",
    "status": "action_required",
    "payments": [
        {
            "id": "pay_GBc53h6dHvuuq4vlcP6dY",
            "intentId": "pi_tffiDaXyWQu203rIXhujW",
            "amount": 207,
            "currency": "XOF",
            "status": "pending",
            "method": "mobile_money",
            "country": "CI",
            "provider": "orange",
            "number": "00000001",
            "fees": ["..."],
            "nextAction": {
                "type": "otp",
                "message": "Sandbox mode. Type a 4-digit number to authenticate the payment."
            }
        }
    ],
    "nextAction": {
        "type": "otp",
        "message": "Sandbox mode. Type a 4-digit number to authenticate the payment."
    }
}

Important

The relevant part is: "nextAction": { "type": "otp", "message": "Sandbox mode. Type a 4-digit number to authenticate the payment." }.

Display nextAction.message to the end customer so they know how to validate the payment. The action type is one of:

redirection: provides everything needed to redirect the customer to an external page.
ussd: tells the customer which USSD procedure to follow to validate the payment.
otp: tells the customer how to generate a one-time password (OTP). The customer enters the OTP in a field, and you send it to the dedicated endpoint. Some providers accept the OTP directly in the payment attempt request (see the otp field of the mobileMoney object).

Bank collection

The bank collection feature lets a merchant offer customers a bank transfer payment option. The customer receives a unique reference to make the transfer.

Prerequisites

This payment method requires a prior KYB (Know Your Business) registration. Create a KYB registration

Payment process

The merchant creates a payment intent (PaymentIntent) as described above.
For the payment attempt, the merchant sets bank_transfer as the payment method and provides the bankTransfer object:
- kybName (required): the name declared in the KYB registration.
- expirationDelay (optional): number of seconds before the payment expires. Minimum 3600, default 1296000 (15 days).
HUB2 generates a unique reference for the transfer.
The customer receives this reference and makes the transfer.
The payment status is updated once the transfer is received. If no transfer is received before the expiration delay, the payment fails with the expired failure cause.

Attempt a payment

curl --location --request POST 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "bank_transfer",
    "country": "CI",
    "provider": "Bank",
    "bankTransfer": {
        "kybName": "Name declared in KYB",
        "expirationDelay": 3600
    }
}'

import fetch from 'node-fetch';

async function postPaymentIntents() {
    const response = await fetch('https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
            "paymentMethod": "bank_transfer",
            "country": "CI",
            "provider": "Bank",
            "bankTransfer": {
                "kybName": "Name declared in KYB",
                "expirationDelay": 3600
            }
        })
    });

    if (response.ok) {
        const result = await response.json();
        console.log(result);
    } else {
        console.log(`HTTP Status: ${response.status}`);
    }
}

postPaymentIntents();

import requests
import json

url = 'https://api.hub2.io/payment-intents/pi_tffiDaXyWQu203rIXhujW/payments'

headers = {
    'Content-Type': 'application/json',
}

data = {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnRJZCI6InBpX3RmZmlEYVh5V1F1MjAzcklYaHVqVyIsIm1lcmNoYW50SWQiOiIzIiwibW9kZSI6InNhbmRib3giLCJpYXQiOjE2NTgxMjYxMjV9.1eB6ifC2ldfRw5UstnVa-bQqIdx9_IGLRdwWyXzZR4o",
    "paymentMethod": "bank_transfer",
    "country": "CI",
    "provider": "Bank",
    "bankTransfer": {
        "kybName": "Name declared in KYB",
        "expirationDelay": 3600
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.ok:
    print(response.json())
else:
    print(f'HTTP Status: {response.status_code}')

API response

On success, the API returns a PaymentIntent object containing the bank transfer payment details, including the unique reference generated for the transfer.

Important: communicate the reference to the end customer so they can make the bank transfer. The payment status is updated once the transfer is received and processed.

Getting started

Transfers

Payments

Webhooks

Processing Only

Payment Links

Submerchants

Other

Create a payment intent

Attempt a payment on the payment intent

Retrieve Payment status

1. Register a webhook for payment events (recommended)

2. Status polling

Important

Handle the customer action

Important

Bank collection

Prerequisites

Payment process

API response

​Create a payment intent

​Attempt a payment on the payment intent

​Retrieve Payment status

​1. Register a webhook for payment events (recommended)

​2. Status polling

Important

​Handle the customer action

Important

​Bank collection

​Prerequisites

​Payment process

​API response

Create a payment intent

Attempt a payment on the payment intent

Retrieve Payment status

1. Register a webhook for payment events (recommended)

2. Status polling

Handle the customer action

Bank collection

Prerequisites

Payment process

API response