Payments

POST https://sandbox-api.ubiqpay.io/v1/payments

The merchant's system sends a request to Ubiqpay to debit the customer's account.

Server-to-server Integration

Mobile Money

In Server-to-server mode, the merchant displays the phone number inputs to the customer. The typical checkout flow involves the following steps:

1. The customer is redirected to the merchant's checkout page.
2. The customer selects the correct payment option (the correct Mobile Money provider), enters his phone number.
3. (Optional) Some mobile operators require a voucher or an OTP code. In that case, the customer must dial a USSD shortcode to get the code, then, the customer enters the code before validating the payment. See: https://ubiqpay.readme.io/reference/payment-options#voucher
4. After the customer confirms payment, a push pin prompt or an SMS will be sent to the customer.
5. Once the payment is validated, Ubiqpay sends a callback to the merchant with the final transaction status.
6. The merchant redirects the customer to notify the customer that the order has been validated.

This mode requires 1 mandatory property:

• msisdn: Customer's phone number in international format.

Below is an example:

JSON

{
  "amount": 31000,
  "email": "[email protected]",
  "first_name": "John",
  "language": "EN",
  "last_name": "Doe",
  "merchant_reference": "merchant-ref-momo1234",
  "msisdn": "[phone]",
  "callback_url": "https://1234.eu.ngrok.io",
  "payment_option_id": 9,
  "voucher": "1234" // Optional: only if required by the payment option
}

🚧

Voucher / OTP Required

For some payment options, a voucher code is required. You can add a field voucher in your payment request.

Redirect Flow

Below is a request using the redirect flow. This flow allows redirecting the customer to a checkout or provider page to securely select or complete the transaction. Pay close attention to the mandatory redirect_url parameter in the request and the payment_url in the response. You must always redirect your customer to this URL.

While it is technically possible to use an iframe, it is not recommended. As of today, many browsers, especially on mobile devices, block such usage. Therefore, we strongly advise redirecting the user to a new page instead.

📘

Redirect flow

This flow is available for Mobile Money, card payments, bank payments, and external payment methods. To determine whether the option uses the redirect flow, call the Payment Options API.

JSON

{
  "amount": 100,
  "merchant_reference": "ba86076c-a763-449e-9eb8-7a774500899b",
  "msisdn": "[phone]",
  "callback_url": "https://merchant.com/callback",
  "redirect_url": "https://merchant.com/redirect",
  "payment_option_id": "329",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]"
}

Response:

JSON

{
    "status_code": "success",
    "message": "Request processed successfully",
    "data": {
        "id": "e02e4c9b-eadc-11ef-a03c-0242ac120002",
        "amount": 100,
        "country_code": "CI",
        "currency": "XOF",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "language": "EN",
        "msisdn": "[phone]",
        "merchant_reference": "ba86076c-a763-449e-9eb8-7a774500899b",
        "transaction_id": "236610690629009408",
        "narration": "236610690629009408",
        "payment_method": "MOBILE_MONEY",
        "payment_status": "pending",
        "payment_url": "https://mpayment.orange-money.com/ci/mpayment/abstract/*********************",
        "rounded": false,
        "original_amount": 100,
        "fees": 0.00,
        "created_at": "2024-02-14T14:06:24.637",
        "updated_at": "2024-02-14T14:06:25.037"
    }
}

Card

In Server-to-server mode, the merchant displays the card and billing inputs to the customer. The typical checkout flow involves the following steps:

1. The customer is redirected to the merchant's checkout page.
2. The customer enters their details, such as billing address, card number, expiration date, and CVV code.
3. After the customer confirms payment, the merchant encrypts the payment details and requests a new payment from the Ubiqpay platform.
4. Upon processing the request, the Ubiqpay platform responds to the merchant, which contains a payment_url property.
5. The merchant loads the payment URL to allow the customer to validate the 3D Secure security process.
6. The customer validates the 3D Secure security process.
7. Once the payment is validated, Ubiqpay sends a callback to the merchant with the final transaction status.
8. The merchant redirects the customer, which confirms the order.

