General API Definitions¶

The FloCash Payout API is based on the SOAP API as a standard method of communication between third-party clients and FloCash systems. To perform an action using the Payout API, you need to select a calling convention, send a request to its web service specifying a method and some arguments, and will receive a formatted response.

Only registered static public IP of third-party clients can call payout service.

All request formats, listed on the API index page, take a list of named parameters.

The REQUIRED parameter method is used to specify the calling method.

The REQUIRED parameter api_key is used to specify your API Key.

The optional parameter format is used to specify a response format.

The arguments, responses and error codes for each method are listed on the following section.

API Functions¶

Field Name	Description
Payout	Send payment instruction to transfer funds to any supported e-wallet and currency.
QueryTrans	Return transaction information by a transacti on ID.This is done by submitting transaction ID from a previous transaction.
getExchangeRate	Get real-time currency exchange rate for any supported currency.
validateUser	Verify if a receiver has a valid e-wallet in the receiving payment network

Data Formats¶

The table below lists types and format of data utilized by FloCash Payout API.

Table 6.2.1

Element name	Description	Data type	Note
PayoutRequest	Parameter containing all transaction informat ion for a payment transaction required by the Payout method	Complex	Data elements: Authentication, Transaction
Authentication	API login information	Complex	Data elements: apiUsername, apiPassword, control
Transaction	Information containing payment instruction including amount, sender and receiver informat ion	Complex	Data elements: requestID, custom, amount, currency, detail, sender, receiver
Response	Respond object containing transaction informa tion	TransactionQuery	Data elements: transactionID requestID, reqTime, amount,currency, detail, status
TransactionQuery	Parameter containing authentication and transaction data required by the QueryTrans method	Complex	Data elements: Authentication, Query
Query	Parameter specifying transaction data used to obtain detailed information about a previous transaction	Complex	Data elements: requestID,transactionID
apiUsername	Client’s login ID	String
apiPassword,	Client’s login password	String
control	Security token	String
requestID,	Value that identifies original request from client
transactionID	Unique Transaction ID	String
reqTime	Date of transaction YYYY-MM-DD HH:mm:SS	String
amount	All currency amount fields have the following structure:The amount must have two decimal pla ces.The decimal separator must be a period (“.”).You must not use any thousands separator	String
currency	Currency is listed in of the following formats USD (840) EUR (978)	String
detail	A note describing the transaction	String
status	Indicates transaction status.	String
ExceptionHandler	Response describing the error code and error message	Complex	Data elements: error, errorMessage
error	Error code	String
errorMessage	Error message	String
SenderInfo	Detailed information about sender	Complex	Data elements: email, country Identity, firstname, lastname Mobile, address, city postalCode
ReceiverInfo	Detailed information about receiver	Complex	Data elements: email, country,, firstName, lastName,mobile, address, city postalCode…
PayoutResponse	Response back from FloCash system to payment instruction operation (Payout)	Complex	Data elements: Response
QueryTransResponse	Response back from FloCash system to transact ion query operation (QueryTrans)

Payout Parameters¶

Table 6.3.1

Parameter	Type	Mandatory	Note
Authentication		Yes
apiUsername	String	Yes	Client’s login ID
apiPassword	String	Yes	Client’s login password
control	String	Yes	Security token. It is generated by 3 parts using SHA256 algorithms: apiUsername apiPassword Secret key (which was provided for each partner)
Transaction		Yes
requestID	String	Yes	Value that identifies original request from client
custom	String	Yes	If Transaction Type is CARD
type	String	Yes	CARD/BANK/MOBILE
amount	BigDecimal	Yes	All currency amount fields have the following structure: The amount must have two decimal places. The decimal separator must be a period (“.”). You must not use any thousands separator.
settlementAmount	BigDecimal client
settlementCurrency	String
fee	BigDecimal
sendFee	BigDecimal	Yes	Specifies the amount the remitter paid as Sending Fee
currency	String	Yes	Currency is listed in of the following formats: USD (840) EUR (978)
detail	String
Sender		Yes
email	String	Yes
street1	String	Yes
street2	String
city	String	Yes
postalCode	String	Yes
country	String	Yes
company	String
firstName	String	Yes
lastName	String	Yes
mobile	String	Yes
notes	String
Receiver		Yes
email	String		email format
street1	String	Yes
street2	String
city	String	Yes
postalCode	String	Yes
country	String
businessName	String
type	String	Yes	INDIVIDUAL/COMPANY
beneficiary	String	Yes
mobile	String	Yes	If Transaction Type is MOBILE
bankAccount	String	Yes	If Transaction Type is BANK
bankName	String	Yes
swiftcode	String	Yes
cardNo	String	Yes	If Transaction Type is CARD
notes	String

ValidateUser Parameters¶

Table 6.4.1

Parameter	Type	Mandatory	Note
Authentication		Yes
apiUsername	String		Client’s login ID
apiPassword	String	Yes	Client’s login password
control	String	Yes	Security token. It is generated by 3 parts using SHA256 algorithms: apiUsername, apiPassword Secret key (which was provided for each partner)
TypeValidateRequest		Yes
requestID	String		Value that identifies original request from client
email	String		email format
mobile	String	Yes	Digits
country	String	Yes

getRate Parameters¶

Table 6.2.1

Parameter	Type	Mandatory	Note
Authentication		Yes
apiUsername	String	Yes	Client’s login ID
apiPassword	String	Yes	Client’s login password
control	String	Yes	Security token. It is generated by 3 parts using SHA256 algorithms: apiUsername, apiPassword Secret key (which was provided for each partner)
TypeRateQuery		Yes
requestID	String	Complex	Value that identifies original request from client
source	String	Yes	from currency
destination	String		to currency
Authentication		Yes
apiUsername	String	Yes	Client’s login ID
apiPassword	String	Yes	Client’s login password
control	String	Yes	Security token. It is generated by 3 parts using SHA256 algorithms: apiUsername, apiPassword Secret key (which was provided for each partner)
Query		Yes
requestID	String	Yes	Value that identifies original request from client
transactionID	String	Yes	Unique Transaction ID

