Back to top

Biller List API Staging v1.0

PayMaya’s Biller List API manages the exposure of billers to clients.

API Authentication

Biller List API require key-based authentication. APIs and features accessible to each API consumer are defined by the public and/or secret key that the API consumer will use. For each API call, the API consumer must pass an Authorization header (using Basic access authentication), with the API key encoded in Base64 MIME encoding.

Example: Given secret key sk-A9zFq1siKCRREsF2nKG3wj2tfEkYNPO1bMt1nOxip9o:

Authorization: Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==

Resource Group

Biller List with Categorization

API for retrieving the list of billers with categorization and their information.

List of Supported Categories
GET/categories{?fields}

Retrieve the list of Categories that are available to the client given their clientid. By default, returns all the urls for icons used in listing.

Example URI

GET /categories?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more category properties that the API response will include. The response will contain the properties name, slug and listUrl by default. Set this query to “all” to retrieve all category properties.

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "categories": [
    {
      "name": "Utilities",
      "slug": "utilities",
      "listUrl": {
        "ios": {
          "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
          "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
        },
        "android": {
          "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
          "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
          "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
        }
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "categories": {
      "type": "array",
      "description": "Array of categories available to the client."
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Invalid key!"
}

List of Supported Categories w/ DeviceType Query
GET/categories{?deviceType}{?fields}

Retrieve the list of Categories that are available to the client given their clientid. Returns the urls of the icon for the given device type.

Example URI

GET /categories?deviceType=ios?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
deviceType
string (optional) Example: ios

Specifies the OS of the device where the icons will be displayed

fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more category properties that the API response will include. The response will contain the properties name, slug and listUrl by default. Set this query to “all” to retrieve all category properties.

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "categories": [
    {
      "name": "Utilities",
      "slug": "utilities",
      "listUrl": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "categories": {
      "type": "array",
      "description": "Array of categories available to the client."
    }
  }
}

List of Supported Categories w/ DeviceResolution Query
GET/categories{?deviceResolution}{?fields}

Retrieve the list of Categories that are available to the client given their clientid. Returns the link of the specific device resolution given

Example URI

GET /categories?deviceResolution=hdpi?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
deviceResolution
string (optional) Example: hdpi

Specifies the resolution of the icon to be returned

fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more category properties that the API response will include. The response will contain the properties name, slug and listUrl by default. Set this query to “all” to retrieve all category properties.

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "categories": [
    {
      "name": "Utilities",
      "slug": "utilities",
      "listUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "categories": {
      "type": "array",
      "description": "Array of categories available to the client."
    }
  }
}

Get a Specific Category
GET/categories/{categorySlug}

Retrieve details of a specific category given its slug provided that the requested category is available to the client.

Example URI

GET /categories/utilities
URI Parameters
HideShow
categorySlug
string (required) Example: utilities

slug of the category

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "category": {
    "name": "Utilities",
    "slug": "utilities",
    "listUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
      }
    },
    "confirmationUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/3x/Confirmation-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/retina/Confirmation-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/xhdpi/Confirmation-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/mdpi/Confirmation-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png"
      }
    },
    "iconUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/3x/Dash-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/retina/Dash-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/xhdpi/Dash-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/mdpi/Dash-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
      }
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "category": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the category"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the category"
        },
        "listUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon urls for android per screen resolution"
            }
          },
          "description": "List of category's images to be displayed on initial screen"
        },
        "confirmationUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for android per screen resolution"
            }
          },
          "description": "List of category's images to be displayed upon confirmation of payment"
        },
        "iconUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon urls for android per screen resolution"
            }
          },
          "description": "List of category's images to be displayed while playing"
        }
      },
      "description": "Details of the category"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "90097fd6-b28a-4db9-b07a-53fa51767ce0",
    "message": "[2555] Category Slug Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/#reference/billers"
      }
    ]
  }
]

Get a Specific Category w/ DeviceType Query
GET/categories/{categorySlug}{?deviceType}

Retrieve details of a specific category given its slug provided that the requested category is available to the client.

Example URI

GET /categories/utilities?deviceType=android
URI Parameters
HideShow
categorySlug
string (required) Example: utilities

slug of the biller

deviceType
string (optional) Example: android