📘

Required parameters

If the payment flow of the payment option is direct, 3 fields are required:

• billing: This field holds the billing information associated with the transaction.
• card: This encrypted string includes the card number, expiry date, and CVV code.
• browser_details: This field contains information about the customer's browser, which is used to help prevent fraudulent transactions.

For other flows, the customer may have to follow instructions or enters card details on an external page.

Below is an example for the direct flow:

JSON

{
  "payment_option_id": 7,
  "billing": {
    "full_name": "John Doe",
    "address": "37 Jesmond Rd",
    "zip": "NP6 0WP",
    "city": "Kilgwrrwg Common",
    "state": "",
    "country_code": "KE"
  },
  "card": "cEF0MHJqS1M3eE9YTUxhWUhIdjRKS09RWmNzT0xaQVBrZnZhUmE4Zlg4MFVQdFFTRU5HZE1WL1lpTW1Gbk9PdEIrTkNOcUg3MTRaaGh1MThBZ1F1YUxUTUtRcXltNlRwTno3UkF4d3hESXpQUFBqTWJrYStVcHFnNUxjdVFpa1RqdU5XMFVDY0NLb2o5ZFFOendhbER0dlUzUk03VVRHUDA2WWVvVm96S1ZrPQ==",
  ...
  "browser_details": {
    "accept_header": "text\/html",
    "screen_color_depth": "24",
    "language": "en-US",
    "screen_height": "768",
    "screen_width": "1366",
    "timezone": "-180",
    "java_enabled": "false",
    "javascript_enabled": "true",
    "ip_address": "192.123.12.1",
    "user_agent": "Firefox 105.0"
  }
}

Card Encryption

Encrypting card details is a necessary step to secure them during transaction processing.

You must encrypt thecard JSON object as below:

JSON

{
  "full_name": "John Smith",
  "number": "4111111111111111",
  "cvv": "123",
  "expiry": {
    "month": "12",
    "year": "25"
  }
}

The following script can be used to accomplish this:

Java

public static String encrypt(String plainText, String ivKey, String secretKey) throws Exception {
    MessageDigest digest = MessageDigest.getInstance("SHA-256");
    byte[] hashedIV = digest.digest(ivKey.getBytes(StandardCharsets.UTF_8));
    byte[] hashedSecret = digest.digest(secretKey.getBytes(StandardCharsets.UTF_8));

    IvParameterSpec IV = new IvParameterSpec(bytesToHex(hashedIV).substring(0, 16).getBytes(StandardCharsets.UTF_8));
    SecretKeySpec secret = new SecretKeySpec(bytesToHex(hashedSecret).substring(0, 32).getBytes(StandardCharsets.UTF_8), "AES");

    Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
    cipher.init(Cipher.ENCRYPT_MODE, secret, IV);
    byte[] encrypted = cipher.doFinal(plainText.getBytes(StandardCharsets.UTF_8));

    String base64Encoded = Base64.getEncoder().encodeToString(encrypted);
    return base64Encoded;
}

/**
 * bytesToHex - a function to convert encrypted byte to a hexadecimal String
 *
 * @param data byte[]
 * @return string String
 */
public static String bytesToHex(byte[] data) {
    if (data == null) {
        return null;
    }

    StringBuilder hexString = new StringBuilder();
    for (byte b : data) {
        String hex = Integer.toHexString(0xff & b);
        if (hex.length() == 1) {
            hexString.append('0');
        }
        hexString.append(hex);
    }
    return hexString.toString();
}

JavaScript

const CryptoJS = require('crypto-js');

function encrypt(plainText, ivKey, secretKey) {
  const hashedIV = CryptoJS.SHA256(ivKey).toString(CryptoJS.enc.Hex);
  const hashedSecret = CryptoJS.SHA256(secretKey).toString(CryptoJS.enc.Hex);

  const IV = CryptoJS.enc.Utf8.parse(hashedIV.substring(0, 16));
  const secret = CryptoJS.enc.Utf8.parse(hashedSecret.substring(0, 32));

  const encrypted = CryptoJS.AES.encrypt(plainText, secret, { iv: IV, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 });

  return CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(encrypted.toString()));
}

