Intelworld IP2 Reference Documentation

Introduction

Use Intelworld's REST API to interact with the IP2 API.

Click here to learn more about REST

Get started

  1. Sign into the Business Console
  2. Click Manage - you will find the BaseUri, your subscriptionId , API Key and API Password
  3. Click Accounts - you will find account numbers associated with your account

Security

Check out how to secure your REST transaction here

Payments

GET paymentmethods

Returns list of payment methods supported by IP2 Payments API

Resource Url

[baseuri]/paymentMethods

Resource Information
Parameter Description
offset zero base index from which to begin retrieval
count number of records to retrive
Request body

None

Success response
[{"PaymentProviderId": "string",
"Name": "string",
"ShortDescription": "string",
"LongDescription": "string",
"Currencies": [
  {
    "CurrencyCode": "string",
    "SymbolThumbnailUri": "string",
    "Name": "string",
    "ShortDescription": "string",
    "LongDescription": "string"
  }
],
"Countries": [
  {
    "CountryCode": "string",
    "Name": "string",
    "FlagThumbnailUri": "string",
    "ShortDescription": "string",
    "LongDescription": "string"
  }
],
"Website": "string",
"ImageUri": "string",
"ThumbnailUri": "string"}]
Response Message Parameters
Parameter Description
PaymentProviderId Identifier of Payment Method
Name Name of payment method
ShortDescription Short description of payment method
LongDescription Long description of payment method
PaymentMethodId Id of the payment method which your recipient will use to transact with you. See list of payment Id's here
CurrencyCode Currency Supported by that payment method
CountryCode Country Supported by that payment method
Website Official website of that Payment method
ImageUri Uri to large image logo for that payment provider
ThumbnailUri Uri to thumbnail image logo for that payment provider

Commerce

GET products

Function

Get list of products

Uri

[baseuri]/products

METHOD

GET

Resource Information
Parameter Description
offset zero base index from which to begin retrieval
count number of records to retrive
Request body

None

Success response
[{
"ProductId": "string",
"Name": "string",
"ShortDescription": "string",
"LongDescription": "string",
"CurrencyCode": "string",
"CountryCode": "string",
"ImageUri": "string",
"ThumbnailUri": "string",
"Website": "string",
}]
Response Message Parameters
Parameter Description
ProductId Identifier of Product
Name Name of product
ShortDescription Short description of product
LongDescription Long description of product
CurrencyCode Currency Supported by that payment method
CountryCode Country Supported for that product
Website Official website of that product
ImageUri Uri to large image logo for the product
ThumbnailUri Uri to thumbnail image logo for the product

Accounts

GET accounts

Function

Get your acccount information

Uri

[baseuri]/accounts

METHOD

GET

URL Params
Parameter Description
subscriptionId Your subscriptionId
accountId Your accountId
Request body

None

Success response
 {
"CreatedOn": "string",
"ModifiedOn": "string",
"AccountId": "string",
"SubscriptionId": "string",
"AccountType": "string",
"CurrencyCode": "string",
"CountryCode": "string",
"AccountStatus": "string",
"Name": "string",
"ShortDescription": "string",
"LongDescription": "string",
"AlertLevel": "string",
"AlertChannel": "string",
"AlertEmailAddress": "string",
"AlertPhoneNumber": "string",
"MinimumTransactionAmount": 0,
"MaximumTransactionAmount": 0,
"TransactionPlan": "string",
"TransactionPlanTotalAmount": 0,
"MinimumBalance": 0,
"Balance": 0}
Response Message Parameters
Parameter Description
SubscriptionId Identifier of subscription associated with account
AccountId Identifier of accountId associated with account
Name Name associated with account
ShortDescription Short description of the account
LongDescription Long description of the account
MinimumTransactionAmount Minimum transaction amount for account
MaximumTransactionAmount Maximum transaction amount for bundle
TransactionPlan Transaction plan associated with account
TransactionPlanTotalAmount The total amount transaction plan can transact in one day
MinimumBalance Minimum balance for account
AlertLevel Alert level associated with account
AlertEmail Email address to send alerts for this account
AlertPhone Phone number to send alerts for this account
AlertLevel Alert level associated with account