Specifies the OS of the device where the icons will be displayed

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "category": {
    "name": "Utilities",
    "slug": "utilities",
    "listUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
    },
    "confirmationUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/xhdpi/Confirmation-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/mdpi/Confirmation-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png"
    },
    "iconUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/xhdpi/Dash-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/mdpi/Dash-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "category": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the category"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the category"
        },
        "listUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of category's images to be displayed on initial screen"
        },
        "confirmationUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of category's images to be displayed upon confirmation of payment"
        },
        "iconUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of category's images to be displayed while playing"
        }
      },
      "description": "Details of the category"
    }
  }
}

Get a Specific Category w/ DeviceResolution Query
GET/categories/{categorySlug}{?deviceResolution}

Retrieve details of a specific category given its slug provided that the requested category is available to the client.

Example URI

GET /categories/utilities?deviceResolution=hdpi
URI Parameters
HideShow
categorySlug
string (required) Example: utilities

slug of the biller

deviceResolution
string (optional) Example: hdpi

Specifies the resolution of the icon to be returned

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "category": {
    "name": "Utilities",
    "slug": "utilities",
    "listUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png",
    "confirmationUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png",
    "iconUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "category": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the category"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the category"
        },
        "listUrl": {
          "type": "string",
          "description": "List url of category for specified device resolution"
        },
        "confirmationUrl": {
          "type": "string",
          "description": "Confirmation url of category for specified device resolution"
        },
        "iconUrl": {
          "type": "string",
          "description": "Icon url of category for specified device resolution"
        }
      },
      "description": "Details of the category"
    }
  }
}

List of Supported Billers in a Specific Category
GET/categories/{categorySlug}/billers{?fields}

Retrieve the list of Billers that are available to the client and the category given their clientid and category slug. By default, returns all the urls for icons used in listing.

Example URI

GET /categories/utilities/billers?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more biller properties that the API response will include. The response will contain the properties name, category, categorySlug, slug and listUrl by default. Set this query to “all” to retrieve all biller properties.

categorySlug
string (required) Example: utilities

slug of the category

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "billers": [
    {
      "name": "Cignal Mediascape",
      "slug": "CIGNAL",
      "category": "Utilities",
      "categorySlug": "utilities",
      "listUrl": {
        "ios": {
          "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
          "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
        },
        "android": {
          "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
          "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
          "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
        }
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billers": {
      "type": "array",
      "description": "Array of billers available to the client."
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "90097fd6-b28a-4db9-b07a-53fa51767ce0",
    "message": "[2555] Category Slug Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/#reference/billers"
      }
    ]
  }
]
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Invalid key!"
}

List of Supported Billers in a Specific Category w/ DeviceType Query
GET/categories/{categorySlug}/billers{?deviceType}{?fields}

Retrieve the list of Billers that are available to the client and the category given their clientid and category slug. Returns the urls of the icon for the given device type.

Example URI

GET /categories/utilities/billers?deviceType=ios?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
deviceType
string (optional) Example: ios

Specifies the OS of the device where the icons will be displayed

fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more biller properties that the API response will include. The response will contain the properties name, category, categorySlug, slug and listUrl by default. Set this query to “all” to retrieve all biller properties.

categorySlug
string (required) Example: utilities

slug of the category

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "billers": [
    {
      "name": "Cignal Mediascape",
      "slug": "CIGNAL",
      "category": "Utilities",
      "categorySlug": "utilities",
      "listUrl": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billers": {
      "type": "array",
      "description": "Array of billers available to the client."
    }
  }
}

List of Supported Billers in a Specific Category w/ DeviceResolution Query
GET/categories/{categorySlug}/billers{?deviceResolution}{?fields}

Retrieve the list of Billers that are available to the client and the category given their clientid and category slug. Returns the link of the specific device resolution given

Example URI

GET /categories/utilities/billers?deviceResolution=hdpi?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
deviceResolution
string (optional) Example: hdpi

Specifies the resolution of the icon to be returned

fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more biller properties that the API response will include. The response will contain the properties name, category, categorySlug, slug and listUrl by default. Set this query to “all” to retrieve all biller properties.

categorySlug
string (required) Example: utilities

slug of the category

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "billers": [
    {
      "name": "Cignal Mediascape",
      "slug": "CIGNAL",
      "category": "Utilities",
      "categorySlug": "utilities",
      "listUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billers": {
      "type": "array",
      "description": "Array of billers available to the client."
    }
  }
}

Get a Specific Biller in a Specific Category
GET/categories/{categorySlug}/billers/{slug}