In the code above, we are using:

• AES encryption with CBC mode and PKCS5Padding
• SHA-256 to derive the IV and key from the provided inputs
• Base64 encoding to convert the encrypted byte array into a string

Bank

Except for a few payment options, most do not require bank details from the customer in the payment request. Most payment options use instructions or redirect payment flow.

Thus, the integration is similar to the MOBILE_MONEY payment method.

When using a bank payment option with a direct flow, your request body must include a field called bank. This field represents an object with the following properties:

JSON

{
  "account_number": "0001234",
  "account_birth_date": "01/12/1986",
  "account_owner": "John Smith"
}

External

The external payment method encompasses all payment options that require an external application to validate the payment, such as Snapscan, Mybux, Arakapay, and others.

Typically, the customer will need to follow instructions, which may involve completing several steps or scanning a QR code, in order to validate the payment.

The process is similar to the MOBILE_MONEY and BANK methods.

Fawry

Example of a Fawry request:

json

{
  "amount": 200,
  "currency": "EGP",
  "country_code": "EG",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "language": "EN",
  "merchant_reference": "ZJ283HE13",
  "msisdn": "[phone]",
  "narration": "Account deposit 201012345678",
  "payment_method": "EXTERNAL",
  "payment_option_id": 275,
  "callback_url": "https://my.callback.url"
}

Response:

JSON

{
  "status_code": "success",
  "message": "Request processed successfully",
  "data": {
    "id": "71851d93-deed-11ef-a6eb-0242ac1212345",
    "amount": 200,
    "country_code": "EG",
    "currency": "EGP",
    "instructions": "<div style=\"font-family:Arial,'Helvetica Neue',Helvetica,sans-serif;color:#333\"dir=rtl lang=ar><p>للدفع عن طريق فوري، يمكن استخدام كود الدفع المرجعي في الحاوية أدناه. اتبع الخطوات التالية لإتمام عملية الدفع باستخدام المحفظة الإلكترونية:</p><div style=\"background-color:#f2f2f2;padding:20px;text-align:center;margin:10px 0;font-size:24px;border-radius:5px\"><strong>9874050123</strong></div><ol><li>اذهب إلى تطبيق المحفظة الإلكترونية الخاص بك.</li><li>اختر \"فوري باي\" من الخدمات المتاحة.</li><li>ادخل كود الدفع المرجعي الموضح أعلاه.</li><li>تأكد من صحة المعلومات وقم بالتأكيد لإتمام العملية.</li></ol><p>بديلًا، يمكنك الدفع نقدًا في أي متجر تابع لفوري بلس.</p></div>",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "language": "EN",
    "msisdn": "[phone]",
    "merchant_reference": "ZJ283HE13",
    "transaction_id": "2211065131737712345",
    "narration": "Account deposit 201012345678",
    "payment_method": "EXTERNAL",
    "payment_status": "pending",
    "rounded": false,
    "original_amount": 200,
    "fees": 10,
    "created_at": "2024-01-30T09:34:46.477",
    "updated_at": "2024-01-30T09:34:47.834"
  }
}

Merchant must display the instructions provided in the response:

للدفع عن طريق فوري، يمكن استخدام كود الدفع المرجعي في الحاوية أدناه. اتبع الخطوات التالية لإتمام عملية الدفع باستخدام المحفظة الإلكترونية:

9874050123

1. اذهب إلى تطبيق المحفظة الإلكترونية الخاص بك.
2. اختر \"فوري باي\" من الخدمات المتاحة.
3. ادخل كود الدفع المرجعي الموضح أعلاه.
4. تأكد من صحة المعلومات وقم بالتأكيد لإتمام العملية.

بديلًا، يمكنك الدفع نقدًا في أي متجر تابع لفوري بلس.

The customer will use the voucher code using Fawry app to confirm the payment.