TransferTo Airtime API Document 2.8 · 8.0 Reports: Transaction ... , TransferTo currently links +4.5 billion mobile users across more than 400 mobile operators. ... Select Developer

TransferToInc.–Cross-BorderMobilePayments©Copyright2016–Confidential

AirtimeAPIDocument

Version2.8.4


AirtimeAPIDocumentVersionNo.2.8.3

RevisionHistoryVersion Date Name Description1.06.03 16thNov2012 LynnLannuzel no-cacheheaderforHTTPPostresponse

1.06.04 19thNov2012 LynnLannuzel 1.RetaileraccountwillnolongerreturnwalletbalanceiftheyaresharingMerchant'swallet.

2.WalletlimitwillbecheckedbeforeaTop-upismade

1.06.08 20thMar2013 LynnLannuzel 1.Addedreturn_timestampflagforTop-up

2.Addedreturn_versionflagforTop-up

3.Addedservice_feeflagforTop-up,msisdn_info,pricelist

1.06.08 4thApril2013 LynnLannuzel AddinstructionsforPLNoperator.

1.06.12 1stJuly2013 LynnLannuzel 1.Fixed<Fixedandmobile>tagsto<TransferTo>

2.Enhanceddescriptions

1.06.18 8thJuly2013 LynnLannuzel 1.transactionidremovediftrxrejectedduetowalletorlimitation

2.AccountLimitationerror_code{241,242,243,244,245,246}

3.SenderLimitationerror_code{251,252,253,254,255,256}

31stJuly2013 LynnLannuzel AddinstructionstoretrieveAPIToken1.06.19 9thOct2013 MickaelFrelicot AddDTHIndiaOperatorsto9.2

1.06.26 17thDec2013 LynnLannuzel Addedpromotion(return_promo)toTop-upandmsisdn_infometh-od

1.06.32 27thMar2014 LynnLannuzel AddedSimulation/ChangemethodtoTop-up

1.06.35 29thApr2014 MarieHuc Updateofchapter“Otherproducts”.

AddasectionforDTHCignalTVProducts

2.01 11thJul2014 MarieHuc UpdateofSMSManagement(4.1).

2.2 29thMar2016 JennahMakalai Template&graphicupdate

2.3 30thMar2016 LynnLannuzel Updatefinalshopurlandrollversionnumber

2.4 21stJun2016 FooGuoTing AddedasectionforPrepaiddatabundles-Telcel

2.5 17thAug2016 FooGuoTing UpdatedURLforoperators’logos

2.6 16thSep2016 FooGuoTing AddedasectionforViberCredits

2.7 4thOct2016 FooGuoTing Addedlistofoperatorsforprepaidbundles

2.7.1 10thNov2016 FooGuoTing AddedViberEURItalytothelistofViberoperators

2.7.2 16thNov2016 FooGuoTing AddedmoreoperatorstothelistofViberoperators

2.7.3 19thDec2016 FooGuoTing AddedmoreoperatorstothelistofViberoperators

2.7.4 16thJan2017 FooGuoTing 1.AddedViberUSDJapantothelistofViberoperators

2.Addedmoreoperatorstothelistofprepaidbundlesoperators



2.8 10thFeb2017 FooGuoTing UpdatednewAPIendpoint

Correctedthedestination_msisdnparameterforPLN

Addednewresponseparametersfortrans_info

AddedIndiaGiftVoucherssection

AddedmoreoperatorstothelistofViberoperators

2.8.1 2ndMar2017 FooGuoTing AddedmoreoperatorstothelistofGiftVouchersoperators

2.8.2 8thMar2017 FooGuoTing Addedmoreoperatorstothelistofprepaidbundlesoperators

2.8.3 10thNov2017 FooGuoTing Updateddevelopers’section

2.8.4 2ndMar2018 LynnLannuzel Added311and312toerrorcodetable



Confidentiality

Allinformationcontainedinthisdocumentshallbekeptinconfidence.Nopartofthisdocumentistobealteredor copiedwithout thewrittenagreementof TransferTo Ltd.Noneof this information shall bedivulgedtopersonsotherthantoauthorisedemployeesofTransferToGrouporanyofTransferToGroupsubsidiaries,andshallbeonaneedtoknowbasis.Releaseofthisdocumenttootherpartiesshallbetoindividualsoforganisations authorisedbyTransferToand in accordancewithexistingpolicy regardingrelease of company information and shall only bemade availablewhen an acceptableNDAhas beensignedwiththatparty.

Pleasecontacttosupport@transfer-to.comforyourqueriesondocumentationandproducts/servicesofTransferTo.



TableofContentsGlossary ....................................................................................................... 71.0 Company Profile ..................................................................................... 82.0 Getting Started: Account Set-Up and Management ............................................ 9

2.1 Retrieve your API Token ......................................................................... 92.2 How to Send Requests ........................................................................... 102.3 Authentication and Security .................................................................... 112.4 Timeout Parameter .............................................................................. 122.5 Account, Sub-Accounts .......................................................................... 122.6 Account balance: How does it work? .......................................................... 132.7 Get ready, test your account! ................................................................. 14

3.0 API Overview ........................................................................................ 154.0 Basics: Airtime Recharge Query .................................................................. 17

4.1 Introduction to Top-up End-To-End Flow ..................................................... 174.2 Get details on a MSISDN ......................................................................... 194.3 Reserve an ID ..................................................................................... 244.4 Conduct a Top-up ................................................................................ 26

4.4.1 PIN Less Versus PIN Based Operators .................................................... 294.4.2 PIN Less ...................................................................................... 304.4.3 PIN Based .................................................................................... 354.4.4 Check if a MSISDN is subjected to a promotion ........................................ 38

5.0 Advanced values across borders .................................................................. 405.1 Prepaid Electricity ............................................................................... 40

5.1.1 PLN Indonesia: PIN Based ................................................................. 405.2 International Calling Service – PINLESS/PINFREE ............................................ 42

5.2.1 DollarPhone PINLESS ....................................................................... 425.3 Prepaid bundles .................................................................................. 455.4 Credits ............................................................................................. 46

5.4.1 Viber Out Credits ........................................................................... 465.5 India Gift Vouchers .............................................................................. 47

6.0 Tests: Simulate Top-up and Error codes ........................................................ 496.1 Check account credentials ..................................................................... 496.2 Monitor connection to the API ................................................................. 50



6.3 Simulate a Top-up ............................................................................... 506.4 Simulate error codes ............................................................................ 51

7.0 Account: Balance, Offer and Pricelist Query ................................................... 527.1 Check account balance ......................................................................... 527.2 Get the list of countries offered to my account ............................................ 597.3 Get the list of operators for a given country ................................................ 617.4 Get the list of products for a given operator ................................................ 64

8.0 Reports: Transaction Information Query ........................................................ 678.1 Get information from a transaction ID ....................................................... 67

8.1.1 PIN Less ...................................................................................... 688.1.2 PIN Based .................................................................................... 72

8.2 Get the list of transactions performed during a given date range ....................... 748.3 Get a transaction ID from a given key ........................................................ 77

9.0 Standard API Errors ................................................................................. 7910.0 Annexes ............................................................................................ 84

10.1 Sample Code in JAVA for MD5 Generation ................................................. 8410.2 Sample Code in PHP .......................................................................... 8510.3 URL to retrieve operator logo images ...................................................... 8710.4 Web Developers Samples ..................................................................... 8810.5 Mobile Apps Developers Samples ........................................................... 90



Glossary

AcronymorTerm DefinitionDTH Direct-To-Home

MSISDN MobileSubscriberIntegratedServicesDigitalNetwork-Number

PLN PerusahaanListrikNegara,English:'StateElectricityCompany'



1.0 CompanyProfileTransferTohelpsbusinessesofferairtimetop-ups,goodsandservices,andmobilemoneyaroundtheworldinrealtime.OurglobalairtimeandmobilemoneyHubprovidesanessentialcombinationofservicesandtechnologytomobiletelecommunicationcompaniesandfinancialinstitutionsincludingMTN,Singtel,Orange,WesternUnion,PayPal,andXoom.

Thousandsofcompaniesinover100countriesdependonTransferTotoprovidemobilefinancialtransactionsfortheircustomerswithouttheneedforabankaccount.TransferTo’sclientsarecompanieswhoseconsumerbaseconsistslargelyofpeopleconnectingwithfamilyandfriendsbackhome.Foundedin2005,TransferTocurrentlylinks+4.5billionmobileusersacrossmorethan400mobileoperators.



2.0 GettingStarted:AccountSet-UpandManagementThisAPIenablesdeveloperstointegrateTransferToTop-upserviceintotheirsystem.Ifyouarebuildingapplicationthatleveragesinternationalrechargeservices,thenthisistheAPIforyou.

Beforestarted,youmaywanttoexplorewhatdevelopershavedonebyintegratingthisAPI.Then,youshouldhavea lookat theURL listed inAnnexes (WebandMobileAppsDevelopersSamples,chapters10.4and10.5).

Thissectionintroducesthefollowingbestpracticesrelatedtoaccountset-upandmanagement:

• Retrieveyouraccountcredentials• Sendarequest(HTTPS)• EstablishaconnectiontotheAPI• GenerateatemporaryanduniquekeytoquerytheAPI• Consultandcredityouraccountbalance• Testyouraccount

2.1 RetrieveyourAPIToken

Once you have received your account credentials (login, password) to access the TransferTo webinterface,youmustloginandretrieveyourAPItokentobeusedwiththeTransferToAPI.

Toactivateaccess toyourAPIaccount,enableTwoFactorAuthentication (2FA).GoogleAuthenticatorapp is available on iTunes and Google Play. We strongly recommend you the use of the GoogleAuthenticatorappoverSMSAuthenticationasit isnottimeornetwork-dependent.IfyoudonothaveaccesstotheGoogleAuthenticatorapp,selectSMSToken.

Tosignupto2FA

1. Logintohttp://shop.transferto.com/.2. SelectDeveloperfromthetopmenu,andclickClickHeretoenable2FA.3. SelectGoogleAuthenticatorandclickSave.4. InGoogleAuthenticatorapp,scanthedisplayedbarcodeordirectkey-inthedisplayedcode.

Youareregistered.

Then,toretrieveyourAPItoken

1. SelectDeveloperfromthebottommenu.2. Enterthe6digitscodedisplayedonyourdevice’sGoogleAuthenticator.3. ClickonSubmitbutton.

YourAPItokenisdisplayed.

ClickonREGENERATEandSaveifyouneedtoresetit.



2.2 HowtoSendRequests

TransferToplatformisreachableviaHTTPSURL.

Therearecurrently3waysormethodstosendarequesttotheAPI:

• XMLformat(POSTmethod)• Plaintext(POSTmethod)• Plaintext(GETmethod)

TheplatformwillsendaresponseformattedtoXMLifXMLformatwasusedintherequest.

PlainTextPOST/GETRequestsYoumustprovideparametersusingtheHTTPSPOSTorGETmethods(botharevalidandrecognizedbythe system).WhileGETmethod is good forwriting test requests quickly,we recommend using POSTmethodforproductionasthereisnolengthlimitationandissafer.