Retrieve details of a specific biller given its slug provided that the requested biller is available to the client and the category.

Example URI

GET /categories/utilities/billers/CIGNAL
URI Parameters
HideShow
slug
string (required) Example: CIGNAL

slug of the biller

categorySlug
string (required) Example: utilities

slug of the category

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "biller": {
    "name": "Cignal Mediascape",
    "slug": "CIGNAL",
    "category": "Utilities",
    "categorySlug": "utilities",
    "otherFields": {
      "field": {
        "type": "textfield",
        "regex": "^[-a-zA-Z .]{1,100}$",
        "required": "true",
        "placeholder": "First Name",
        "defaultValue": "BAYAD"
      }
    },
    "listUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
      }
    },
    "confirmationUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/3x/Confirmation-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/retina/Confirmation-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/xhdpi/Confirmation-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/mdpi/Confirmation-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png"
      }
    },
    "iconUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/3x/Dash-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/retina/Dash-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/xhdpi/Dash-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/mdpi/Dash-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
      }
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the biller"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the biller"
        },
        "category": {
          "type": "string",
          "description": "Category of the biller"
        },
        "categorySlug": {
          "type": "string",
          "description": "Unique identifier of the biller's category"
        },
        "otherFields": {
          "type": "object",
          "properties": {
            "field": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "textfield",
                    "selectable",
                    "date",
                    "hidden"
                  ],
                  "description": "type of the field"
                },
                "regex": {
                  "type": "string",
                  "description": "indicates the regular expression where the field with type text field will be validated"
                },
                "required": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ],
                  "description": "indicates if the field is required or not"
                },
                "placeholder": {
                  "type": "string",
                  "description": "the name of the field to be displayed"
                },
                "defaultValue": {
                  "type": "string",
                  "description": "required only when field type is hidden, this is always the field's value"
                }
              },
              "description": "Field specific only for the biller"
            }
          },
          "description": "An object of fields which are required by each biller"
        },
        "listUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon urls for android per screen resolution"
            }
          },
          "description": "List of biller's images to be displayed on initial screen"
        },
        "confirmationUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for android per screen resolution"
            }
          },
          "description": "List of biller's images to be displayed upon confirmation of payment"
        },
        "iconUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon urls for android per screen resolution"
            }
          },
          "description": "List of biller's images to be displayed while playing"
        }
      },
      "description": "Details of the biller"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "90097fd6-b28a-4db9-b07a-53fa51767ce0",
    "message": "[2557] Biller Slug Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/#reference/billers"
      }
    ]
  }
]
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "90097fd6-b28a-4db9-b07a-53fa51767ce0",
    "message": "[2555] Category Slug Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/#reference/billers"
      }
    ]
  }
]

Get a Specific Biller in a Specific Category w/ DeviceType Query
GET/categories/{categorySlug}/billers/{slug}{?deviceType}

Retrieve details of a specific biller given its slug provided that the requested biller is available to the client and the category.

Example URI

GET /categories/utilities/billers/CIGNAL?deviceType=android
URI Parameters
HideShow
slug
string (required) Example: CIGNAL

slug of the biller

deviceType
string (optional) Example: android

Specifies the OS of the device where the icons will be displayed

categorySlug
string (required) Example: utilities

slug of the category

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "biller": {
    "name": "Cignal Mediascape",
    "slug": "CIGNAL",
    "category": "Utilities",
    "categorySlug": "utilities",
    "otherFields": {
      "field": {
        "type": "textfield",
        "regex": "^[-a-zA-Z .]{1,100}$",
        "required": "true",
        "placeholder": "First Name",
        "defaultValue": "BAYAD"
      }
    },
    "listUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
    },
    "confirmationUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/xhdpi/Confirmation-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/mdpi/Confirmation-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png"
    },
    "iconUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/xhdpi/Dash-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/mdpi/Dash-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the biller"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the biller"
        },
        "category": {
          "type": "string",
          "description": "Category of the biller"
        },
        "categorySlug": {
          "type": "string",
          "description": "Unique identifier of the biller's category"
        },
        "otherFields": {
          "type": "object",
          "properties": {
            "field": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "textfield",
                    "selectable",
                    "date",
                    "hidden"
                  ],
                  "description": "type of the field"
                },
                "regex": {
                  "type": "string",
                  "description": "indicates the regular expression where the field with type text field will be validated"
                },
                "required": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ],
                  "description": "indicates if the field is required or not"
                },
                "placeholder": {
                  "type": "string",
                  "description": "the name of the field to be displayed"
                },
                "defaultValue": {
                  "type": "string",
                  "description": "required only when field type is hidden, this is always the field's value"
                }
              },
              "description": "Field specific only for the biller"
            }
          },
          "description": "An object of fields which are required by each biller"
        },
        "listUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of biller's images to be displayed on initial screen"
        },
        "confirmationUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of biller's images to be displayed upon confirmation of payment"
        },
        "iconUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of biller's images to be displayed while playing"
        }
      },
      "description": "Details of the biller"
    }
  }
}

