Skip to main content

Intro

The API allows the developer to acquire products for customers.

Performing product acquire

API permission
Performing acquire operation requires to have `ACQUIRE` permission. If `ACQUIRE` permission wasn't grant to you, please contact Qrios team.

Acquire product

Fetching available products

Before performing acquire operation, you must select the product and know the amount for the product.

Products in Qrios API are categorized into groups. There are two categories of product groups:

  • STATIC_PRODUCT_GROUP - products are known beforehand
  • BENEFICIARY_SPECIFIC_PRODUCT_GROUP - products specific for a given beneficiary. To get them you need to call GET /v1/acquire/procuctGroups/{groupId}?beneficiaryId=BENEFICIARY_ID_VALUE

Products can have three types of amount sources:

  • FIXED - the amount for the product is fixed and is displayed in the product definition
  • PROVIDED_BY_USER - the amount should be passed to the acquire request
  • BASED_ON_BENEFICIARY_ID - to know the amount restriction, you need to call /v1/acquire/amount
To list product groups, send request:
GET /v1/acquire/productGroups
Headers:
X-Client-Id: x97uJ23b
X-Client-Secret: [secret]
HTTP: 200 (OK)
[
  {
    "type": "STATIC_PRODUCT_GROUP",
    "groupId": "staticProductGroup",
    "groupName": "Static products",
    "products": [
      {
        "sku": "1001",
        "beneficiaryIdLabel": "Acquirer msisdn",
        "productDescription": "MTN Recharge",
        "amountSource": "PROVIDED_BY_USER",
        "tags": [
          "airtime",
          "operator_product"
        ]
      },
      {
        "sku": "7001",
        "beneficiaryIdLabel": "Acquirer msisdn",
        "productDescription": "GLO Youtube Plan 1.5GB",
        "amountSource": "FIXED",
        "amount": 50.00,
        "tags": [
          "data",
          "operator_product"
        ]
      }
    ]
  },
  {
    "type": "BENEFICIARY_SPECIFIC_PRODUCT_GROUP",
    "groupId": "dstv",
    "groupName": "DSTV payment",
    "beneficiaryIdLabel": "Decoder number",
    "tags": [
      "cable"
    ]
  },
  {
    "type": "BENEFICIARY_SPECIFIC_PRODUCT_GROUP",
    "groupId": "startimes",
    "groupName": "Startimes products",
    "beneficiaryIdLabel": "Cable number",
    "tags": [
      "cable"
    ]
  }
]

Fetching available products for beneficiary

This endpoint allows fetching products specific to beneficiaries for the BENEFICIARY_SPECIFIC_PRODUCT_GROUP product group type.

To list products available to beneficiary, send request:
GET /v1/acquire/productGroups/dstv?beneficiaryId=12345678
Headers:
X-Client-Id: x97uJ23b
X-Client-Secret: [secret]
HTTP: 200 (OK)
{
  "status": "SUCCESS",
  "products": [
    {
      "sku": "1000000001",
      "beneficiaryIdLabel": "DSTV Smart Card number",
      "productDescription": "DSTV bill payment",
      "amountSource": "BASED_ON_BENEFICIARY_ID",
      "tags": [
        "cable"
      ]
    }
  ]
}

When you have the SKU and the amountSource is BASED_ON_BENEFICIARY_ID. It means that you need to call /v1/acquire/amount to get the amount for bill payment.

Fetching amount

This endpoint allows getting the amount for products with amountSource BASED_ON_BENEFICIARY_ID.

To get amount for product, send request:
GET /v1/acquire/amount?sku=1000000001&beneficiaryId=12345678
Headers:
X-Client-Id: x97uJ23b
X-Client-Secret: [secret]
HTTP: 200 (OK)
{
  "status": "SUCCESS",
  "amount": {
    "value": 100,
    "restrictions": "EXACT"
  },
  "beneficiaryDetails": {
    "beneficiaryName": "John Doe"
  },
  "paymentDetails": {
    "productName": "DSTV bill payment"
  }
}

When you know the sku, amount, and beneficiaryId you are ready to call acquire request.

Acquire product

Depending on the product type and amount source, the request body may look like:

  • RECHARGE
{
  "operationId": "114400000775637359",
  "sku": "1001",
  "beneficiaryId": "2341234567890",
  "customerMsisdn": "2341234567890",
  "amount": 50
}
  • DATA (without amount)
{
  "operationId": "114400000775637359",
  "sku": "7001",
  "beneficiaryId": "2341234567890",
  "customerMsisdn": "2341234567890"
}
  • CABLE
{
  "operationId": "114400000775637359",
  "sku": "1000000001",
  "beneficiaryId": "12345678",
  "customerMsisdn": "2341234567890",
  "amount": 100
}
To acquire product, send request:
POST /v1/acquire/product
Headers:
X-Client-Id: x97uJ23b
X-Client-Secret: [secret]
Content-Type: application/json

