Table of Contents
1. Authentication (Post Method)
3. Check Balance (Post Method)
4. Search/Check Customer (Post Method)
5. Estimate Charges (Post Method)
6. Verify Access Pin (Post Method)
8. Confirm Transaction (Post Method)
9. Transaction History (Post Method)
10. Payment Request (Post Method)
11. Payment Request History (Post Method)
12. Cancel Payment Request (Post Method)
13. Make Authorized Transaction (Post Method)
14. Check Transaction Status (Post Method)
Introduction
Merchant Id: merchant_id
Description: Your merchant id will be provided by a TipMe administrator and is required for every API integration. Without this merchant ID, you will not be able to access TipMe API. Contact TipMe if you need help with how to obtain a merchant id.
Access Key Name: authorizekey
Description: Your merchant key will be provided by a TipMe administrator and will be used in each API.
Note : Authorize key is sent in the headers.
API URLs:
Description: This URL will be provided by a TipMe administrator. The Staging URL and the live URLs are different. All API connectivity and integration is executed in the Staging Environment and upon a successful test, your account will be, migrated to the Live Environment , and new credentials provided by a TipMe administrator. The staging and the live API key and Merchant ids will be different.
Caution: New API keys can be requested at anytime. TipMe strongly recommend that you set both your API key, and merchant id as variables which can be called into your application at anytime and in a case where new API keys are generated, replacing the variable with the new API key automatically redirects all variable calls made to the new key. While in the Staging Environment, TipMe will force you to validate this as a last step requirement before approving your account to be migrated into the live environment.
API Listings
1.
Authentication (Post Method)
Description: This API is used for Authenticating the business account details linked with a specific merchant id. It will return auth token. This token is used in every API call for validation. Store this token locally and send on every request. You can also regenerate this token by calling this API.
URL: {base_url}/Business_api/authenticate
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Auth token generated use this token on every request for validation.",
"auth_token": "YfRBcyh7013Xsoc3"
}
}
2.
Get Profile (Post Method)
Description: This API is used for calling the business profile details linked with specific merchant id.
URL: {base_url}/Business_api/get_profile
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication API)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Data Found.",
"detail": {
"business_id": "BID1000001",
"name": "Business Name",
"email": "business@xyz.com",
"fullname": "ABC",
"mobile": "1234567890",
"country": "Liberia",
"profile_pic": ""
}
}
}
3.
Check Balance (Post Method)
Description: This API is used for fetching the business account balance details linked with a specific merchant id.
URL: {base_url}/Business_api/check_balance
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Data Found.",
"wallet": [
{
"amount": "0.00",
"currency_code": "LRD",
"is_primary": "1",
"currency": "L$"
},
{
"amount": "0.00",
"currency_code": "USD",
"is_primary": "0",
"currency": "$"
}
]
}
}
4.
Search/Check Customer (Post Method)
Description: This API is used for searching a customer by CUSTOMER ID/BUSINESS ID which has been assigned to a registered customer in the TipMe system. It is helpful to non-smart users for making transactions and also used for validate customer account in TipMe if it exist or not.
URL: {base_url}/Business_api/search_customer
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication API)
3. customer_id(string) (Mandatory) (enter CID or BID)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Record found.",
"detail": {
"mobile": "1234567890",
"user_name": "AbC",
"customer_id": "CID100001",
"profile_pic": "",
"country_name": "Liberia",
"currency": "L$",
"business_id": "BID100001",
"wallets": [
{
"currency_code": "USD",
"is_primary": "1",
"currency": "$"
},
{
"currency_code": "LRD",
"is_primary": "0",
"currency": "L$"
}
]
}
}
}
Transaction Flow
5.
Estimate Charges (Post Method)
Description: This API is used to estimate the charges before executing a transaction. It is used for calculating transaction charges and validating transaction limits/wallet limits for the customer.
URL: {base_url}/Business_api/estimate_charges
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. customer_id(string) (Mandatory) (enter CID or BID)
4. amount(float) (Mandatory) (transfer amount)
5. currency_code (string) (Mandatory) - (Customer wallet currency code, fetched by the search customer API if you receive and if you send amount to customer then your wallet currency code gets this from the balance API.)
6. charges_by (string) (Mandatory) (who pays transaction charges must be Sender or Receiver)
7. transation_type(string) (Mandatory) (transaction type must be Send or Receive)
(most important value and this is used to define a transaction if it is executed by you or a customer. If you want to send money from your wallet to customer wallet then transaction_type must be Send and if you want to receive money from customer wallet to your account then transaction_type must be Receive)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "You are about to transfer L$ 10.00 and receiver will get L$ 10.00",
"detail": {
"amount": "L$ 10.00",
"admin_commission": "L$ 5.000000",
"conversion_charge": "0.00",
"currency": "L$",
"currency_code": "LRD",
"total_paid": "L$ 15.00",
"charges_by": "Sender",
"receiver_get": "L$ 10.00"
}
}
}
6.
Verify Access Pin (Post Method)
Description: This API is used to verify access PIN before a transaction is pre-authorized to take place and moved onto the next stage which is to get OTP. This API is called after Estimate Charges API. Parameters value must be the same as provided in estimate charge api. OTP is always sent on senders(who transfer amount) mobile number and email. If transaction type is “Send” than OTP will be sent to your (business account) number and if transaction type is “Receive” then OTP will be sent to the customer’s phone number on file.
URL: {base_url}/Business_api/verify_access_pin
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. customer_id(string) (Mandatory) (enter CID or BID)
4. amount(float) (Mandatory) (transfer amount)
5. currency_code (string) (Mandatory) -(Customer wallet currency code, fetched by the search customer API if you receive and if you send an amount to a customer then your wallet currency code is gotten from balance API.)
6. access_pin (integer) (Mandatory) – (Sender access pin 4 digits)
7. transation_type(string) (Mandatory) (transaction type must be Send or Receive)
(most important value this is used to define a transaction made by you or customer, if you are sending money from your wallet to a customer’s wallet then transaction_type must be Send and if you want to receive money from a customer’s wallet to your account then transaction_type must be Receive)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Access pin verified successfully. An OTP is sent for verification."
}
}
7.
Resend OTP (Post Method)
Description: This API is used to resend an OTP if OTP is not received. The account holder must have either email notification or SMS notification or both notification methods turned on their account to receive OTP. By default, SMS notification is automatically activated on every account for which the phone number was validated. You cannot turn both methods OFF. This API is called after verify access pin API. Parameters value must be same as provided in estimate charge API. OTP is always sent on senders(who transfer amount) mobile number and email. If transaction type is “Send” and OTP will be sent to your (business account) number and if transaction type is “Receive” then OTP will be sent to customer’s number.
URL: {base_url}/Business_api/resent_otp
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. customer_id(string) (Mandatory) (enter CID or BID)
4. amount(float) (Mandatory) (transfer amount)
5. currency_code (string) (Mandatory) - (Customer’s wallet currency code, fetched by the search customer API if you receive and if you send amount to customer then your wallet currency code is gotten from the balance API.)
7. transation_type(string) (Mandatory) (transaction type must be Send or Receive)
(most important value this is used to define a transaction made by you or customer, if you are sending money from your wallet to a customer’s wallet then transaction_type must be Send and if you want to receive money from a customer’s wallet to your account then transaction_type must be Receive)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "OTP resent to your registered mobile number XXXXXX1111"
}
}
8.
Confirm Transaction (Post Method)
Description: This API is used to confirm a transaction and OTP. it is called after getting OTP. Parameters value must be same as provided in estimate charge API.
URL: {base_url}/Business_api/confirm_transaction
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. customer_id(string) (Mandatory) (enter CID or BID)
4. otp (integer) (Mandatory) – (4 digits)
5. amount(float) (Mandatory) (transfer amount)
6. currency_code (string) (Mandatory) - (Customer wallet currency code, fetched by the search customer API if you receive and if you send an amount to the customer then your wallet currency code is gotten from balance API.)
7. ref_no (alphanumeric/string) (Optional)
8. charges_by (string) (Mandatory) (who pays transaction charges must be Sender or Receiver)
9. transation_type(string) (Mandatory) (transaction type must be Send or Receive)
(most important value this is used to define a transaction made by you or customer, if you are sending money from your wallet to a customer’s wallet then transaction_type must be Send and if you want to receive money from a customer’s wallet to your account then transaction_type must be Receive)
10. description(string) (Optional)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Payment completed successfully."
}
}
9.
Transaction History (Post Method)
Description: This API is used for listing all transactions and the list can be filtered out through multiple parameters.
URL: {base_url}/Business_api/transaction_history
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication API)
3. page(integer) (Mandatory) (It is a page no.)
4. limit(integer) (Optional) (limit of 10 per page is set as default)
5. keyword(string) (Optional) – (In keyword parameter you can filter by customer id or transaction id)
6. type(string) (Optional) (must be sender/receiver)
7. from_date (Optional) (Format: YYYY-MM-DD)
8. to_date (Optional) (Format: YYYY-MM-DD)
9. ref_no (Optional)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Data Found",
"list": [
{
"sender_id": "BID1000001",
"receiver_id": "CID1000002",
"description": "test",
"charges_by": "Sender",
"transaction_id": "TR10000000000",
"created": "2020-10-08 10:33:08",
"type": "sender",
"status": "Success",
"ref_no": "6564545645664",
"currency": "L$",
"total_amount": "10.00",
"admin_comission": 5,
"conversion_comission": "0.000000",
"total_paid": "15.00",
"full_name": "ABC",
"profile_pic": ""
}
]
}
}
10.
Payment Request (Post Method)
Description: This API is used for request payment to customer.
URL: {base_url}/Business_api/payment_request
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. receiver_id(string) (Mandatory) (enter CID)
5. amount(float) (Mandatory) (requested amount)
6. currency_code (string) (Mandatory) – (Currency code which amount was requested)
7. charges_by (string) (Mandatory) (who pays transaction charges must be Sender or Receiver)
9. description(string) (Optional)
10. ref_no (alphanumeric/string) (Optional)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"ref_no": "123456789",
"transaction_id": "TR1000000000",
"msg": "Your request for $ 50.00 has been successfully sent to ABC."
}
}
11.
Payment Request History (Post Method)
Description: This API is used for listing all payment requests and the list can be filtered out through multiple parameters.
URL: {base_url}/Business_api/payment_request_history
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. page(integer) (Mandatory) (It is a page no.)
4. limit(integer) (Optional) (limit of 10 per page as default)
5. keyword(string) (Optional) – (In keyword parameter you can filter by customer id or transaction id)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Data Found",
"list": [
{
"id": "70",
"sender_id": "BID1000001",
"receiver_id": "CID1000001",
"description": "",
"status": "Pending",
"transaction_id": "TR100000000",
"ref_no_id": "123456789",
"charges_by": "Sender",
"modified": "2020-10-08 12:44:25",
"created": "2020-10-08 12:44:25",
"full_name": "ABC",
"currency": "$",
"amount": "50.00",
"profile_pic": ""
}
]
}
}
12.
Cancel Payment Request (Post Method)
Description: This API is used for cancelling a payment request before it can be honoured
URL: {base_url}/Business_api/cancel_payment_request
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. request_id(integer) (Mandatory) (Get it from payment request history api)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Payment request Cancelled successfully."
}
}
13. Make Authorized Transaction (Post
Method)
Description: This API is used for confirming transaction OTP. This API require that “OTP Allow Access” function to be turned on, on the business account. For Using this api you not need verify pinc and resend otp api. The OTP key will be shared by TipMe admin.
URL: {base_url}/Business_api/make_authorized_transaction
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. customer_id(string) (Mandatory) (enter CID or BID)
4. otp (string) (Mandatory) (static key provided by Tipme admin)
5. amount(float) (Mandatory) (transfer amount)
6. currency_code (string) (Mandatory) - (Customer wallet currency code, fetched by the search customer API if you receive and if you send an amount to the customer then your wallet currency code is gotten from balance API.)
7. charges_by (string) (Mandatory) (who pays transaction charges must be Sender or Receiver)
8. transation_type(string) (Mandatory) (transaction type must be Send)
(most important value this is used to define a transaction made by you or customer, if you are sending money from your wallet to a customer’s wallet then transaction_type must be Send .
9. description(string) (Optional)
10. ref_no (alphanumeric/string) (Optional)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"transaction_id": "TR100000000000",
"msg": "Payment completed successfully."
}
}
14. Check Transaction Status (Post Method)
Description: This API is used for get transaction details/status using ref_no.
URL: {base_url}/Business_api/check_transaction_status
Content-Type: application/x-www-form-urlencoded
Parameters:
1. merchant_id(string) (Mandatory)
2. auth_token(string) (Mandatory) (provided in authentication api)
3. ref_no (alphanumeric/string) (Mandatory)
Response:
Content-Type: application/json
|
HTTP Response Code |
Meaning |
|
401 |
Unauthorized access |
|
500 |
Internal server error |
|
Status: 0 |
Fail |
|
Status: 1 |
Success |
Sample Response:
{
"data": {
"status": "1",
"msg": "Data Found",
"detail":
{
"sender_id": "BID1000001",
"receiver_id": "CID1000002",
"description": "test",
"charges_by": "Sender",
"transaction_id": "TR10000000000",
"created": "2020-10-08 10:33:08",
"type": "sender",
"status": "Success",
"ref_no": "6564545645664",
"currency": "L$",
"total_amount": "10.00",
"admin_comission": 5,
"conversion_comission": "0.000000",
"total_paid": "15.00",
"full_name": "ABC",
"profile_pic": ""
}
}
}
Sample Request for Php Curl Example:
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL =>{base_url}/Business_api/get_profile",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS =>
"merchant_id=111111111111111",
CURLOPT_HTTPHEADER => array(
"Content-Type: application/x-www-form-urlencoded",
"authorizekey:xxxxxxxxxxxxxxxxxxxxxxxx",
"cache-control: no-cache"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}