Get a Specific Biller in a Specific Category w/ DeviceResolution Query
GET/categories/{categorySlug}/billers/{slug}{?deviceResolution}

Retrieve details of a specific biller given its slug provided that the requested biller is available to the client and the category.

Example URI

GET /categories/utilities/billers/CIGNAL?deviceResolution=hdpi
URI Parameters
HideShow
slug
string (required) Example: CIGNAL

slug of the biller

deviceResolution
string (optional) Example: hdpi

Specifies the resolution of the icon to be returned

categorySlug
string (required) Example: utilities

slug of the category

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "biller": {
    "name": "Cignal Mediascape",
    "slug": "CIGNAL",
    "category": "Utilities",
    "categorySlug": "utilities",
    "otherFields": {
      "field": {
        "type": "textfield",
        "regex": "^[-a-zA-Z .]{1,100}$",
        "required": "true",
        "placeholder": "First Name",
        "defaultValue": "BAYAD"
      }
    },
    "listUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png",
    "confirmationUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png",
    "iconUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the biller"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the biller"
        },
        "category": {
          "type": "string",
          "description": "Category of the biller"
        },
        "categorySlug": {
          "type": "string",
          "description": "Unique identifier of the biller's category"
        },
        "otherFields": {
          "type": "object",
          "properties": {
            "field": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "textfield",
                    "selectable",
                    "date",
                    "hidden"
                  ],
                  "description": "type of the field"
                },
                "regex": {
                  "type": "string",
                  "description": "indicates the regular expression where the field with type text field will be validated"
                },
                "required": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ],
                  "description": "indicates if the field is required or not"
                },
                "placeholder": {
                  "type": "string",
                  "description": "the name of the field to be displayed"
                },
                "defaultValue": {
                  "type": "string",
                  "description": "required only when field type is hidden, this is always the field's value"
                }
              },
              "description": "Field specific only for the biller"
            }
          },
          "description": "An object of fields which are required by each biller"
        },
        "listUrl": {
          "type": "string",
          "description": "List url of biller for specified device resolution"
        },
        "confirmationUrl": {
          "type": "string",
          "description": "Confirmation url of biller for specified device resolution"
        },
        "iconUrl": {
          "type": "string",
          "description": "Icon url of biller for specified device resolution"
        }
      },
      "description": "Details of the biller"
    }
  }
}

Biller List for Backwards Compatibility

API for retrieving the list of billers and their information.

List of Supported Billers
GET/billers{?fields}

Retrieve the list of Billers that are available to the client given their clientid. By default, returns all the urls for icons used in listing.

Example URI