TheURLtoreachtheplatformishttps://airtime.transferto.com/cgi-bin/shop/topup

AGETrequestwilllooklikethisone:

https://airtime.transferto.com/cgi-bin/shop/topup?login=login&key=key&md5=md5&action=ping

WiththefollowingparameterspassedintheURL:

• login• key• md5• action(hereping)

ForaPOSTrequest,theparametersaresentintherequestbody.

IfyousendtheparametersusingthePOSTmethodortheGETmethod,theTransferToAPIsendsbacka“text/plain”documentwithhuman readable information formatted in the following format (each lineendswith‘\r\n’):

value1=result1value2=result2…

XMLPOSTRequestAsdiscussedabove,youcanalsoreachtheplatformusingXML.

Whensendingarequest,formatcontentinXMLbeforecreatingtheURLrequest.

Note:Setthecontenttypeto“text/xml.”

TheresponsewillbeinXML.Allfieldnamesthatyouusedtocreatetherequestandreceivedinthere-sponseremainthesameasthoseusedin“text/plain”format.



2.3 AuthenticationandSecurity

InadditiontoHTTPS,anIPSECVPNcanbeestablisheduponrequest.

IntheXMLmessageitselfbeingtransmittedoverHTTPS,3parametersarerelatedtoauthentication:log-in,key,MD5.

Parameter Type Descriptionlogin AlphanumericString AccountloginnameprovidedbyTransferTo.

key Integer Keygeneratedbytheclient.Thetransactionisrejectedifthekeyhasbeenused.

md5 AlphanumericString MD5sumofthehexencodedconcatenationoflogin,token,andkey.

Table1–Authenticationparameters

Foreachrequest,generateakey,whichisauniqueinteger.Generateandmanagethiskeyonyourside.Togeneratethiskey,youneedtouseyourAPItoken(alphanumericstringretrievefromthewebinter-faceasdescribedinchapter2.1).

Thefollowingisanexampleofagoodkey.

• Useauniqueserver:atimestampwithmilliseconds.• Usemultipleservers.

- Useacommonsequenceshared throughadatabase toensure thatall the serversaresynchronized.

- Setup severalaccounts through theTransfer-Toweb interface tohavedistinct se-quences(oneperserverforinstance).

Note: As of 31st July 2013 (API version1.06.18), access to theAPI is fully independent fromyour ac-count'scredentials.Aseparate tokenmustbeactivated toconnect to theTransferToAPI.Forexistinguserspriorto31stJuly2013,yourtokenisthesameasyouraccount'spassword.

Example

Theloginandtokenusedbelowareforthisexampleonly.Youneedtouseyourownloginandtoken.

• login:client• token:pass99• key:1to5

CalculationoftheMD5hash:

• md5=md5_hex(login.token.key)



Results

key=1,md5=2f922ef79253f93d0fc05d0ac0b0d100key=2,md5=43dd325a272140a9f47a3be015eb8129key=3,md5=cc98cf7d902047101be5635f6af3877ekey=4,md5=b4a9d3a95ac0efb73d840bd0dbbe1d1ckey=5,md5=a43cff6e5d057f84b1ae99e64245bff8

Asyoucanseeinthesesamples,thecalculatedkeyisdistinctforeachtransaction.

2.4 TimeoutParameter

Morethan99.5%ofthetransactionsarecurrentlyprocessedwithinafewseconds.

However, itmayhappeninsomerarecasesthatatransactiontakes longertobeprocessedbythere-ceivingoperatorduetocongestedsystemontheirendforinstance.

TransferToguaranteesthattransactionsnotprocessedwithin600secondswillnotbecharged,whateverthefinalstatusofthetransaction(successfulornot).Inaddition,TransferToisoperatingarealtimesys-tem;therefore,thestatusreturnedintheTop-upresponseisfinalandwillnotchange.

To ensure that your system captures successfully the status of all transactions especially the longestones,itisadvisedtoeithersetupahightimeoutvalueof600secondstobeonthesafeside(TCPcon-nectioncouldpotentiallybeopenedforalongtimeinthiscase)ortosetupamechanismtocheckonthestatus(todoso,youcancallthetrans_infomethodtoretrievethefinalstatusofatransaction).

Incaseoftimeout,bothmethodsreserve_idandget_id_from_keyoftheAPIcouldbeusefultoidentifytheIDofthetransaction(werecommendtoeithersendareserve_idrequestandtousetheIDreturnedintheresponseinthesubsequenttop-uprequestsothatyouknowinadvancetheIDofthetransaction).

2.5 Account,Sub-Accounts

TransferTocreatesanaccount,andyoucanretrieveyourtokenthroughtheportalwiththeloginnameprovided.Thisaccountstandsforyourmasteraccount.

Ifyou’relookingtocreatesub-accounts,thisispossiblethankstoTransferTowebinterface:

Tocreateasub-account

1. Logintohttp://shop.transferto.com/.2. AcceptTermsandConditions.3. ClickonManageUsersbuttonandthenon+AddaNewUser4. Fill out the form (define login/password, contact information, etc.). For balance settings,

pleaserefertosection2.6hereafter.

Yoursub-accountiscreated.Yournewsub-accountuserwillreceiveanemailinvitation.



2.6 Accountbalance:Howdoesitwork?

MasteraccountTransferTosystemworksonaprepaidbasis.Eachnewaccountisinitializedwithaminimumamountintheirbalanceallowingtoperformthebasictests.Checkyourbalancebyeitherconnecttothewebinter-face(seehereafter)orusetheAPImethoddescribedinchapter7.1.

Toconsultyourbalanceandcredityouraccount

1. Logintohttp://shop.transferto.com/.2. Yourbalanceisdisplayedonthetopleftcorner.3. SelectAddCreditfromthetopmenu(nexttoyourbalance).4. Followtheinstructionstocredityouraccountbalance.

ThemainpaymentmethodsupportedbyTransferToplatformisthebanktransfer.Detailsonbankac-countcanbefinddirectlyontheweb interface.Moreover,otherpaymentsmethodsareprovidedde-pendingonyourlocation.

SubaccountsThereare3thingstoknowforsub-accountbalancemanagement:

1. Sub-accountbalancecanbesharedwithmaster(defaultsetting)

This is defined at sub-account creation. If shared, each transaction will imply a debit frommasteraccountbalance.Else,onlysub-accountbalancewillbeimpacted.

2. Adailylimitcanbefixedonsub-accountbalance

Todefineadailylimit

a. Logintoyourmasteraccountonhttp://shop.transferto.com/.b. ClickonManageUsersbuttonandsearchforyoursub-accountloginnamec. DefinethelimitationinDailyLimitcolumn

Note:thesub-account’sbalanceisautomaticallyresettothedailylimitamounteverydayat01hGMT.

3. Sub-accountbalanceiscreditedfromMasterTocredityoursub-accountbalancea. Logintoyourmasteraccountonhttp://shop.transferto.com/.b. ClickonManageUsersbuttonandsearchforyoursub-accountloginnamec. Definetheamount inManageFundscolumnandclickAdd.Thisamountwillbedebited

fromyourMasteraccountbalance.

To check yourmaster account balance, youmust send the requestwith the login name provided byTransferTo.

To check your sub-account balance, youmust send the request with the login name defined at sub-accountcreation.

Pleaserefertosection7.1toseemoredetailsonhowtocheckaccountbalance.



2.7 Getready,testyouraccount!

TheURLtoreachTransferToTop-upAPIis:https://airtime.transferto.com/cgi-bin/shop/topup

Beforestarting,checkyouraccountcredentialsbyusingthepingmethod.

Then,trytosimulateaTop-up(methodsimulation)andalsothemostcommonerrorcodesreturnedbyTransferTosysteminthetopupmethodresponse.

Pleaserefertosection0formoredetails.



3.0 APIOverviewThis API enables developers to access some of the core primitives of TransferTo platform includingmsisdn_info, reserve_id and topup. In addition, this API also offers several methods identified by aspecificvalueoftheparameter“action”.

BasicsAirtimeRecharge

Querymsisdn_inforeserve_id

topup

AccountBalance,OfferandPricelistQuerycheck_walletpricelist

TestsSimulateTop-upandErrorCodes

pingsimulation

ReportsTransaction

InformationQuerytrans_infotrans_list

get_id_from_key

AdvancedvaluesPLNandDTHRechargeQuery



Basics

Action Descriptionmsisdn_info ReturnsrelevantinformationonaMSISDN(operator,country…)aswellasthe

listofproductsconfiguredforyouraccountandthedestinationoperatorlinkedtothatMSISDN.AllowstocheckifaMSISDNissubjectedtoapromo-tion.

reserve_id ReturnsatransactionIDreservedinthesystemtobeusedduringnexttopuporsimulationquery.Thisway,yoursystemhastheIDofthetransactionbe-foresendingtherequesttoTransferTo.Otherwise,itwillappearonlyintheresponse.

topup AllowstoconductaTop-up.Returnstransactiondetailsbasedonproducttype(PIN-LessorPIN-Based):transactionidandstatus,errorcode,pininformation,localamountreceived,etc.

Account

Action Descriptioncheck_wallet Returnsyouraccountbalance.

Donotusethismethodmorethan24timesperday.

pricelist Returnsinformationconfiguredinyouraccountsuchascountieslist,opera-torslist,orproductslistandprices(wholesaleandretail).

Tests

Action Descriptionping Allowstocheckaccountcredentials.

simulation ThismethodisusedtosimulateaTop-up.Ittakesthesameargumentsastopupaction.ItdoesnotperformarealTop-uptothedestinationnumber.

Reports

Action Descriptiontrans_info ReturnsallavailableinformationonaspecifictransactionID.

trans_list Returnsthelistoftransactionsperformedduringagivendaterange.

get_id_from_key ReturnstheIDofatransactionpreviouslyperformedbasedonthekeyusedintherequestatthattime.



4.0 Basics:AirtimeRechargeQuery

ThissectionintroducesthedifferentstepstotheTop-upprocessflow:

• RetrieveinformationonaMSISDN• ReserveanIDinthesystem• Sendanairtimerecharge

4.1 IntroductiontoTop-upEnd-To-EndFlow

Using“msisdn_info”,“reserve_id”and“topup”MethodsThefollowingprocessdescribesatypicaltransactionflowbasedonthemainmethodsprovidedbytheAPI:

Figure1–Top-upProcessFlow



SMSManagementBydefault,anSMSnotificationissenttotherecipientaftereverysuccessfulTop-up.ThefollowingisthedefaultSMSwhichistranslatedintolocallanguagesformostofrecipientcountries:

Congratulations!You'vereceivedAMOUNT_CURRENCYfromSENDER.Thankyouforus-ingTransferTo.FREE_TEXT.

• AMOUNT CURRENCY is the amount that has

beensentwiththecurrency.• SENDERcanbeanameoraphonenumber.• FREE_TEXT is the contentof the fieldnamed