{
  "operationId": "114400000775637359",
  "sku": "1000000001",
  "beneficiaryId": "12345678",
  "customerMsisdn": "2341234567890",
  "amount": 100
}
HTTP: 200 (OK)
{
  "status": "SUCCESS",
  "transactionId": "txId123",
  "reference": "refId123"
}

Acquire product (async)

You are allowed to perform the acquire operation asynchronously. Let's assume you have configured URL https://developer.example.com/callback as a main callback.

To acquire product (async mode), send request:
POST /v1/acquire/product/async
Headers:
X-Client-Id: x97uJ23b
X-Client-Secret: [secret]
Content-Type: application/json

{
  "operationId": "114400000775637359",
  "sku": "1000000001",
  "beneficiaryId": "12345678",
  "customerMsisdn": "2341234567890",
  "amount": 100
}
HTTP: 200 (OK)
{
  "status": "INITIATED",
}

When "status" from the response is "INITIATED", you will be notified about operation result via callback:

POST https://developer.example.com/callback
Headers:
Content-Type: application/json

{
  "clientId": "x97uJ23b",
  "operationId": "114400000775637359",
  "operation": "acquire",
  "status": {
    "result": "success"
  },
  "acquire": {
    "reference": "refId123",
    "transactionId": "txId123",
  }
}

Acquire status

This endpoint allows checking operation status. It may be useful when the acquire request has finished with the unknown result or has timed out.

To check operation status, send request:
GET /v1/acquire/status?operationId=114400000775637359
Headers:
X-Client-Id: x97uJ23b
X-Client-Secret: [secret]

HTTP: 200 (OK)
{
  "status": "SUCCESS",
  "transactionId": "txId123",
  "reference": "refId123"
}

Acquire mobile operator products

Fetching available operator products

To list all products, that you can acquire, send request:
GET /v1/acquire/products
Headers:
X-Client-Id: x97uJ23b
X-Client-Secret: [secret]
HTTP: 200 (OK)
[
    {
        "sku": "1001",
        "operator": "mtn",
        "amount": null,
        "description": "MTN Recharge"
    },
    {
        "sku": "7001",
        "operator": "glo",
        "amount": 12.00,
        "description": "Glo data bundle 1GB"
    }
]

As a response you should receive products list. Response contains product list, that you can acquire to customer.

Acquire a product to customer

If you want to acquire `N100` `MTN Recharge` for `2340123456789`, send request
POST /v1/acquire
Headers:
  X-Client-Id: x97uJ23b
  X-Client-Secret: [secret]
  Content-Type: application/json

{
  "operationId": "535bdec5-ea1c-4737-b9e2-04a9743d4227",
  "sku": "1001",
  "acquirerMsisdn": "2340123456789",
  "amount": 100
}
HTTP 202 Accepted
"The request has been accepted for processing, but the processing has not been completed."

operationId - unique operation identifier

sku - stock keeping unit is a distinct type of item for sale

acquirerMsisdn - customer's phone number

amount - product amount. Have to be provided, if amount isn't defined in a product.

Product MTN Recharge sku: 1001 request have to have defined amount, because recharge could be done do N200 as well as N500. For other hand Glo data bundle 1GB have constant price N12, so it amount: 12 have no sense in request.

POST /v1/acquire
Headers:
  X-Client-Id: x97uJ23b
  X-Client-Secret: [secret]
  Content-Type: application/json

{
  "operationId": "535bdec5-ea1c-4737-b9e2-04a9743d4227",
  "sku": "7001",
  "acquirerMsisdn": "2340123456789",
  "amount": null
}
HTTP 202 Accepted
"The request has been accepted for processing, but the processing has not been completed."

Acquire request have been accepted. Qrios API is going to proceed with your request, and deliver you result in callback asynchronously.

Checking status of acquire

If you want to manually check the status of the acquire operation, send request:
POST /v1/acquire/status
Headers:
  X-Client-Id: x97uJ23b
  X-Client-Secret: [secret]
  Content-Type: application/json

{
  "operationId": "535bdec5-ea1c-4737-b9e2-04a9743d4227",
}
HTTP 200 (OK)
"success"

Acquire API

Acquire operation API swagger can be found here