GET accounts/balances

Function

Get your acccount balances

Uri

[baseuri]/accounts/balances

METHOD

GET

URL Params
Parameter Description
subscriptionId Your subscriptionId
accountId Your accountId
Request body

None

Success response
 {"0"}
Response Message Parameters
Parameter Description
Balance Returns your business account balance

Transactions

POST transactions/debits

Functionality

Debit your business account.

Scenarios

Use this command in the following scenarios

  1. When you want to top up funds onto your clients account. e.g. Debit your business account and topup your clients MTN Mobile Money account.
  2. When your reselling commerce products. e.g. Debit your business account and topup your clients airtel airtime account.

PS. To debit your account you need to have prefunded your acccount. You can do this in the business console by clicking on accounts, select the account you want to top up , click topup and follow instructions

Url

[baseuri]/transactions/debits

METHOD

POST

URL Params
Parameter Description
subscriptionId Your subscriptionId
accountId Your accountId
Request Body
[{"BatchId": "string",
"RequestId": "string",
"RequestReference": {},
"PaymentMethodId": "string",
"PaymentMethodReference": {},
"Metadata": {},
"ProductId": "string",
"ProductReference": {},
"Amount": 0,
"CurrencyCode": "string",
"CountryCode": "string",
"Memo": "string",
"ChannelId": "string",
"ChannelReference": {},
"CustomerId": "string"
}]
Request parameters
Parameter Mandatory Description
RequestId Yes A unique Id from your system
CustomerId No Unique Id of customer in your system
BatchId Yes Use if you want to batch requests together
RequestReference No JSON string of parameters associated with transaction e.g. for an ecommerce may be {"CartId": "123", "ItemId":"345345345"}. We post this data back to you on callback
PaymentMethodId Yes Id of the payment method which your recipient will use to transact with you. Use GET/PaymentMethods to see list of payment methods
PaymentMethodReference Yes JSON string of parameters associated with payment method e.g. mobile money may be {"MSISDN": "256776000000"
Amount Yes Amount that you would like to transact with your recipient
Memo Yes Short description (Maximum 500 characters) to describe the transaction
ChannelId Yes The channel that your using to initiate the request. See list of channels here
ChannelReference No JSON string of usefull information on the channel e.g. for android smartphone maybe {"DeviceId": "465465465465465"}
Success response
[{
"CreatedOn": "string",
"ModifiedOn": "string",
"AccountId": "string",
"SubscriptionId": "string",
"AccountType": "string",
"CurrencyCode": "string",
"CountryCode": "string",
"AccountStatus": "string",
"Name": "string",
"ShortDescription": "string",
"LongDescription": "string",
"AlertLevel": "string",
"AlertChannel": "string",
"AlertEmailAddress": "string",
"AlertPhoneNumber": "string",
"MinimumTransactionAmount": 0,
"MaximumTransactionAmount": 0,
"TransactionPlan": "string",
"TransactionPlanTotalAmount": 0,
"MinimumBalance": 0,
"Balance": 0}]

POST transactions/credits

Functionality

Credit your business account.

Scenarios

Use this command in the following scenarios

  1. When you want to collect funds from your client e.g. Your selling your good or service . We debit your clients account and credit your business account

PS. If you have a collection account we credit your IP2 Business Account , if you have a payment account we credit your merchant account with the payment provider

Url

[baseuri]/transactions/credits

METHOD

POST

URL Params
Parameter Description
subscriptionId Your subscriptionId
accountId Your accountId
Request Body
[{"BatchId": "string",
"RequestId": "string",
"RequestReference": {},
"PaymentMethodId": "string",
"PaymentMethodReference": {},
"Metadata": {},
"ProductId": "string",
"ProductReference": {},
"Amount": 0,
"CurrencyCode": "string",
"CountryCode": "string",
"Memo": "string",
"ChannelId": "string",
"ChannelReference": {},
"CustomerId": "string"
}]
Request parameters
Parameter Mandatory Description
RequestId Yes A unique Id from your system
CustomerId No Unique Id of customer in your system
BatchId Yes Use if you want to batch requests together
RequestReference No JSON string of parameters associated with transaction e.g. for an ecommerce may be {"CartId": "123", "ItemId":"345345345"}. We post this data back to you on callback
PaymentMethodId Yes Id of the payment method which your recipient will use to transact with you. Use GET/PaymentMethods to see list of payment methods
PaymentMethodReference Yes JSON string of parameters associated with payment method e.g. mobile money may be {"MSISDN": "256776000000"
Amount Yes Amount that you would like to transact with your recipient
Memo Yes Short description (Maximum 500 characters) to describe the transaction
ChannelId Yes The channel that your using to initiate the request. See list of channels here
ChannelReference No JSON string of usefull information on the channel e.g. for android smartphone maybe {"DeviceId": "465465465465465"}
Success response
{
"ResponseCode": "int",
"ResponseMessage": "string",
"Data": {}
}
Response Params
Parameter Description
ResponseCode ResponseCode for transaction. 0 for success
ResponseMessage ResponseMessage
Data Data associated with request

GET transactions

Function

Get list of your transactions

Uri

[baseuri]/transactions

METHOD

GET

URL Params
Parameter Description
subscriptionId Your subscriptionId
accountId Your accountId
ealierdate Date to start querying transactions for
laterdate Date to end querying transactions for
offset zero base index from which to begin retrieval
count number of records to retrive
Request body

None

Success response
 [
{
"TransactionId": "string",
"BatchId": "string",
"AccountId": "string",
"SubscriptionId": "string",
"RequestId": "string",
"ProductReference": "string",
"PaymentMethodReference": "string",
"RequestReference": "string",
"CurrencyCode": "string",
"CountryCode": "string",
"Amount": 0,
"PaymentMethodId": "string",
"ProductId": "string",
"ChannelId": "string",
"Memo": "string",
"TransactionType": "string",
"TransactionStatus": "string",
"StatusMessage": "string",
"Payment": {
  "PaymentId": "string",
  "PaymentStatus": "string",
  "PaymentStatusMessage": "string",
  "PaymentStatusCode": 0
},
"Order": {
  "OrderId": "string",
  "OrderStatus": "string",
  "OrderStatusCode": 0,
  "OrderStatusMessage": "string"
},
"CommitId": "string",
"CommitStatus": "string",
"CommitStatusMessage": "string",
"CommitStatusCode": 0,
"Fee": 0,
"Commission": 0,
"CustomerId": "string",
"CreatedOn": "string",
"ModifiedOn": "string"
}
]
Response Message Parameters
Parameter Description
SubscriptionId Your subscriptionId
AccountId Your accountId
TransactionId Identifier of transaction
RequestId Your request identifier of transaction
ProductReference JSON string of product that was ordered
PaymentMethodReferece JSON string of payment method parameters
RequestReference JSON string of request parameters
CurrencyCode CurrencyCode of transaction
CountryCode CountryCode of transaction
Amount Transaction amount
PaymentMethodId Identifier of payment method
ChannelId Identifier of channel used
Memo Short description of transaction purpose
TransactionType Debit or Credit
TransactionStatus TransactionStatus
StatusMessage Transaction Status Message
Payment Payment status and messages
Order Order status and messages
CommitId Id from your system to confirm you received transaction
CommitStatus Status of the commit
CommitStatusMessage Message from your system to indicate if transaction was commited
Fee Fees/Charges you incurred for the transaction
Commission Commission you earned for the transaction
CustomerId Your customerId
CreatedOn Date transaction was created
ModifiedOn Last date the transaction was modified

If you have questions about this documetation you can send us an email on developers@intelworld.co.ug or chat with us on skype (Skype names allan.rwakatungu and mubtx)