“sms”ofthetopupmethod.

Example:

ThedefaultoriginatingaddressfortheSMSis“8888”.



4.2 GetdetailsonaMSISDN

Purpose:Checkphonenumberformat;Getoperatorandavailabledenominations;etc.

Figure2–“msisdn_infoMethodIllustration”

Method msisdn_info

ReturnsrelevantinformationonaMSISDN(operator,country…)aswellasthelistofproductsconfiguredforyouraccountandthedestinationoperatorlinkedtothatMSISDN.AllowstocheckifaMSISDNissub-jectedtoapromotion.

Request

Answer



RequestParameters

Name Type Required(Yes/No) Description

login AlphanumericString

Y AccountloginnameprovidedbyTransferTo.

key Integer Y Keygeneratedbytheclient.Thetransactionisrejectedifthekeyhasbeenused.

md5 AlphanumericString

Y MD5sumofthehexencodedconcatenationoflogin,token,andkey.

action AlphanumericString

Y Mustbesetto“msisdn_info”

destination_msisdn NumericString Y DestinationMSISDN(usuallyrecipientphonenumber).Thisisthedestinationphonenumberthatwillbecreditedwiththeamounttransferred.Formatissimilarto“msisdn”andrestrictedtointernationalphonenumberonly.

delivered_amount_info AlphanumericString

(lessthan2chars)

N Settingthisto“1”willreturnthefieldslo-cal_info_amount_list,local_info_currencyandlocal_info_value_listintheAPIresponse.Blankor“no”ifyoudonotwantthisre-turned.

return_service_fee Numeric N Settingthisto“1”willreturnthefieldser-vice_fee_listintheAPIresponse.Blankor“0”ifyoudonotwantitreturned.

operatorid Integer N OperatorIDofthereceivingoperatorthatmustbeusedwhentreatingtherequest.Ifset,theplatformwillbeforcedtousethisop-eratorIDandwillnotidentifytheoperatorofthedestinationMSISDNbasedonthenum-beringplan.Itisveryusefulincaseofcountrieswithnum-berportabilityifyouareabletoknowthedestinationoperator.

return_promo Numeric N Settingthisto“1”willreturnthecurrentpromotionrelatedtothetransaction’sopera-tor.



ResponseParameters

Name Type Descriptionauthentication_key Integer Keygeneratedbytheclienttoperformtherequest

(specifiedinkeyrequestparameter).Thetransactionisrejectedifthekeyhasbeenused.

error_code Integer Errorcodeofthetransaction.Refertosection9.0toseethelistoferrorcodesreturnedbytheAPI.

error_txt AlphanumericString

Descriptionoftheerror.

country AlphanumericString

Countryofthedestinationoperator.

countryid Integer UniqueIDofthedestinationcountry.

operator AlphanumericString

Destinationoperatorname.

operatorid Integer DestinationoperatorIDreturnedonlyifforcedbycli-ent,elseblank.

connection_status Integer Showssuccessfulratetothedestinationoperator.1-100with100being100%successrate.

destination_msisdn NumericString DestinationMSISDN(usuallyrecipientphonenumber).

destination_currency AlphanumericString

Currencyofthedestinationcountry.

product_list String Returnsthelistofallavailableproductsconfiguredforthecurrentaccount.Productsareseparatedbyacomma.

service_fee_list String Returnsthelistofallservicefeeconfiguredforthecur-rentaccount.Pricesareseparatedbyacommaandinthecurrencyofthecurrentaccount.

retail_price_list String Returnsthelistofallfinalretailpricesconfiguredforthecurrentaccount.Pricesareseparatedbyacommaandinthecurrencyofthecurrentaccount.

wholesale_price_list String Returnsthewholesaleprice(alsoknownasYourCost)listofallavailableproductsconfiguredforthecurrentaccount.Pricesareseparatedbyacommaandinthecurrencyofthecurrentaccount.



Name Type Descriptionlocal_info_amount_list String Listoffinalamountsreceivedbyrecipient(aftertaxes

andoperatorfees).Indicativevalueonly.

local_info_value_list Numeric Listofeachproductamount(beforetaxesandservicefees)inlocalcurrency.

local_info_currency AlphanumericString


promotion AlphanumericString

Promotiondetails.Returnedonlywhenrequestedwithreturn_promofield.

promo_start Date Promotionstartdate(e.g“yyyy-mm-ddhh:mm:ss+offset”).

promo_end Date Promotionenddate(e.g“2013-12-0113:05:55+00”).

SampleRequest<xml><login>test</login><key>1326965217</key><md5>md5</md5><destination_msisdn>+60172860300</destination_msisdn><delivered_amount_info>1</delivered_amount_info><return_service_fee>1</return_service_fee><action>msisdn_info</action></xml>



SampleResponse

<TransferTo><country>Malaysia</country><countryid>799</countryid><operator>MaxisMalaysia</operator><operatorid>385</operatorid><connection_status>100</connection_status><destination_msisdn>60172860300</destination_msisdn><destination_currency>MYR</destination_currency><product_list>5,10,20,30</product_list><service_fee_list>0.00,0.00,0.00,0.00</service_fee_list><retail_price_list>2.10,4.00,7.80,11.60</retail_price_list><wholesale_price_list>1.95,3.72,7.25,10.79</wholesale_price_list><authentication_key>1326965217</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt><local_info_amount_list>5.00,10.00,20.00,30.00</local_info_amount_list><local_info_value_list>5.00,10.00,20.00,30.00</local_info_value_list><local_info_currency>MYR</local_info_currency></TransferTo>



4.3 ReserveanID

Purpose GetareservedIDfromthesystem

Method reserve_id

ReturnsatransactionIDreservedinthesystemtobeusedinduringnexttopuporsimulationquery.Thisway,yoursystemhastheIDofthetransactionbeforesendingtherequesttoTransferTo.Otherwise,itwillappearonlyintheresponse.

RequestParameters



Y AccountloginnameprovidedbyTransfer-To.

key Integer Y Keygeneratedbytheclient.Thetransac-tionisrejectedifthekeyhasbeenused.


Y MD5sumofthehexencodedconcatena-tionoflogin,token,andkey.


Y Mustbesetto“reserve_id”



ResponseParameters

Name Type Descriptionauthentication_key Integer Keygeneratedbytheclienttoperformtherequest(speci-

fiedinkeyrequestparameter).Thetransactionisrejectedifthekeyhasbeenused.




reserved_id Numeric ReservedIDinTransferTosystemtouseinthenexttopuporsimulationrequest.

Request<xml><login>your_login</login><key>1217303174266</key><md5>b70aa58d2fe87d0bb0cd2b1902e5fce2</md5><action>reserve_id</action></xml>

Response

<TransferTo><status_code>0</status_code><reserved_id>20123457</reserved_id><error_txt>Transactionsuccessful</error_txt><authentication_key>1217303174266</authentication_key><error_code>0</error_code></TransferTo>



4.4 ConductaTop-up

Purpose Sendanairtimerecharge

Method topup

AllowstoconductaTop-up.Returnstransactiondetailsbasedonproducttype(PIN-LessorPIN-Based):transactionidandstatus,errorcode,pininformation,localamountreceived,etc.

RequestParameters






Y MD5sumofthehexencodedcon-catenationoflogin,token,andkey.


Y Mustbesetto“topup”




destination_msisdn NumericString Y DestinationMSISDN(usuallyrecipi-entphonenumber).Thisisthedestinationphonenum-berthatwillbecreditedwiththeamounttransferred.Formatissimi-larto“msisdn”andrestrictedtoin-ternationalphonenumberonly.

return_service_fee Numeric N Settingthisto“1”willreturnthefieldservice_fee_listintheAPIre-sponse.Blankor“0”ifyoudonotwantitreturned.

operatorid Integer N OperatorIDofthereceivingopera-torthatmustbeusedwhentreatingtherequest.Ifset,theplatformwillbeforcedtousethisoperatorIDandwillnotidentifytheoperatorofthedestinationMSISDNbasedonthenumberingplan.Itisveryusefulincaseofcountrieswithnumberportabilityifyouareabletoknowthedestinationopera-tor.

return_promo Numeric N Settingthisto“1”willreturnthecurrentpromotionrelatedtothetransaction’soperator.

msisdn AlphanumericString

Y Theinternationalphonenumberornameoftheuserrequestingtocreditaphonenumber(senderphonenumber).Theformatmustcontainthecountrycode,andwillbevalidwithorwithoutthe‘+’or‘00’placedbeforeit.Forexample:“6012345678”or“+6012345678”or“006012345678”(Malaysia)or“John”areallvalid.Thisfieldmustnotbeempty.

product AlphanumericString

Y Product(ordenomination)touseintherequest(often,thesameastheamountindestinationcurrency).




cid1 AlphanumericString(lessthan64chars)

N Thisfieldcanbeusedtorecordanykindofinformationwhenperform-ingatransaction.ItisstoredinTransferTodatabaseandmayap-pearinvariousreports.


N Thisfieldcanalsobeusedtorecordanykindofinformationwhenper-formingatransaction.ItisstoredinTransferTodatabaseandmayap-pearinvariousreports.


N Thisfieldcanalsobeusedtorecordanykindofinformationwhenper-formingatransaction.ItisstoredinTransferTodatabaseandmayap-pearinvariousreports.

reserved_id NumericString N Ifdefines,TransferTosystemwillusethepreviouslyreservedID(viaMethod“reserve_id”)forthistrans-action.

send_sms AlphanumericString(yesorno)

N RecipientSMSWhenthisfieldissetto“no”,thenotificationSMSisnotsenttotherecipient.Whenthisfieldisnotdefinedornotequalsto“no”,thedefaultSMSissenttorecipient.

sms AlphanumericString(lessthan30chars)

N RecipientSMS

Thisfieldisusedtosendyourownfreetextmessage.Itwillbeap-pendedtothedefaultnotificationSMSsenttotherecipient.ItdoesNOTdefinetheentirecontentoftheSMSsenttorecipient.

Mustbelessthan30charsandspe-cialcharactershavetobeencoded(&,<,>…).

sender_sms AlphanumericString

N SenderSMS“yes”ifrequired,blankor“no”ifnotrequired.




sender_text AlphanumericString(lessthan30chars)

N SenderSMSUsedonlyif“sender_sms”isequalsto"yes".Thisfieldisusedtosendyourownfreetextmessage.Itwillbeap-pendedtothedefaultnotificationSMSsenttothesender.ItdoesNOTdefinetheentirecontentoftheSMSsenttosender.

delivered_amount_info AlphanumericString(lessthan2chars)

N Settingthisto“1”willreturnthefieldslocal_info_amount_list,lo-cal_info_currencyandlo-cal_info_value_listintheAPIre-sponse.Blankor“no”ifyoudonotwantthisreturned.

return_timestamp Numeric N Settingthisto“1”willreturnthefieldtimestampintheAPIresponse.Blankor“0”ifyoudonotwantitre-turned.