Operator Table¶

Table 6.2.1

Service name	Type	Operator Name	Note
airtel	string	Airtel	Available in multiple countries
mtn	String	MTN	Available in multiple countries
orange	String	Orange	Available in multiple countries
safaricom	String	Safaricom	Available in multiple countries
etisalat	String	Etisalat	Available in multiple countries
glo	String	Glo	Available in multiple countries
tigo	String	Tigo	Available in multiple countries
laCell	String	LaCell	Burundi
ecoCash	String	EcoNet	Zimbabwe
telecash	String	Telecell	Zimbabwe

Error Codes¶

#	Error Code	Descriptions
1	001	Invalid credentials
2	002	Access denied
3	003	Missing transaction info
4	004	Missing Currency
5	005	Invalid currency or not supported
6	006	Missing amount
7	007	Invalid amount
8	008	Invalid sender info:{fields}
9	009	Invalid recipient info:{fields}
10	010	Invalid request ID
11	011	Duplicate request ID
12	012	Invalid transaction ID
13	013	No transaction found.
14	014	You have exceeded your daily transaction volume limit. Please contact support to increase your limit.
15	015	You have exceeded your daily transaction limit. Please contact support to increase your limit.
16	016	You have exceeded your per transaction limit. Please contact support to increase your limit.
17	017	Invalid query value
18	018	Invalid source currency
19	019	Invalid Currency or not supported
20	020	Invalid Recipient country
21	021	Invalid custom value
22	022	Invalid recipient type
23	023	Recipient type must be: INDIVIDUAL or COMPANY
24	024	Not enough balance
25	025	Maximum balance limit reached
26	026	Sender email is invalid
27	027	Recipient email is invalid
28	028	Transaction type must be one of the followings: MOBILE,BANK,CARD.
29	029	Transaction type must be :{ MOBILE/BANK/CARD }
30	030	Missing transaction custom info.
31	031	Invalid Sender country.
32	032	Recipient mobile number is invalid format
33	033	Payment was declined. Please contact support team.
34	034	Missing country
35	035	Missing mobile
36	036	Invalid country code
37	037	Access denied. Please contact support.
38	038	Missing settlement amount
39	039	Invalid settlement amount
40	040	Missing fee amount
41	041	Invalid fee amount
42	042	Missing settlement currency
43	043	Invalid settlement currency
44	044	Missing currency destination
45	045	Invalid currency destination
46	046	Settlement amount is insufficient to cover payout instructions and associated fees.
47	047	Missing sending fee amount
48	048	Invalid sending fee amount
49	999	Internal Error: Server has encountered unexpected condition. Please contact support team.

Sample Code¶

 Download WSDL, using JAXWS tool to generate client code.
 This is sample client code to call the API

 package com.flocash.payout;

 import java.math.BigDecimal;

 import org.apache.commons.codec.digest.DigestUtils;

 import com.flocash.Authentication;
 import com.flocash.PayoutRequest;
 import com.flocash.ReceiverInfo;
 import com.flocash.SenderInfo;
 import com.flocash.Transaction;
 public class PayoutServiceCall {
    public final static String SECRET_KEY="XXXXXXXXXXXXXXXXXXXXXXXX";
    public static void main(String[] args) {
            PayoutAPIServiceImplService service= new PayoutAPIServiceImplService();
            try{
                    Authentication authen= new Authentication();
                    authen.setApiPassword("test");
                    authen.setApiUsername("test");

                    //build hash control code

                    StringBuilder sb= new StringBuilder();
                    sb.append(authen.getApiUsername()).append(":");
                    sb.append(authen.getApiPassword()).append(":").append(SECRET_KEY);
                    authen.setControl(DigestUtils.sha256Hex(sb.toString()));

                    // transaction info

                    Transaction transaction= new Transaction();

                    //sender info
                    SenderInfo senderInfo= new SenderInfo();
                    senderInfo.setCity("adsa");
                    senderInfo.setStreet1("dsada");
                    senderInfo.setCompany("dsada");
                    senderInfo.setEmail("phamthaithinh@flocash.com");
                    senderInfo.setFirstName("Thinh");
                    senderInfo.setLastName("Pham");
                    senderInfo.setPostalCode("10000");
                    senderInfo.setCountry("VN");
                    senderInfo.setMobile("3342343243434");
                    //recipientInfo
                    ReceiverInfo receiverInfo= new ReceiverInfo();
                    receiverInfo.setMobile("32432434343");
                    receiverInfo.setBeneficiary("Sirak");
                    receiverInfo.setCountry("GB");
                    receiverInfo.setStreet1("dsadsada");
                    receiverInfo.setEmail("sirak@flocash.com");
                    receiverInfo.setPostalCode("EDADS");
                    transaction.setReceiver(receiverInfo);
                    transaction.setSender(senderInfo);
                    transaction.setSettlementAmount(new BigDecimal(100));
                    transaction.setSettlementCurrency("840");
                    transaction.setFee(new BigDecimal(1.1));
                    transaction.setAmount(new BigDecimal(100));
                    transaction.setCurrency("840");
                    transaction.setType("MOBILE");
                    ServiceSoap soap= service.getPayoutAPIServiceImplPort();

                    //Payout request
                    PayoutRequest request= new PayoutRequest();
                    request.setAuthentication(authen);
                    request.setTransaction(transaction);
                    soap.payout(request);

    }catch(Fault  ex){
                    ex.printStackTrace();
                  }

           }

}