GET /billers?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more biller properties that the API response will include. The response will contain the properties name, category, slug and listUrl by default. Set this query to “all” to retrieve all biller properties.

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "billers": [
    {
      "name": "Cignal Mediascape",
      "slug": "CIGNAL",
      "category": "Utilities",
      "categorySlug": "utilities",
      "listUrl": {
        "ios": {
          "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
          "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
        },
        "android": {
          "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
          "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
          "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
        }
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billers": {
      "type": "array",
      "description": "Array of billers available to the client."
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Invalid key!"
}

List of Supported Billers w/ DeviceType Query
GET/billers{?deviceType}{?fields}

Retrieve the list of Billers that are available to the client given their clientid. Returns the urls of the icon for the given device type.

Example URI

GET /billers?deviceType=android?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
deviceType
string (optional) Example: android

Specifies the OS of the device where the icons will be displayed

fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more biller properties that the API response will include. The response will contain the properties name, category, slug and listUrl by default. Set this query to “all” to retrieve all biller properties.

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "billers": [
    {
      "name": "Cignal Mediascape",
      "slug": "CIGNAL",
      "category": "Utilities",
      "categorySlug": "utilities",
      "listUrl": {
        "ios": {
          "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
          "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
        },
        "android": {
          "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
          "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
          "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
        }
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billers": {
      "type": "array",
      "description": "Array of billers available to the client."
    }
  }
}

List of Supported Billers w/ DeviceResolution Query
GET/billers{?deviceResolution}{?fields}

Retrieve the list of Billers that are available to the client given their clientid. Returns the link of the specific device resolution given

Example URI

GET /billers?deviceResolution=hdpi?fields=iconUrl,confirmationUrl
URI Parameters
HideShow
deviceResolution
string (optional) Example: hdpi

Specifies the resolution of the icon to be returned

fields
string (optional) Example: iconUrl,confirmationUrl

Specifies a comma-separated list of one or more biller properties that the API response will include. The response will contain the properties name, category, slug and listUrl by default. Set this query to “all” to retrieve all biller properties.

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "billers": [
    {
      "name": "Cignal Mediascape",
      "slug": "CIGNAL",
      "category": "Utilities",
      "categorySlug": "utilities",
      "listUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billers": {
      "type": "array",
      "description": "Array of billers available to the client."
    }
  }
}

Get a Specific Biller
GET/billers/{slug}

Retrieve details of a specific biller given its slug provided that the requested biller is available to the client.

Example URI

GET /billers/CIGNAL
URI Parameters
HideShow
slug
string (required) Example: CIGNAL

slug of the biller

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "biller": {
    "name": "Cignal Mediascape",
    "slug": "CIGNAL",
    "category": "Utilities",
    "categorySlug": "utilities",
    "otherFields": {
      "field": {
        "type": "textfield",
        "regex": "^[-a-zA-Z .]{1,100}$",
        "required": "true",
        "placeholder": "First Name",
        "defaultValue": "BAYAD"
      }
    },
    "listUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
      }
    },
    "confirmationUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/3x/Confirmation-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/retina/Confirmation-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/xhdpi/Confirmation-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/mdpi/Confirmation-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png"
      }
    },
    "iconUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/3x/Dash-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/retina/Dash-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/xhdpi/Dash-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/mdpi/Dash-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
      }
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the biller"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the biller"
        },
        "category": {
          "type": "string",
          "description": "Category of the biller"
        },
        "categorySlug": {
          "type": "string",
          "description": "Unique identifier of the biller's category"
        },
        "otherFields": {
          "type": "object",
          "properties": {
            "field": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "textfield",
                    "selectable",
                    "date",
                    "hidden"
                  ],
                  "description": "type of the field"
                },
                "regex": {
                  "type": "string",
                  "description": "indicates the regular expression where the field with type text field will be validated"
                },
                "required": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ],
                  "description": "indicates if the field is required or not"
                },
                "placeholder": {
                  "type": "string",
                  "description": "the name of the field to be displayed"
                },
                "defaultValue": {
                  "type": "string",
                  "description": "required only when field type is hidden, this is always the field's value"
                }
              },
              "description": "Field specific only for the biller"
            }
          },
          "description": "An object of fields which are required by each biller"
        },
        "listUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon urls for android per screen resolution"
            }
          },
          "description": "List of biller's images to be displayed on initial screen"
        },
        "confirmationUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for android per screen resolution"
            }
          },
          "description": "List of biller's images to be displayed upon confirmation of payment"
        },
        "iconUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon urls for android per screen resolution"
            }
          },
          "description": "List of biller's images to be displayed while playing"
        }
      },
      "description": "Details of the biller"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "90097fd6-b28a-4db9-b07a-53fa51767ce0",
    "message": "[2557] Biller Slug Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/#reference/billers"
      }
    ]
  }
]

Get a Specific Biller w/ DeviceType Query
GET/billers/{slug}{?deviceType}

Retrieve details of a specific biller given its slug provided that the requested biller is available to the client.

Example URI

GET /billers/CIGNAL?deviceType=android
URI Parameters
HideShow
slug
string (required) Example: CIGNAL

slug of the biller

deviceType
string (optional) Example: android