return_version Numeric N Settingthisto“1”willreturntheAPIversionintheAPIresponse.Blankor“0”ifyoudonotwantitre-turned.

ResponseParameters

Oursystemcanreturntwopossibleresponsesdependingonthetypeofrechargeperformed:Pin-LessorPin-Based.

4.4.1 PINLessVersusPINBasedOperators

Mostreceivingoperators(orcarriers)arePINless(directtop-up),meaningthatthemobilephoneoftherecipientisrechargedinrealtime.AfewoperatorsarehoweverPINbased(mostlyintheUSAandUK).For thesePINbasedoperators,aPINcode is sentbySMS to the recipient,who thenhas tomanuallycompletetherechargeprocess(usuallybycallinganIVRtoredeemthePIN).

Theresponsesofthetopupmethodareslightlydifferentdependingonthetypeoftheoperator:someadditionalfieldsarereturnedincaseofPINbasedoperator(IVRnumber,PINcode,instructionsonhowtoredeemit,expirationdate…).



ExampleofPINbasedanswer:

4.4.2 PINLess

ResponseParameters

Name Type Descriptionauthentication_key Integer Keygeneratedbytheclienttoperformtherequest

(specifiedinkeyrequestparameter).Thetransactionisrejectedifthekeyhasbeenused.









operatorid Integer DestinationoperatorIDreturnedonlyifforcedbyclient,elseblank.

destination_msisdn NumericString DestinationMSISDN(usuallyrecipientphonenum-ber).

1 (XXX) XXX-XXXX



Name Type Descriptiondestination_currency Alphanumeric

StringCurrencyofthedestinationcountry.



promotion AlphanumericString

Promotiondetails.Returnedonlywhenrequestedwithreturn_promofield.

promo_start Date Promotionstartdate(e.g“yyyy-mm-ddhh:mm:ss+offset”).

promo_end Date Promotionenddate(e.g“2013-12-0113:05:55+00”).


Theinternationalphonenumberornameoftheuser(sender)requestingtocreditaphonenumber.

originatingcurrency AlphanumericString

Currencyoftheaccountfromwhichthetransactionisrequested.

product_requested Float Valueoftheproductdefinedin“product”fieldofthetopuprequest.

actual_product_sent Float Returnsthevaluerequestedtotheoperator(equalstoproduct_requestedincaseofsuccessfultransac-tion).Itequalsto0whenTop-upfailed.

sms_sent AlphanumericString

RecipientSMSDefinesthestatusofthenotificationSMSsenttotherecipient.Returns“yes”onlyiftheSMShasbeensuccessfullysent.

sms AlphanumericString

RecipientSMSReturnsthecustommessageappendedtothede-faultnotificationSMSsenttotherecipient.

sender_sms AlphanumericString

SenderSMSDefinesthestatusofthenotificationSMSsenttothesender.Returns“yes”onlyiftheSMShasbeensuccessfullysent.

sender_text AlphanumericString

SenderSMSReturnsthecustommessageappendedtothede-faultnotificationSMSsenttothesender.

wholesale_price Numeric Returnsthecostoftheproductdefinedin“product”fieldoftherequest.Thiscostissetintheaccount’scurrency.



Name Type Descriptionservice_fee Numeric Returnstheservicefeeoftheproductasconfigured

intheaccount.

retail_price Numeric Returnstheretailpriceoftheproductasconfiguredintheaccount.

transactionid Integer IDofthetransaction.

cid1 AlphanumericString

Valueofthecustomizedfieldcid1sentintheTop-uprequest.





reference_operator AlphanumericString

Referenceoftheoperator(returnedonlyifavaila-ble).

local_info_amount Numeric Finalamountreceivedbyrecipient(aftertaxesandoperatorfees).Indicativevalueonly.

local_info_value Numeric Amountoftheproduct(beforetaxesandservicefees)inlocalcurrency.

return_timestamp Date Timestamprecordedforthistransaction(e.g“2013-03-1800:00:00”).

return_version Numeric VersionofthisAPI.

balance Numeric Formainaccount:returnstheaccount’sremainingbalance.Forsub-account:returnstheaccount’sremaininglimitbalanceofthedayifadailylimitisfixed.Else,returnstheaccountremainingbalance.



SampleRequest

<xml><login>test</login><key>1326963417</key><md5>md5</md5><msisdn>69999999999</msisdn><sms>Happybirthday!</sms><destination_msisdn>+60172860300</destination_msisdn><product>10</product><cid1>MyText</cid1><sender_sms>yes</sender_sms><sender_text></sender_text><delivered_amount_info>1</delivered_amount_info><return_timestamp>1</return_timestamp><return_version>1</return_version><return_service_fee>1</return_service_fee><action>topup</action></xml>



SampleResponse

<TransferTo><transactionid>77748538</transactionid><msisdn>69999999999</msisdn><destination_msisdn>60172860300</destination_msisdn><country>Malaysia</country><countryid>799</countryid><operator>MaxisMalaysia</operator><reference_operator></reference_operator><operatorid></operatorid><originating_currency>USD</originating_currency><destination_currency>MYR</destination_currency><product_requested>10</product_requested><actual_product_sent>10</actual_product_sent><wholesale_price>3.39</wholesale_price><service_fee>0.00</service_fee><retail_price>4.30</retail_price><balance>8.1</balance><sms_sent>yes</sms_sent><sms>Happybirthday</sms><sender_sms>yes</sender_sms><sender_text></sender_text><cid1>MyText</cid1><cid2></cid2><cid3></cid3><authentication_key>1326963417</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt><local_info_value>10.00</local_info_value><local_info_amount>10.00</local_info_amount><local_info_currency>MYR</local_info_currency><return_timestamp>2013-03-1800:00:01</return_timestamp><return_version>1.06.08</return_version></TransferTo>



4.4.3 PINBased

ResponseParameters(additionalparametersapplicabletoPINBasedonly)

Name Type Descriptionpin_based String Returns“Yes”ifPIN-basedtransactions.Else“No”.

pin_option_1 String Additionalinformation.Forexample,itcandescribehowtousethePINdirectlyfromhandset(byenteringadedicatedUSSDcode).

pin_option_2 String Additionalinformation.Forexample,itcanprovidetheopera-torrefillwebsite.

pin_option_3 String Additionalinformation.Forexample,itcanprovidetheopera-torrefillcallcenter.

pin_value Integer ValueofthePIN.

pin_code AlphanumericString

CodeofthePIN.

pin_ivr Integer IVRnumberofthePIN.

pin_serial AlphanumericString

SerialnumberofthePIN.

pin_validity String ValidityofthePIN.

SampleRequest

<xml><login>test</login><key>1326964272</key><md5>md5</md5><msisdn>69999999999</msisdn><sms>TestcreditfromTransferTo</sms><destination_msisdn>00009779742045269</destination_msisdn><product>200</product><delivered_amount_info>1</delivered_amount_info><action>Top-up</action></xml>



SampleResponse1/2

<TransferTo><transactionid>77749654</transactionid><msisdn>69999999999</msisdn><destination_msisdn>9779742045269</destination_msisdn><country>Nepal</country><countryid>819</countryid><operator>NTCCDMANepal</operator><reference_operator></reference_operator><operatorid></operatorid><originating_currency>USD</originating_currency><destination_currency>NPR</destination_currency><product_requested>200</product_requested><actual_product_sent>200</actual_product_sent><wholesale_price>2.58</wholesale_price><service_fee>0.00</service_fee><retail_price>3.30</retail_price><balance>5.52</balance><sms_sent>yes</sms_sent><sms>TestcreditfromTransferTo</sms><cid1></cid1><cid2></cid2><cid3></cid3> <pin_based>yes</pin_based><pin_option_1>Torechargeyourmobile,dial1415fromyourownPre-Paidmo-bilephoneandfollowtheinstructions.</pin_option_1><pin_option_2>SkyPhone</pin_option_2><pin_option_3></pin_option_3><pin_value>200</pin_value><pin_code>12345678901234</pin_code><pin_ivr>1415</pin_ivr><pin_serial>123456789123456789</pin_serial><pin_validity>30Days</pin_validity>...

Status: Transaction successful

Number: 9779742045269 Operator: NTC CDMA Nepal Date: Fri Apr 25 2014 12:45:08 PM Transaction ID: 77749654 PIN Info 1: To recharge your mobile, dial 1415 from your own Pre-Paid mobile phone and follow the instructions. PIN Info 2: SkyPhone PIN Value: 200 PIN Code: 1234 5678 9012 34



SampleResponse2/2...<service_fee>0.00</service_fee><retail_price>3.30</retail_price>...<authentication_key>1326964272</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt><local_info_value>200.00</local_info_value><local_info_amount>200.00</local_info_amount><local_info_currency>NPR</local_info_currency></TransferTo>

Status: Transaction successful Number: 9779742045269 Operator: NTC CDMA Nepal Date: Fri Apr 25 2014 12:45:08 PM Transaction ID: 77749654 PIN Info 1: To recharge your mobile, dial 1415 from your own Pre-Paid mobile phone and follow the instructions. PIN Info 2: SkyPhone PIN Value: 200 PIN Code: 1234 5678 9012 34 PIN IVR: 1415 PIN Serial: 123 456 789 123 456 789 PIN Validity: 30 Days Value sent: 200 NPR (before taxes)

Value received*: 200 NPR (after taxes + operator fees)

Transaction Fee: 0.00 USD Amount paid: 3.30 USD includes a service fee of 0.00

* Estimate only. Actual amount received by recipient may differ from dis-played amount.



4.4.4 CheckifaMSISDNissubjectedtoapromotion

Bothmsisdn_infoandtopupmethodsallowtoreturnthepromotionrelatedtoagivenphonenumberofdestination.Hereafterisanexamplewithreturn_promofieldrequested(equalsto1)andsubsequentre-sponses(promotiondetail,startandenddates).

SampleRequest

<xml><login>test</login><key>1326963417</key><md5>md5</md5><msisdn>69999999999</msisdn><sms>Happybirthday!</sms><destination_msisdn>+60172860300</destination_msisdn><product>10</product><cid1>MyText</cid1><sender_sms>yes</sender_sms><sender_text></sender_text><delivered_amount_info>1</delivered_amount_info><return_promo>1</return_promo><return_timestamp>1</return_timestamp><return_version>1</return_version><return_service_fee>1</return_service_fee><action>topup</action></xml>



SampleResponse

