Agent API
BuzzPaid API for serving agent accounts
BuzzPaid is a digital money platform that allows people without bank accounts to perform a range of transactions from their mobile phone or the BuzzPaid website. One feature is the ability for customers to top up their BuzzPaid account by purchasing credit from an approved agent.
This document describes the RESTful API that is designed to be consumed by, for example, mobile applications to service agent accounts.
Overview
The API currently offers two endpoints to help service agent accounts. Agents can purchase prepaid credit and then sell it on to customers. The API provides an endpoint to show details of an agent's account and another to complete the sale transaction.
Account structure overview
BuzzPaid works on a framework of accounts. Transactions take place between one account and another. Successful transactions affect the balance of both accounts in the transaction.
Account format
Each account has data points that describe it. Here are the key fields that are relevant to agent accounts accessing the API:
| Field name | Data type | Description | Relationships |
|---|---|---|---|
| id | char(36) | UUID that uniquely identifies an account. Not generally for user consumption. | |
| account_number | char(10) | A unique randomly generated string. Is used as the publicly visible account reference. | |
| title | varchar(50) | The name of the account as chosen by the account holder. | |
| account_type_id | char(3) | A foreign key that determines which type of account this is. | Links to the account_types table. |
| currency_id | tinyint(3) | An id that determines the currency of this account. Account holders can (in most cases) transact cross currency, but funds held in an account are all single currency. Agents cannot operate cross currency. | Links the currencies table. |
| balance | decimal(10,2) | The current balance of this account held to two decimal places. Public accounts cannot have a negative balance, so transactions that would take them below zero will fail. | |
| latest_transaction_date | datetime | The date and time of the most recent transaction that affected this account. |
Account types
An account has a type, which defines what the account holder can and can't do. Some accounts are for internal use only. The publicly visible account types are:
| Type | Description |
|---|---|
| Personal | An account held by a consumer. |
| Corporate | An account held by a company that wants to allow its employees use the account as part of their work. |
| Merchant | A merchant account allows retailers and utility companies to receive payment for goods and services. |
| Agent | An agent pays in advance for some credit, which it then sells on to other customers. This enables customers to access credit quickly and easily. |
Users
Each account can have one or more users who are authorised to make transactions through the account. It is the user who logs in to BuzzPaid to make a transaction through the account; in other words, it is not the account that logs in. Each user has a username (normally an email address), password and PIN number. The password and PIN are one way encrypted when stored in the database.
Agent accounts
Agent accounts behave in a restricted manner. Agent account holders cannot access their account through the BuzzPaid website. They can only interact with their account through the mobile mobile application, which in turn communicates with the BuzzPaid API via http requests.
Key differences of agent accounts
- Agent accounts only have a single account user.
- The username of the user holding an agent account is a numeric only phone number (not an email address). The phone number must match the phone number of the device the mobile application is installed on.
- Agent account holders have no access to the BuzzPaid website.
- Agent accounts cannot make the full range of transactions. The only transaction they can initiate is the sale of prepaid credit.
- As all agent transactions are effected through the mobile app and that is installed by a BuzzPaid administrator, the agent user does not need to log in to the application to make a transaction, and the user does not need to enter his PIN number.
Agent account set up
To open an agent account, the agent must go to the BuzzPaid office in person. A BuzzPaid administrator will check their credentials and set up the account on their behalf through the BuzzPaid admin interface. Then the administrator installs the mobile app on the agent's phone and initiates it with the relevant data.
Agent account prepayment
An agent must buy some credit from the BuzzPaid office before it can be used. They have to visit the BuzzPaid office and pay for the credit, which a BuzzPaid adminsitrator will record in the BuzzPaid system via the BuzzPaid site. The agent account will then be in credit to that amount. hey must return to the BuzzPaid office periodically to top up their account.
Mobile application set up
The BuzzPaid adminsitrator will install the application on the agent's mobile device and initialise it with the following details of the agent account:
| Data | Description | Example |
|---|---|---|
| username | The username of the user who has access to this agent account. | 0123456789 |
| password | The password of the user who has access to this agent account. | password |
| id | The internal id of the agent account. | 52fe7d8a-838c-4a9f-af5e-54de505fbae2 |
| account_number | The publicly visible account reference. | 4DGPHJ4CWT |
| user_id | The id of the user who is permissioned to use the agent account. | 5822a87c-f1c8-4ab0-4978-5fec6e33d25e |
| currency_id | The id of the currency of the account. | 2 |
The agent account is then ready to use via the application.
Accessing the API
The API is an HTTP RESTful service that exposes endpoints for the application to consume. There are strict rules around how it can be accessed:
- Each request must pass user authentication. For any action, the request must include a key value pair set in the header for username and password (e.g. PHP_AUTH_USER and PHP_AUTH_PW)
- Any request has to be over HTTPS else it will be blackholed with a purposely obscure error message
Available endpoints
These are the current endpoints. The URLs are to the test site (as they are not currently in production). The production URLs will not have the 'test' prefix. Text in square brackets ([]) indicates a variable. The requests can be accessed with a .json or a .xml suffix, which will determine the format of the response (json or xml).
| Endpoint | Type | URL | Description |
|---|---|---|---|
| Agents view | GET | https://test.buzzpaid.com/agents/view/[account_number].json | Returns an array of data about the account that matches the [account_number] variable passed in as a URL parameter. The user (as identified by the authentication details) must have access to that account, else the request will fail. |
| Credits add | POST | https://test.buzzpaid.com/credits/add.json | Returns an array of data that describes the success or failure of the transaction request. The user (as identified by the authentication details) must have access to that account, else the request will fail. The request must contain all relevant data fields in the posted request, else the transaction will fail. |
Agents view
This endpoint allows the application to request details of the account installed on the agent's mobile device. It might typically be used to retrieve the current balance of the account.
To complete successfully, the agent view action:
- Must be a GET
- Must be over HTTPS
- Must pass user authentication
- Must have the account number of the agent in the url (e.g. https://test.buzzpaid.com/agents/view/ABCDEFGH.json)
- The logged in user must have access to the requested account
Possible responses
| Locked user: when the user account of the user calling the API is locked: | |
| Key | Value |
|---|---|
| result | false |
| code | locked-user |
| message | Your user account is locked. Please contact BuzzPaid support. |
| requestId | [UUID] |
| Access denied: when the user does not have access to the requested account number passed in the URL: | |
| Key | Value |
| result | false |
| code | access-denied |
| message | You do not have access to that account. |
| requestId | [UUID] |
| Agent not found: when an invalid account number is passed in the URL: | |
| Key | Value |
| result | false |
| code | agent-not-found |
| message | That account was not found. |
| requestId | [UUID] |
| Agent found: when the account is found: | |
| result | true |
| code | agent-found |
| message | An array of data describing the agent account (see below) |
| requestId | [UUID] |
A successful view request looks like this:
{
"response": {
"result": true,
"code": "agent-found",
"agent": {
"Account": {
"id": "52fe7d8a-838c-4a9f-af5e-54de505fbae2",
"account_number": "ABCDEFGH",
"title": "0123456789",
"balance": "8.00",
"latest_transaction_date": "2016-11-07 21:10:12"
},
"Currency": {
"title": "British Pounds",
"code": "GBP",
"id": "2"
},
"AccountStatus": {
"title": "Active",
"id": "a"
}
},
"requestId": "585458d7-c454-469a-8b81-041d505fbae2"
}
}
An unsuccessful view request looks like this:
{
"response": {
"result": false,
"code": "locked-user",
"message": "Your user account is locked. Please contact BuzzPaid support.",
"requestId": "585458d7-c454-469a-8b81-041d505fbae2"
}
}
Credits add
This endpoint requests the completion of a transaction where a customer is purchasing credit from an agent.
To complete successfully, the credits add action:
- Must be a POST
- Must be over HTTPS
- Must pass user authentication
- The logged in user must have access to the agent account contained in the request
- The agent account must have sufficient credit to complete the transaction
- Both the agent account and the purchasing customer account must both be active (i.e. not locked or dormant)
- Must have key value pairs in the header for:
- user_id: the id of the agent user
- account_number: the account number of the customer purchasing credit
- amount: a decimal (to 2 places) amount that equals the amount of credit the customer is buying
- account_id: the id of the agent's account
- currency_id: the currency_id of the agent's account
The currency of the customer's account must match the currency of the agent's account (which will also be the currency of the transaction). The currency of the entire transaction must all be the same else the transaction will fail.
Here is an example key/value pair set that forms a complete POST:
| Key | Value (example) | Notes |
|---|---|---|
| user_id | 5822a87c-f1c8-4ab0-4978-5fec6e33d25e | The id of the agent user |
| account_number | ABCDEFGH | The account number of the customer buying credit from an agent |
| amount | 100.00 | The amount credit the customer is buying |
| account_id | 52fe7d8a-838c-4a9f-af5e-54de505fbae2 | The id of the agent's account |
| currency_id | 2 | The currency of this transaction |
| requestId | 585458d7-c454-469a-8b81-041d505fbae2 | A UUID used for tracking and debugging API requests |
Possible responses
| Data validation failed: when the posted data is invalid in some way: | |
| Key | Value |
|---|---|
| result | false |
| code | data-validation-failed |
| message | The credit sale cannot complete as one or more fields are empty. |
| errors | An array of errors with key value pairs for each invalid field and their errors. |
| requestId | [UUID] |
| Transaction type not allowed: when the transaction request is in some way not permitted by the account (an unlikely scenario) | |
| Key | Value |
| result | false |
| code | transaction-type-not-allowed |
| message | This account type cannot make that transaction. |
| requestId | [UUID] |
| Inactive account: when the agent account is not active: | |
| Key | Value |
| result | false |
| code | inactive-account |
| message | That agent account is inactive. |
| requestId | [UUID] |
| Potential duplicate: if it appears that this is a duplicate of a very recent transaction (within the last 30 seconds) - designed to prevent accidental duplication: | |
| result | false |
| code | potential-duplicate |
| message | This is a potential duplicate of a very recent transaction. Please try again in 30 seconds. |
| requestId | [UUID] |
| Exceeds recent transaction limit: if completing the transaction would cause the customer account to exceed its transaction limits: | |
| result | false |
| code | exceeds-recent-transaction-limit |
| message | This amount ([amount]) cannot be accepted by the account you are sending it to [code: TL]. |
| requestId | [UUID] |
| Exceeds projected transaction limit: if completing the transaction would cause the customer account to exceed its maximum allowed balance: | |
| Key | Value |
| result | false |
| code | exceeds-projected-transaction-limit |
| message | This amount ([amount]) cannot be accepted by the account you are sending it to [code: MB]. |
| requestId | [UUID] |
| Illegal matching accounts: if the agent account is the same as the customer account: | |
| Key | Value |
| result | false |
| code | illegal-matching-accounts |
| message | You cannot complete a credit sale into same account. Please choose a different account. |
| requestId | [UUID] |
| Inactive counterparty (customer) account: if the customer account is inactive: | |
| Key | Value |
| result | false |
| code | inactive-counterparty-account |
| message | The customer account you want to sell credit to is inactive. |
| requestId | [UUID] |
| Invalid account user: if the agent user's access to this agent account is inactive: | |
| Key | Value |
| result | false |
| code | invalid-account-user |
| message | That user does not have access to that agent account. |
| requestId | [UUID] |
| Cross currency forbidden: if the transaction is cross currency: | |
| Key | Value |
| result | false |
| code | cross-currency-forbidden |
| message | Cross currency credit sales are not allowed. |
| requestId | [UUID] |
| Insufficient funds: if the agent account does not have sufficent funds to complete the transaction: | |
| Key | Value |
| result | false |
| code | insufficient-funds |
| message | Your account has insufficient funds to complete this transaction. |
| requestId | [UUID] |
| Technical error: if the transaction fails for a technical reason: | |
| Key | Value |
| result | false |
| code | technical-error |
| message | Failed to create transaction due to a technical error. |
| requestId | [UUID] |
| Success: if the transaction succeeds: | |
| Key | Value |
| result | true |
| message | The credit sale is complete. Please record these details for your records. |
| transaction_id | [transactionId] |
| requestId | [UUID] |
A successful view request looks like this:
{
"response": {
"result": true,
"message": "The credit sale is complete. Please record these details for your records.",
"transaction_id": "[transactionId]",
"requestId": "[UUID]"
}
}