Specifies the OS of the device where the icons will be displayed

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "biller": {
    "name": "Cignal Mediascape",
    "slug": "CIGNAL",
    "category": "Utilities",
    "categorySlug": "utilities",
    "otherFields": {
      "field": {
        "type": "textfield",
        "regex": "^[-a-zA-Z .]{1,100}$",
        "required": "true",
        "placeholder": "First Name",
        "defaultValue": "BAYAD"
      }
    },
    "listUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
    },
    "confirmationUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/xhdpi/Confirmation-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/mdpi/Confirmation-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png"
    },
    "iconUrl": {
      "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/xhdpi/Dash-Cignal.png",
      "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/mdpi/Dash-Cignal.png",
      "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the biller"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the biller"
        },
        "category": {
          "type": "string",
          "description": "Category of the biller"
        },
        "categorySlug": {
          "type": "string",
          "description": "Unique identifier of the biller's category"
        },
        "otherFields": {
          "type": "object",
          "properties": {
            "field": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "textfield",
                    "selectable",
                    "date",
                    "hidden"
                  ],
                  "description": "type of the field"
                },
                "regex": {
                  "type": "string",
                  "description": "indicates the regular expression where the field with type text field will be validated"
                },
                "required": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ],
                  "description": "indicates if the field is required or not"
                },
                "placeholder": {
                  "type": "string",
                  "description": "the name of the field to be displayed"
                },
                "defaultValue": {
                  "type": "string",
                  "description": "required only when field type is hidden, this is always the field's value"
                }
              },
              "description": "Field specific only for the biller"
            }
          },
          "description": "An object of fields which are required by each biller"
        },
        "listUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of biller's images to be displayed on initial screen"
        },
        "confirmationUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of biller's images to be displayed upon confirmation of payment"
        },
        "iconUrl": {
          "type": "object",
          "properties": {
            "xhdpi": {
              "type": "string"
            },
            "mdpi": {
              "type": "string"
            },
            "hdpi": {
              "type": "string"
            }
          },
          "description": "List of biller's images to be displayed while playing"
        }
      },
      "description": "Details of the biller"
    }
  }
}

Get a Specific Biller w/ DeviceResolution Query
GET/billers/{slug}{?deviceResolution}

Retrieve details of a specific biller given its slug provided that the requested biller is available to the client.

Example URI

GET /billers/CIGNAL?deviceResolution=hdpi
URI Parameters
HideShow
slug
string (required) Example: CIGNAL

slug of the biller

deviceResolution
string (optional) Example: hdpi

Specifies the resolution of the icon to be returned

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "biller": {
    "name": "Cignal Mediascape",
    "slug": "CIGNAL",
    "category": "Utilities",
    "categorySlug": "utilities",
    "otherFields": {
      "field": {
        "type": "textfield",
        "regex": "^[-a-zA-Z .]{1,100}$",
        "required": "true",
        "placeholder": "First Name",
        "defaultValue": "BAYAD"
      }
    },
    "listUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png",
    "confirmationUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png",
    "iconUrl": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the biller"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the biller"
        },
        "category": {
          "type": "string",
          "description": "Category of the biller"
        },
        "categorySlug": {
          "type": "string",
          "description": "Unique identifier of the biller's category"
        },
        "otherFields": {
          "type": "object",
          "properties": {
            "field": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "textfield",
                    "selectable",
                    "date",
                    "hidden"
                  ],
                  "description": "type of the field"
                },
                "regex": {
                  "type": "string",
                  "description": "indicates the regular expression where the field with type text field will be validated"
                },
                "required": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ],
                  "description": "indicates if the field is required or not"
                },
                "placeholder": {
                  "type": "string",
                  "description": "the name of the field to be displayed"
                },
                "defaultValue": {
                  "type": "string",
                  "description": "required only when field type is hidden, this is always the field's value"
                }
              },
              "description": "Field specific only for the biller"
            }
          },
          "description": "An object of fields which are required by each biller"
        },
        "listUrl": {
          "type": "string",
          "description": "List url of biller for specified device resolution"
        },
        "confirmationUrl": {
          "type": "string",
          "description": "Confirmation url of biller for specified device resolution"
        },
        "iconUrl": {
          "type": "string",
          "description": "Icon url of biller for specified device resolution"
        }
      },
      "description": "Details of the biller"
    }
  }
}

Biller Custom Fields

Type otherFields.<field>.type

Type specifies the expected format of the field. The different types available are:

  • textfield

  • selectable

  • amount

  • accountNumber

  • date

  • hidden

  • textview

Each type have different keys and validation, and will be further discussed on the next section.

Textfield