<TransferTo><transactionid>77748538</transactionid><msisdn>69999999999</msisdn><destination_msisdn>60172860300</destination_msisdn><country>Malaysia</country><countryid>799</countryid><operator>MaxisMalaysia</operator><reference_operator></reference_operator><operatorid></operatorid><originating_currency>USD</originating_currency><destination_currency>MYR</destination_currency><product_requested>10</product_requested><actual_product_sent>10</actual_product_sent><wholesale_price>3.39</wholesale_price><service_fee>0.00</service_fee><retail_price>4.30</retail_price><balance>8.1</balance><sms_sent>yes</sms_sent><sms>Happybirthday</sms><sender_sms>yes</sender_sms><sender_text></sender_text><cid1>MyText</cid1><cid2></cid2><cid3></cid3><authentication_key>1326963417</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt><local_info_value>10.00</local_info_value><local_info_amount>10.00</local_info_amount><local_info_currency>MYR</local_info_currency><return_timestamp>2013-03-1800:00:01</return_timestamp><return_version>1.06.08</return_version><promotion>Promotion:Quadruple(4x)Balance Operator:Claro Country:Nicara-gua Denominations(USD):5andabove Date:December16th,2013toDecember19th,2013at11:59pm(-6GMT) TermsandConditions: -Claronetworkcalls -Callinternationaldestinations -Callingotheroperatorsaccordingtotheuserprofile -Forrefills$5to$11yourbonuswillexpirein30days -Forrefills$12andaboveyourbonuswillexpirein45days Exceptionspromotionalbalance(nottobeused) -SendTextMessages -Callingotheroperatorsaccordingtotheuserpro-file -InternetBrowsing</promotion><promo_start>2013-12-1516:00:00+00</promo_start><promo_end>2015-12-3115:59:00+00</promo_end></TransferTo>



5.0 AdvancedvaluesacrossbordersAsdescribedinpreviouschapter,TransferToAPImainpurposeistoallowcustomerstoperformairtimerecharges.However,TransferToAPIisalsodesignedtoofferotherrechargesolutionssuchasElectricityinIndonesia(asknownasPLN)andDTHtelevisioninIndiaandPhilippines.

ThischapterdescribesthemainmethodsofTransferToAPIforeachspecificproduct:

• Performamsisdn_infoquerytoretrievetheavailablerechargeamounts• Usethetopupmethodtocompletetherecharge

Moreover,itprovidesyouwiththedifferentkindofresponses(PINBased/PINLess)returnedbytheAPIandbaseduponthetypeofservice.

5.1 PrepaidElectricity5.1.1 PLNIndonesia:PINBased

Description

APLNproductisaprepaidelectricityvoucherexpressedintheformofa20digitsPIN.

As the top-up solution, TransferTo provides solutions enablingmigrants to conveniently recharge thePLNaccounttotheirlovedonesinIndonesia.

Pre-conditions

InordertogeneratethePINandensurethatitissenttotherightperson,youmustprovidethefollow-ingparameters:

1. Recipient'sPLNprepaidmeternumber(11digits)

Note:TherecipientofthePINmusthaveaprepaidelectricityaccountwithPLN,aleadingutilitycompanyinIndonesia.

2. Recipient'sphonenumber

Note:Oncegenerated,thePINissenttotherecipientviaSMS.Then,thePINmustbeenteredbythere-cipientintotheirprepaidelectricitymetertorechargetheirmetervalue.



Method msisdn_info

Samplequery<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><destination_msisdn>PLN14032918279_628123456770</destination_msisdn><operatorid>1671</operatorid><action>msisdn_info</action></xml>Responseparametersaresimilartotheonesdescribedinchapter4.2.

ListofavailablePLNproductsisreturnedintheparameternamedproduct_list.

Method topup

Samplequery

<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><destination_msisdn>PLN14032918279_628123456770</destination_msisdn><operatorid>1671</operatorid><msisdn>sendernumber</msisdn><product>10000</product><action>topup</action></xml>Inbothmethodsyoumustfillthedestination_msisdnparameterwith:

1. Recipient’sPLNprepaidmeternumber(e.g14032918279)2. Recipient'sphonenumber(e.g628123456770)

Responseparametersaresimilartotheonesdescribedinchapter4.4.3.

ThefinalPINisreturnedintheparameternamedpin_code.ThisPINisalsosenttotherecipientphonenumberthatyoucanfindinresponseparameternameddestination_msisdn.



5.2 InternationalCallingService–PINLESS/PINFREE

TheInternationalCallingServicePinlessallowsuserstomakeinternationalcallswithouttheattachmentstoanyphoneprovider. Simpleregisteryourphonenumbertoanyoftheprovidersandenjoyinterna-tionalphoneserviceatmuchbetterratesthanregularphoneoperators.

5.2.1 DollarPhonePINLESS

DollarPhonePinless is a high-quality prepaid international calling service you can usewith any phone.Therearenohiddenfees,nocontracts,anditworksautomaticallywithyourcurrentphoneservice.

Pre-conditions

Inordertocreateanewaccountorreloadacurrentone,youmustprovidethefollowingparameters:

1. ValidUSAPhonenumber.

Note:Ifthereisanewaccount,accountwillbecreatedautomaticallyandtheaccountrecipientwillre-ceiveandSMSwiththeaccessinformationtomakeinternationalcalls.

Ifthereisacurrentaccount,thetopupwillbecreditedandthecustomerwillbenotifiedoftherecharge.

2. OperatorID(2010)

Note:OperatorneedstobeforcedinordertousethisserviceviaAPI.

Method msisdn_info

Samplequery

<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><destination_msisdn>13057893399</destination_msisdn><operatorid>2010</operatorid><action>msisdn_info</action></xml>Responseparametersaresimilartotheonesdescribedinchapter.

ListofavailableInternationalcallingservicePINLESSproductsisreturnedintheparameternamedprod-uct_list.



Method topup

Samplequery

<xml><login>your_login</login><key>1420579279</key><md5>83c9c262adfee072edb44500f63f1b80</md5><msisdn>13057893399</msisdn><destination_msisdn>13057893399</destination_msisdn><product>1</product><sms></sms><operatorid>2010</operatorid><action>topup</action></xml>

Responseparametersaresimilartotheonesdescribedinchapter4.4.2



SMSNotificationsfromDollarPhone

NewAccount:

TopupAccount:



5.3 PrepaidbundlesPrepaidbundlesareamixtureofcalls,data,SMSandsocialmediaaccesswhichtheuserscanpurchaseotherthanairtimecredits.

Pre-conditions

Todoarecharge,youmustprovidethefollowingparameters:

1. Recipient'sphonenumber2. OperatorID

Note:OperatorIDneedstobeforcedinordertousethisserviceviaAPI.

Listofoperatorsofferingprepaidbundles-OperatorID

Forthelistofoperatorsavailabletoyou,pleaserefertoyourpricelistathttps://shop.transferto.com/cgi-bin/display_price_listYoucancontactyouraccountmanageroremail [email protected] ifyou’re interested tohavethisproductaddedtoyouraccount.

Method msisdn_info

Samplequery

<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><destination_msisdn>521122334455</destination_msisdn><operatorid>2446</operatorid><action>msisdn_info</action></xml>

Responseparametersaresimilartotheonesdescribedinsection4.2.

Listofavailabledenominationsisreturnedintheparameternamedproduct_list.



Method topup

Samplequery


Responseparametersaresimilartotheonesdescribedinsection4.4.2.

5.4 Credits5.4.1 ViberOutCredits

ViberOutisaservicethatallowsViberuserstocallanyphonenumberatlowrates.Callscanbemadetolandlinesandmobiles,eveniftheydonothavetheViberApplicationinstalled.

Pre-conditions




ListofViberOperatorID




Method msisdn_info

Samplequery

<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><destination_msisdn>151234567890</destination_msisdn><operatorid>2675</operatorid><action>msisdn_info</action></xml>Responseparametersaresimilartotheonesdescribedinsection4.2.


Method topup

Samplequery


Responseparametersaresimilartotheonesdescribedinsection4.4.2.

5.5 IndiaGiftVouchers

GiftVouchersarePIN-baseddigitalvouchers.ThePINwillbesentviaSMS.TheuserscanusethePINtoredeemforproductsandservicesoftherespectivemerchants.

Pre-conditions






ListofGiftVouchers’OperatorID


Method msisdn_info

Samplequery

<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><destination_msisdn>911234567890</destination_msisdn><operatorid>2758</operatorid><action>msisdn_info</action></xml>Responseparametersaresimilartotheonesdescribedinchapter4.2.


Method topup

Samplequery

<xml><login>your_login</login><key>1420579279</key><md5>83c9c262adfee072edb44500f63f1b80</md5><destination_msisdn>911234567890</destination_msisdn><msisdn>sendernumber</msisdn><product>100</product><operatorid>2675</operatorid></xml>Responseparametersaresimilartotheonesdescribedinchapter4.4.3.



6.0 Tests:SimulateTop-upandErrorcodesThis section isdesigned fordeveloperswhowant to test theiraccountcredentials, simulateaTop-up,simulatedifferenterrorcodesreturnedbytheAPI,ormonitortheconnectiontotheAPI.

6.1 Checkaccountcredentials

Method ping

AllowstocheckaccountcredentialsortomonitortheconnectiontotheAPI.

RequestParameters








Y Mustbesetto“ping”

ResponseParameters

Name Type Descriptioninfo_txt Integer Contains“pong”ifthetransactionissuccessful.

authentication_key Integer Keygeneratedbytheclienttoperformtherequest(speci-fiedinkeyrequestparameter).Thetransactionisrejectedifthekeyhasbeenused.






SampleRequest<xml><login>test</login><key>1327027869</key><md5>md5</md5><action>ping</action></xml>

SampleResponse<TransferTo><info_txt>pong</info_txt><authentication_key>1327027869</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>

6.2 MonitorconnectiontotheAPI

MonitoringtheconnectiontotheAPIcanbedoneeasilythankstothepingmethod(asdescribedinpreviouschapter).

6.3 SimulateaTop-up

Method simulation

Themethodsimulationtakesthesameparametersastopupmethod.ItdoesnotperformarealTop-uptothedestinationnumber.

ThisactionwilltestifthedestinationnumberisinTransferTonumberingplan,andiftheproductspeci-fiedisvalid.

• ItDOESNOTverify ifthedestinationnumberhasexpiredfor instanceastherequest isnotsubmittedtotheoperator.Thus,asimulationcanbesuccessful,whilearealtop-up(requestsenttotheoperatortoperformbothdebitandTop-up)canfail.

• ForPINBasedproducts,APIwillrespondbasics information(PINLess like).Allparame-tersrelatedtoPINinformationwillnotbeprovidedintheresponse.

Notethatthisactionwillprovideyouwithsomeinformation(productsavailableinyouraccount)butisnotpartoftheTop-upcycle.YoushouldperformTop-upwithoutmakinganysimulationsbefore.



6.4 Simulateerrorcodes

A few fakephonenumbers in Indonesiahavebeencreatedand setupwithavailableproductsof IDR5000,10000,20000,50000and100000:

628123456710:errorcode0forPINbasedTop-up(successfultransaction).

628123456770:errorcode0forPINlessTop-up(successfultransaction).

628123456780:errorcode204(destinationnumberisnotavalidprepaidphonenumber).

628123456781:errorcode301(inputvalueoutofrangeorinvalidproduct).

628123456790:errorcode214(transactionrefusedbytheoperator).

628123456798:errorcode998(systemnotavailable,pleaseretrylater).

628123456799:errorcode999(unknownerror,pleasecontactsupport).

TransferTohighlyrecommendtoperformonetopupquerybyphonenumber listedabove, inordertoensurethegoodcomprehensionoftopupresponsesandtodeveloparobusterrormanagementsystem.



7.0 Account:Balance,OfferandPricelistQueryThissectiondescribeshowtoretrieveinformationonyouraccountasthefollowing:

• Remainingbalanceofyourmasteraccountandsub-accounts• Dailylimitofasub-account• Listofcountriesofferedtoyouraccount• Listofoperatorsofferedbycountry• Listofdenomination,includingwholesaleandretailprices,offeredtoyouraccount

7.1 Checkaccountbalance

Purpose

Method check_wallet

ReturnsthebalanceinyourTransferToaccount.

Thismethodshallnotbeusedmorethan24timesperday.

IfyoujustneedtomonitortheconnectiontotheAPI,TransferTohighlyrecommendtousethepingmethod(referto6.1).

Pleasenotethatalowbalancealertisautomaticallysenttotheemailconfiguredinyouraccountwhentheminimumthresholdisreached.

Retrieve total balance (sum of master and sub accounts)

Retrieve sub-account balance and Daily limit

Retrieve master account balance



RequestParameters



Y AccountloginnameprovidedbyTransfer-To.

key Integer Y Keygeneratedbytheclient.Thetransac-tionisrejectedifthekeyhasbeenused.


Y MD5sumofthehexencodedconcatena-tionoflogin,token,andkey.


Y Mustbesetto“check_wallet”

ResponseParameters






type AlphanumericString

Accounttype:“Master”(mainaccount)or“Retailer”(sub-account)

name AlphanumericString

Accountloginname.

currency AlphanumericString

Accountcurrency(USD,GBP,EUR,etc…).

balance Numeric Formainaccount:returnstheaccount’sremainingbalance.Forsub-account:returnstheaccount’sremaininglimitbal-anceofthedayifadailylimitisfixed.Else,returnstheac-countremainingbalance.



Name Type Descriptionwallet Numeric Formainaccount:returnsthetotalremainingbalance(sum

ofallsub-accountsandcurrentmaster).Forsub-account:

1. Ifbalanceissharedanddailylimitisfixed:returnsthefixeddailylimitamount

2. Ifbalanceissharedbutdailylimitisnotfixed:returns“NoLimit”

3. Elseifbalanceisnotshared:returnstheremainingbalance

Sample1–Masteraccount

Retrieve total balance (sum of master and sub accounts)

Retrieve master account balance



Request

<xml><login>demo</login><key>1326958538</key><md5>yourMD5here</md5><action>check_wallet</action></xml>

Response<TransferTo><type>Master</type><name>demo</name><currency>USD</currency><balance>5.99</balance><wallet>9.99</wallet><authentication_key>1326958538</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>

Current balance of master account. Total balance of master and sub-accounts.



Sample2–Sub-Account–SharedBalance–DailyLimitFixedto1

Request

<xml><login>democ</login><key>1326958538</key><md5>yourMD5here</md5><action>check_wallet</action></xml>

Response

<TransferTo><type>Retailer</type><name>democ</name><currency>USD</currency><balance>1.00</balance><wallet>1.00</wallet><authentication_key>1326958689</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>

Retrieve sub-account balance and Daily limit

Daily limit of sub-account. Current balance of sub-account (daily remaining balance).



Sample3–Sub-Account–SharedBalance–NoDailyLimit

Request

<xml><login>testing1</login><key>1326958538</key><md5>yourMD5here</md5><action>check_wallet</action></xml>

Response<TransferTo><type>Retailer</type><name>testing1</name><currency>USD</currency><balance>1.00</balance><wallet>NoLimit</wallet><authentication_key>1326958689</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>



Sample4–Sub-Account–NoSharedBalance

Request

<xml><login>demoa</login><key>1326958538</key> <md5>yourMD5here</md5><action>check_wallet</action></xml>

Response<TransferTo><type>Retailer</type><name>demoa</name><currency>USD</currency><balance>2.00</balance><wallet>2.00</wallet><authentication_key>1326958689</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>

Current balance of sub-account

Daily Limit Not Applicable

Balance of sub-account



7.2 Getthelistofcountriesofferedtomyaccount

Purpose Getthefollowinglist

Method pricelist

Returnsthelistofcountriesofferedtoyouraccountwhenrequestissentwith“countries”inargument(seeabove).

RequestParameters






Y MD5sumofthehexencodedconcatenationoflogin,to-ken,andkey.


Y Mustbesetto“pricelist”

info_type AlphanumericString

Y Mustbesetto“countries”toreturnthelistofallcountriesofferedtotheaccountnamedefinedinloginparameter.



ResponseParameters







Listofcountriesoffered.

countryid Integer ListofrespectiveuniqueIDofcountrieslistedinparameter“country”.

SampleRequest

<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><info_type>countries</info_type><action>pricelist</action></xml>

SampleResponse<TransferTo><country>Afghanistan,Albania,Anguilla,AntiguaandBarbuda,Argentina,Armenia,Aruba</country><countryid>661,662,916,668,669,670,671</countryid><authentication_key>1337662098</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>



7.3 Getthelistofoperatorsforagivencountry

Purpose SendacountryIDtogetthelistofoperatorsofferedinthisdestination

Method pricelist

Returnsthe listofoperatorsofferedtoyouraccount, foraspecificcountry,whenrequest issentwith“countryid”inargument(seeabove).



RequestParameters










Y Mustbesetto“country”toreturnthelistofoperatorsavailableinthegivencountry.

content Integer Y Thisparameterisrelatedtoinfo_type:definesthecoun-tryidforwhichtheoperatorlistisrequested.

ResponseParameters







Countryrequested.

countryid Integer UniqueIDoftherequestedcountry.


Listofdestinationoperatorsoffered.

operatorid Integer ListofrespectiveuniqueoperatorsIDofoperatorlistedinparameter“operator”.



SampleRequest

<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><info_type>country</info_type><content>767</content><action>pricelist</action></xml>

SampleResponse

<xml><country>Indonesia</country><countryid>767</countryid><operator>IndosatStaroneIndonesia,TelkomFlexiIndonesia,IndosatIM3Indonesia,AAA-TESTINGIndone-sia,EsiaBakrieTelecomIndonesia,IndosatMentariIndonesia,TelkomselSimpatiIndonesia,ThreeTelecomIndonesia,TelkomselKartuASIndonesia,ExcelcomIndonesia,AxisIndonesia</operator><operatorid>1320,1322,1313,1310,1326,1312,1324,1327,1325,215,1411</operatorid><authentication_key>1337662386</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></xml>

Specify the country ID from which you request operator list.



7.4 Getthelistofproductsforagivenoperator

Purpose Sendanoperator ID to get the list of denomimationaswell aswholesale andretailprices.

Method pricelist

Returnsthelistofdenominationincludingwholesaleandretailpricesofferedtoyouraccount,foraspe-cificoperator,whenrequestissentwith“operatorid”inargument(seeabove).

RequestParameters










Y Mustbesetto“operator”toreturnthelistofwholesaleandretailpricesavailableforthegivenoperator.

content Integer Y Thisparameterisrelatedtoinfo_type:definestheopera-toridforwhichthepriceslistsarerequested.



ResponseParameters







Countryoftherequestedoperator.

countryid Integer UniqueIDofthecountry.


Operatorrequested.

operatorid Integer UniqueIDoftheoperator.



product_list String Returnsthelistofallavailableproductsconfiguredforthecurrentaccountandthegivenoperator.Productsareseparatedbyacomma.

retail_price_list String Returnsthelistofallfinalretailpricesconfiguredforthecurrentaccountandthegivenoperator.Pricesareseparatedbyacommaandinthecurrencyofthecurrentaccount.

wholesale_price_list String Returnsthewholesaleprice(alsoknownasYourCost)listofallavailableproductsconfiguredforthecurrentaccountandthegivenoperator.Pricesareseparatedbyacommaandinthecurrencyofthecurrentaccount.



SampleRequest<xml><login>your_login</login><key>1326965217</key><md5>md5</md5><info_type>operator</info_type><content>1313</content><action>pricelist</action></xml>

SampleResponse

<xml><country>Indonesia</country><countryid>767</countryid><operator>IndosatIM3Indonesia</operator><operatorid>1313</operatorid><destination_currency>IDR</destination_currency><product_list>5000,10000,20000,25000,50000,100000</product_list><wholesale_price_list>0.85,1.28,2.98,5.53,11.05</wholesale_price_list><retail_price_list>1.00,1.50,3.50,6.50,13.00</retail_price_list><authentication_key>1337662386</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>

Specify the operator ID from which you request price list.



8.0 Reports:TransactionInformationQuery

Inthissection,youwillfindthefollowinginformation:

• HowtoretrieveinformationonatransactionfromanID• Howtoretrievealistoftransactionperformedduringagivendaterange• HowtoretrieveatransactionIDfromtheuniquekeyusedduringthetransactionquery

8.1 GetinformationfromatransactionID

Purpose Getdestinationphonenumber,topupamount,retailprice,etc.

Method trans_info

ReturnsallavailableinformationonaspecifictransactionID.

Pleasenotethatthismethodisuselessifcalledjustaftertopuprequest.Firstbecauseitcantaketimetoupdatedatabase.Besides,thetopupresponseprovidesthesameinformation.

RequestParameters








Y Mustbesetto“trans_info”

transactionid Integer Y IDofthetransactionwhichrequiresinfor-mation.



ResponseParameters

8.1.1 PINLess

Name Type Descriptiontransactionid Integer DefinestheIDofthetransaction.


Theinternationalphonenumberornameoftheuser(sender)requestingtocreditaphonenumber.

destination_msisdn NumericString DestinationMSISDN(usuallyrecipientphonenumber).

transaction_authentication_key Integer Authenticationkeyusedduringthetransac-tion.

transaction_error_code Integer ErrorcodelinkedtothetransactionIDspeci-fiedintherequest.

transaction_error_txt AlphanumericString

Descriptionoftheerrorlinkedtothetransac-tionIDspecifiedintherequest.






operatorid Integer DestinationoperatorIDreturnedonlyifforcedbyclient,elseblank.

reference_operator AlphanumericString

Referenceoftheoperator(returnedonlyifavailable).

product_requested Float Valueoftheproductdefinedin“product”fieldofthetopuprequest.

actual_product_sent Float Returnsthevaluerequestedtotheoperator(equalstoproduct_requestedincaseofsuc-cessfultransaction).Itequalsto0whenTop-upfailed.

wholesale_price Numeric Returnsthecostoftheproductdefinedin“product”fieldoftherequest.Thiscostissetintheaccount’scurrency.

retail_price Numeric Returnstheretailpriceoftheproductascon-figuredintheaccount.



Name Type Descriptionsms Alphanumeric

StringRecipientSMSReturnsthecustommessageappendedtothedefaultnotificationSMSsenttotherecipient.







date String Dateofthetransaction(GMT).

originatingcurrency AlphanumericString

Currencyoftheaccountfromwhichthetrans-actionisrequested.