A freeform field which is validated by the regular expression present in otherFields.<field>.regex.

  • Sample Biller Field

    "FirstName": {
      "type": "textfield",
      "regex": "^[-a-zA-Z .]{1,100}$",
      "required": true,
      "placeholder": "First Name"
  }

  • Sample Field in BillsPay’s requestMetadata.customFields

    {
      "FirstName": "John Doe"
  }

Selectable

A dropdown wherein the valid values are the keys in otherFields.<field>.values.

  • Sample Biller Field

    "FormSeries": {
      "type": "selectable",
      "values": {
          "0600": "0600 Series",
          "1600": "1600 Series",
          "1700": "1700 Series",
          "1800": "1800 Series",
          "2000": "2000 Series",
          "2200": "2200 Series",
          "2500": "2500 Series"
      }
  }

  • Sample Field in BillsPay’s requestMetadata.customFields

    {
      "FormSeries": "1600"
  }

Amount

An Object with value and currency as fields. The value field should be numeric, and currency should be a valid 3 letter alpha currency code based on ISO 4217

  • otherFields.<field>.min - minimum value allowed

  • otherFields.<field>.max - maximum value allowed

If the minimum or maximum value is not set, then the field value won’t have a limit.

  • Sample Biller Field

    "AmountDue": {
      "type": "amount",
      "min": 100,
      "max": 3500
  }

  • Sample Field in BillsPay’s requestMetadata.customFields

    {
      "AmountDue": {
          "currency": "PHP",
          "value": 2750.50
      }
  }

AccountNumber

A special type of textfield which indicates the Account Number to be paid by the user. Same with textfield, validation will also be done using regular expression, but it will also be sent to the corresponding biller for checking if the account does exist.

  • Sample Biller Field

    "AccountReference": {
      "type": "accountNumber",
      "regex": "^\\d{9}$"
  }

  • Sample Field in BillsPay’s requestMetadata.customFields

    {
      "AccountReference": "123456789"
  }

Date

A field which should consist of month, day or year depending on the format specified on dateFormat field.

The format of dateFormat's value can be based on Java’s SimpleDateFormat.

  • Sample Biller Field

    "DueDate": {
      "type": "date",
      "dateFormat": "YYYY-MM"
  }

  • Sample Field in BillsPay’s requestMetadata.customFields

    {
      "DueDate": "2017-12"
  }

It is advised to only display the needed date field on the client’s user interface.

See table below for example:

dateFormat Shown Fields
YYYY-MM Year, Month
YYYY-MM-DD Year, Month, Date
MM/DD Month, Date

Textview

A constant text field used to display custom notes in the client’s user interface.

  • Sample Biller Field

    "note": {
      "type": "textview",
      "placeholder": "Note to be displayed in App"
  }

Required otherFields.<field>.required

Indicates if the field is expected to be present upon Create Request to BillsPay’s API. Values could either be true or false.

Visible otherFields.<field>.visible

Indicates if the field should be visible on the client’s user interface. Values could either be true or false.

Placeholder otherFields.<field>.placeholder

Indicates the display name of the field.

Condition otherFields.<field>.condition

An Object that if present, indicates that the field is required or visible depending on a certain condition.

condition.<field> - an object where the keys are the possible values of the specified field

condition.<field>.<key> - an object which consists of the following fields: required, visible. Depending on the type, it may also contain regex, values, dateFormat, and defaultValue.

  • Sample Biller Field

    "FormSeries": {
      "type": "selectable",
      "values": {
          "0600": "0600 Series",
          "1600": "1600 Series"
      },
      "placeholder": "Form Series",
      "required": true,
      "visible": true
  },
  "TaxForm": {
      "type": "selectable",
      "required": true,
      "visible": true,
      "placeholder": "Tax Form",
      "condition": {
          "FormSeries": {
              "0600": {
                  "required": true,
                  "visible": true,
                  "values": {
                      "0605": "0605"
                  }
              },
              "1600": {
                  "required": true,
                  "visible": true,
                  "values": {
                      "1600WP": "1600WP",
                      "1601C": "1601C",
                      "1601E": "1601E",
                      "1601F": "1601F",
                      "1602": "1602",
                      "1603": "1603",
                      "1606": "1606"
                  }
              }
          }
      }
  }

  • Sample Field in BillsPay’s requestMetadata.customFields

    {
      "FormSeries": "1600",
      "TaxForm": "1699WP"
  }

Generated by aglio on 03 Aug 2021