pin_based String Typeofproductreturned(“Yes”,default“No”ifnotset).

local_info_amount Numeric Finalamountreceivedbyrecipient.Indicativevalueonly.


Localcurrencyindestination

local_info_value Numeric Valueofthistransactionbeforetaxandservicefeeinlocalcurrency.

authentication_key Integer Keygeneratedbytheclienttoperformthere-quest(specifiedinkeyrequestparameter).Thetransactionisrejectedifthekeyhasbeenused.

error_code Integer Errorcodeofthetransaction.Refertosection10toseethelistoferrorcodesreturnedbytheAPI.





SampleRequest

<xml><login>your_login</login><key>1326967613</key><md5>md5</md5><transactionid>188609730</transactionid><action>trans_info</action></xml>



SampleResponse

<TransferTo><transactionid>188609730</transactionid><msisdn>69999999999</msisdn><destination_msisdn>628123456770</destination_msisdn><transaction_authentication_key>1326963417</transaction_authentication_key><transaction_error_code>0</transaction_error_code><transaction_error_txt>Transactionsuccessful</transaction_error_txt><country>Indonesia</country><countryid>767</countryid><operator>AAA-TESTINGIndonesia</operator><operatorid>0</operatorid><reference_operator>HASH(0x1343f70)</reference_operator><product_requested>1.00</product_requested><actual_product_sent>1.00</actual_product_sent><wholesale_price>0.03</wholesale_price><retail_price>0.00</retail_price><sms>Tshoptestfromme</sms><cid1></cid1><cid2></cid2><cid3></cid3><date>2014-06-1117:36:21.326342</date><originating_currency>USD</originating_currency><destination_currency>IDR</destination_currency><authentication_key>1326967613</authentication_key><pin_based>no</pin_based><local_info_amount>1</local_info_amount><local_info_currency>IDR</local_info_currency><local_info_value>1</local_info_value><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>

Key used to perform the transaction 188609730.



8.1.2 PINBased

ResponseParameters(additionalparametersapplicabletoPINBasedonly)

Name Type Descriptionpin_based String Returns“Yes”ifPIN-basedtransactions.Else“No”.

pin_validity String ValidityofthePIN.

pin_code AlphanumericString

CodeofthePIN.

pin_ivr Integer IVRnumberofthePIN.

pin_serial AlphanumericString

SerialnumberofthePIN.

pin_value Integer ValueofthePIN.

pin_option_1 String Additionalinformation.Forexample,itcandescribehowtousethePINdirectlyfromhandset(byenteringadedicatedUSSDcode).

pin_option_2 String Additionalinformation.Forexample,itcanprovidetheopera-torrefillwebsite.

pin_option_3 String Additionalinformation.Forexample,itcanprovidetheopera-torrefillcallcenter.

SampleRequest

<xml><login>your_login</login><key>1326968024</key><md5>md5</md5><transactionid>77749654</transactionid><action>trans_info</action></xml>



SampleResponse

<TransferTo><transactionid>77749654</transactionid><msisdn>69999999999</msisdn><destination_msisdn>9779742045269</destination_msisdn><transaction_authentication_key>1326964272</transaction_authentication_key><transaction_error_code>0</transaction_error_code><transaction_error_txt>Transactionsuccessful</transaction_error_txt><country>Nepal</country><countryid>819</countryid><operator>NTCCDMANepal</operator><operatorid>0</operatorid><reference_operator></reference_operator><product_requested>200</product_requested><actual_product_sent>200</actual_product_sent><wholesale_price>2.58</wholesale_price><retail_price>3.30</retail_price><sms>FreecreditfromTransferTo</sms><cid1></cid1><cid2></cid2><cid3></cid3><date>2012-01-1909:11:13.792268</date><originating_currency>USD</originating_currency><destination_currency>NPR</destination_currency><pin_based>yes</pin_based><pin_value>200</pin_value><pin_code>12345678901234</pin_code><pin_ivr>1415</pin_ivr><pin_serial>123456789123456789</pin_serial><pin_validity>2014-01-18T00:00:00+05:45</pin_validity><pin_option_1>Torechargeyourmobile,dial1415fromyourownPre-Paidmobilephoneandfollowthein-structions.</pin_option_1><pin_option_2>SkyPhone</pin_option_2><pin_option_3></pin_option_3><local_info_amount>2.80</local_info_amount><local_info_currency>NPR</local_info_currency><local_info_value>2.80</local_info_value><authentication_key>1326968024</authentication_key><error_code>0</error_code><error_txt>Transactionsuccessful</error_txt></TransferTo>



8.2 Getthelistoftransactionsperformedduringagivendaterange

Method trans_list

Returnsthelistoftransactionsperformedduringagivendaterange.

RequestParameters








Y Mustbesetto“trans_list”

destination_msisdn NumericString N DestinationMSISDN(usuallyrecipientphonenumber).Thisisthedestinationphonenumberthatwillbecreditedwiththeamounttrans-ferred.Formatissimilarto“msisdn”andre-strictedtointernationalphonenumberon-ly.


N Theinternationalphonenumberornameoftheuserrequestingtocreditaphonenum-ber(senderphonenumber).Theformatmustcontainthecountrycode,andwillbevalidwithorwithoutthe‘+’or‘00’placedbeforeit.Forexample:“6012345678”or“+6012345678”or“006012345678”(Malay-sia)or“John”areallvalid.Thisfieldmustnotbeempty.

code NumericString N Theerror_codeofthetransactionstosearchfor.E.g“0”tosearchforonlyallsuc-cessfultransactions.Ifleftempty,alltrans-actionswillbereturned(Failedandsuccess-ful).




start_date String Y Definesthestartdateofthesearch(includ-ed).FormatmustbeYYYY-MM-DD.

stop_date String Y Definestheenddateofthesearch(includ-ed).FormatmustbeYYYY-MM-DD.

ResponseParameters






status_code Integer Transactionstatus.0willbereturnedincaseofsuccessfultransaction.Deprecated,usefield“error_code”instead.

transaction_list String ListoftransactionIDsfoundbasedonsearchparameters(daterangeandMSISDN).Transactionsareseparatedbyacomma.

SampleRequest

<xml><login>your_login</login><key>1217301496240</key><md5>14d1a9f386479b2af4d62a8f932f5d79</md5><msisdn>6598236911</msisdn><destination_msisdn>628123456770</destination_msisdn><code>0</code><start_date>2008-01-01</start_date><stop_date>2008-08-01</stop_date><action>trans_list</action></xml>

Refine the research by specifying Sender or/and Recipient Phone Numbers.

Define the date range (mandatory parameters).



SampleResponse

<TransferTo><status_code>0</status_code><transaction_list>6115,6137,6183,6184,6204,6514,8129,8135,14888,14891</transaction_list><error_txt>Transactionsuccessful</error_txt><authentication_key>1217301496240</authentication_key><error_code>0</error_code></TransferTo>



8.3 GetatransactionIDfromagivenkey

Method get_id_from_key

ReturnstheIDofatransactionpreviouslyperformedbasedonthekeyusedintherequestatthattime.

RequestParameters








Y Mustbesetto“get_id_from_key”

from_key Integer Y Keyusedduringatransactionpreviouslyperformed,whomIDisrequested.

ResponseParameters






from_key Integer Keyusedduringatransactionpreviouslyperformed,whomIDisrequested(sameastheonespecifiedinfrom_keyre-questparameter).

id Integer IDofthetransactionyouwerelookingfor.Blankifnotfound



SampleRequest

<xml><login>your_login</login><key>1217303174266</key><md5>b70aa58d2fe87d0bb0cd2b1902e5fce2</md5><from_key>1334909705</from_key><action>get_id_from_key</action></xml>

SampleResponse<TransferTo><error_txt>Transactionsuccessful</error_txt><authentication_key>1217303174266</authentication_key><error_code>0</error_code><id>7654321</id></TransferTo>

Key used during the transaction.

Transaction ID linked to the given Key.



9.0 StandardAPIErrors

Code Text Description

0 Transactionsuccessful. IndicatestheTop-upwassuccessfullydeliveredtotherecipient.

101 DestinationMSISDNoutofrange Numberingplannotrecognized:thedestination/recipientnumberwasnotidentifiedastobelongingtoanyoperatorscoveredbyTrans-ferTo.

Re-checkrecipientnumberand/orescalatethecasetotheTransferToSupportTeamforfurtherinvestigation.

104 MSISDNinblacklist HereMSISDNreferstobothsenderandrecipientphonenumberswhichareblacklistedduetofraudulentactivities.

105 Notenoughcreditonyouraccount Transactionfailedduetoinsufficientfundsinyouraccount'sprepaidbalance.Pleasereloadbalanceandtryagain.

200 TransactioncanceledbyCustomer

202 TransactioncanceledbyTransferTo

203 Transactionincomplete Transactionfailedduetoatechnicalissue.

PleasecontactTransferToSupportTeamforfurtherinvestigation.

204 DestinationAccountisnotprepaidornotvalid

Transactionrefusedbytheoperatorbecausetherecipientphonenumberisnotavalidprepaidaccount.

207 Transactionamountlimitexceeded HerelimitreferstomaximumamountdefinedforthedestinationMSISDN.Therearesomelimitationssetontheoperator'sside,notcontrolledbyTransferTo.Whenoneoftheselimitsisreached,errorcode207willbereturned.

Someexamples:

• IndosatIndonesiaoperator'send,thecustomermustwaitatleast5minsbeforesendinganothertransfertothesamerecipientac-count.

• Indianoperators'end,thecustomermustwait3minsbeforesendinganothertransferofthesameamounttothesamerecipi-entaccount.

• OrangeAfrica,therecipientaccountislimitedtoamaximumre-chargeableamountof30Eurosperweekand60Eurospermonth.

213 Repeatedtransaction Transactionrefusedbecauseitwassubmittedtoocloselyafterapre-cedingTop-upattempt.

214 Topuprefused Transactionrefusedbytheoperatorforareasonthatwasnotspecified.

Commonreasonsforthesetypesoffailuresare:

• Recipientnumbernotvalidforrecharge.• Serviceoutagetemporarilyfacedontheoperator.Pleasetryagainatalatertimeand/orcontacttheTransferToSupportTeamiftheproblempersists.




215 Servicetothisdestinationoperatoristemporarilyunavailable

Transactionfailedduetoanoutageand/orconnectionissuewiththeoperator.

Pleasetryagainatalatertimeand/orcontacttheTransferToSupportTeamiftheproblempersists.

216 Destinationnumbernotactivated Transactionrefusedbytheoperatorbecausetherecipientnumberhasnotbeenactivated.

217 Destinationnumberexpired Transactionrefusedbytheoperatorbecausetherecipientnumberisnolongeranactiveaccount.

218 Requesttimeout Transactiontimed-outandfailedbecauseofthelongpro-cessingduration.

Pleasetryagainatalatertimeand/orcontacttheTransferToSupportTeamiftheproblempersists.

219 Keydoesnotexist Requestfailedbecausethekeyprovideddoesnotexist(errorreturnedforget_id_from_keymethodrequestsonly).

221 Fraudsuspicion Transactionrefusedandtherecipientnumberflaggedforsus-picionoffraud,duetothenumberofconsecutiveTop-upre-questswithinashortgapoftime.

TherecipientphonenumberwillbelockedoutfromreceivinganyTop-upforacertainperiodoftime,afterwhich,there-strictionwillbeautomaticallyreleased.

222 Numberbarredfromrefill Thiserrorcodeisreturnedwhentherecipienthasbeenblockedfromrefilldirectlybytherecipient'soperator.Itpre-ventsTransferTosystemfromreloadinghisaccount.

Recipientmustcalltheoperator’scustomerservicetounblockit

223 IDnotreserved TransactionfailedbecausethetransactionIDspecifiedintherequestwasnotpreviouslyreserved.

224 InvalidlengthofdestinationMSISDN

Transactionfailedbecausetherecipientnumberlengthdoesnotmatch(shorterorlonger)themobilenumberformatofthecountry.

230 Recipientreachedmaximumtopupnumber

ThiserrorisreturnedwhenarecipientreachesthemaximumnumberofTop-upallowableinacertaingapoftime.

• 01Day(s)=>10• 07Day(s)=>15• 30Day(s)=>40




231 Recipientreachedmaximumtopupamount

Thiserrorisreturnedwhenarecipientreachesthemaximumamount(inUSD)ofTop-upallowableinacertaingapoftime.

• 01Day(s)=>max100USD• 07Day(s)=>max150USD• 30Day(s)=>max200USD

232 Accountreachedmaximumtopupnumber

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumnumberofTop-upallowableinacertaingapoftime.

233 Accountreachedmaximumtopupamount

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumamount(inUSD)ofTop-upallowableinacertaingapoftime.

241 Accountreachedmaximumdailytopupamount

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumamount(inUSD)ofTop-upallowablewithinaday.

242 Accountreachedmaximumdailytopupnumber

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumnumberofTop-upallowablewithinaday.

243 Accountreachedmaximumweeklytopupamount

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumamount(inUSD)ofTop-upallowablewithinaweek.

244 Accountreachedmaximumweeklytopupnumber

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumnumberofTop-upallowablewithinaweek.

245 Accountreachedmaximummonth-lytopupamount

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumamount(inUSD)ofTop-upallowablewithinamonth.

246 Accountreachedmaximummonth-lytopupnumber

Thiserrorisreturnedwhenyouraccounthasreacheditsmax-imumnumberofTop-upallowablewithinamonth.

251 Senderreachedmaximumdailytopupamount

Thiserrorisreturnedwhenthesenderhasreacheditsmaxi-mumamount(inUSD)ofTop-upallowablewithinaday.

252 Senderreachedmaximumdailytopupnumber

Thiserrorisreturnedwhenthesenderhasreacheditsmaxi-mumnumberofTop-upallowablewithinaday.

253 Senderreachedmaximumweeklytopupamount

Thiserrorisreturnedwhenthesenderhasreacheditsmaxi-mumamount(inUSD)ofTop-upallowablewithinaweek.

254 Senderreachedmaximumweeklytopupnumber

Thiserrorisreturnedwhenthesenderhasreacheditsmaxi-mumnumberofTop-upallowablewithinaweek.

255 Senderreachedmaximummonthlytopupamount

Thiserrorisreturnedwhenthesenderhasreacheditsmaxi-mumamount(inUSD)ofTop-upallowablewithinamonth.

256 Senderreachedmaximummonthlytopupnumber

Thiserrorisreturnedwhenthesenderhasreacheditsmaxi-mumnumberofTop-upallowablewithinadaymonth.

301 Denominationnotavailable Denominationnotavailableforthisdestination.




310 Denominationblocked TransactionfailedbecausetheTop-upisnolongeravailableontheoperator'sofferorontheaccount.

311 Operatorblocked TransactionfailedbecausetheTop-upisnolongeravailableontheaccount.

312 Operatorblockedbycustomer Transactionfailedbecauseoperatorhavebeenblockedexplic-itelyincustomeraccount.

320 Requestedamountoutofrange TransactionfailedbecausetheTop-amountrequestwasnotwithintherangeofvalidamounts.

321 Requestedcurrencynotallowedforthisaccount

Transactionfailedbecausethecurrencyspecifiedisnotvalidfortheaccount.

401 TransactionIDnotfoundorwasnotmadebyyouraccount

NotransactionwasfoundwiththeIDspecified(errorreturnedfortrans_infomethodrequestsonly).

777 Insufficientbalanceinyourmasteraccount

Transactionfailedbecausetherearenotenoughfundsinyourmasteraccount.

888 Insufficientbalanceinyoursub-account

Transactionfailedbecausetherearenotenoughfundsinyoursub-account.

900 Notenoughinformationtoprocessthetopup

TransactionfailedbecausesomeoftherequiredfieldsinyourTop-uprequestaremissing/empty.

901 Invalidaction Transactionfailedbecausetheactionspecifiedin<action>fieldoftherequestisnotvalid.

902 Invalidinput_currency

903 Invalidoutput_currency

904 Invalidinput_value

905 Invalidstart_date

906 Invalidstop_date

907 InvalidtransactionID TransactionIDspecifiedinthe<reserved_id>oftheTop-uprequestisnotvalid.

908 Accountnotconfiguredforthisservice

Transactionfailedbecausetheaccountisnotconfiguredtocarryouttherequestedaction.

909 Invalidflag Transactionfailedbecausetherequestincludedaninvalidfield/parameter.

919 Allrequiredargumentnotreceived Transactionfailedbecausetherequestismissingamandatoryfield/parameter.

921 WrongMD5encoding TransactionfailedbecausetheMD5hashwasnotcorrect.Typicallyindicatesthatthepasswordisincorrect.




922 OriginatingIPnotallowed TransactionfailedbecausetherequestoriginatedfromanIPthatisnotwhitelistedfortheaccount.

923 KeyorMD5valuecannotbeempty RequestfailedbecauseKeyorMD5valuesareempty.

925 Keyalreadyusedorinvalidkeyval-ue

Requestfailedbecausethekeyvalueincludedintherequestwasnotuniquethanthepreviouskeyused.

926 Accountnotactive.PleasecontactyourAccountManager.

995 Accountnotfound.Pleaseenteranduseacorrectlogin.

998 Systemnotavailable.Pleaseretrylater.

Requestfailedduetotechnicalissues.

PleasecontactTransferToSupportTeamforfurtherinvestiga-tion.

999 Unknownerror. TobeescalatedtotheTransferToSupportTeamforfurtherin-vestigation.



10.0 Annexes10.1 SampleCodeinJAVAforMD5Generation

ThisclassgeneratestheMD5valueinJAVAlanguage.

importjava.security.MessageDigest;importjava.security.NoSuchAlgorithmException;importjava.util.GregorianCalendar;classHelloWorldApp{publicstaticvoidmain(String[]args){ Stringmd5_string=getKeyedDigest("your_login","your_token","your_key"); System.out.println(md5_string);}publicstaticStringgetKeyedDigest(Stringlogin,Stringtoken,Stringkey){try{Stringtemp=login+token+key;MessageDigestmd5=MessageDigest.getInstance("MD5");byte[]bytes=md5.digest(temp.getBytes());returnbyteToHex(bytes);}catch(NoSuchAlgorithmExceptione){System.out.println("oops");}returnnull;}publicstaticStringbyteToHex(byte[]bits){if(bits==null){returnnull;}StringBufferhex=newStringBuffer(bits.length*2);for(inti=0;i<bits.length;i++){if(((int)bits[i]&0xff)<0x10){hex.append("0");}hex.append(Integer.toString((int)bits[i]&0xff,16));}



returnhex.toString();}}

10.2 SampleCodeinPHP

https://shop.transferto.com/shop/v3/demo/api_sample.php

<?php//TransferTo//SamplecodetosendrequesttoAPI//Version1.03//7thFeb2013//TransferToaccountcredentials$login="your_login";$token="your_token";//MD5calculation$key=time();$md5=md5($login.$token.$key);//TransferToPlatform$url="https://airtime.transferto.com/cgi-bin/shop/topup";//Testdata$destination_msisdn="+628123456770";?>CheckWallet:<formname="wallet"method="post"action="<?phpecho$url;?>"><inputtype="text"name="login"value="<?phpecho$login?>"><inputtype="hidden"name="key"value="<?phpecho$key?>"><inputtype="hidden"name="md5"value="<?phpecho$md5?>"><inputtype="hidden"name="action"value="check_wallet"><inputtype="submit"value="submit"/></form>Checkadestinationnumberorgetproductsforanumber:<formname="recipient"method="post"action="<?phpecho$url?>"><inputtype="hidden"name="login"value="<?phpecho$login?>"><inputtype="hidden"name="key"value="<?phpecho$key?>"><inputtype="hidden"name="md5"value="<?phpecho$md5?>"><inputtype="text"name="destination_msisdn"value="<?phpecho$destination_msisdn?>"><inputtype="hidden"name="action"value="msisdn_info"><inputtype="submit"value="submit"/></form>



SendaTopup:<formname="topup"method="post"action="<?phpecho$url?>"><inputtype="hidden"name="login"value="<?phpecho$login?>"><inputtype="hidden"name="key"value="<?phpecho$key?>"><inputtype="hidden"name="md5"value="<?phpecho$md5?>"><inputtype="hidden"name="delivered_amount_info"value="1"><inputtype="text"name="destination_msisdn"value="<?phpecho$destination_msisdn?>"><inputtype="text"name="msisdn"value="<?phpecho$msisdn?>"><inputtype="text"name="product"value="<?phpecho$product?>"><inputtype="hidden"name="action"value="topup"><inputtype="submit"value="submit"/></form>



10.3 URLtoretrieveoperatorlogoimages

TransferToAPIoffersthepossibilitytoretrieveoperatorlogoimages.

Itisquickandeasy,youjustneedtoknowtheoperatorid.

TheURListhefollowing:https://operator-logo.transferto.com/logo-ID-SIZE.png

• IDistheoperatorid• SIZEisanintegerfrom1(smallest)to3(biggest).

TigoSample: https://operator-logo.transferto.com/logo-1529-1.png

OrangeSample: https://operator-logo.transferto.com/logo-1530-1.png

MTNSample: https://operator-logo.transferto.com/logo-1526-1.png



10.4 WebDevelopersSamples

topup.orange.com

mobilerecharge.com

paypal-mobilereload.com

m.transferto.com



prepaidunion.com

sendly.com

joxko.com

becharge.com

afri-phone.com

worldremit.com



10.5 MobileAppsDevelopersSamples

TigoRecargasTopUp

RedPocketMobileRecharge

TopUpPro-MobileRecharge

Documents

TransferTo Airtime API Document 2.8 · 8.0 Reports: Transaction ... , TransferTo currently links +4.5 billion mobile users across more than 400 mobile operators. ... Select Developer