Sparrow Client (Front-end) API “Sparrow Client (Front-end) API” (hereinafter referred to SCA)...

SparrowClient(Front-end)API

ServiceAPI

Version3.6.0(Build8062)

ReleasedMay2017

MerchantPublicServices 2017

2 Confidential©2017SPARROW,LLC.allrightsreserved

RevisionHistory

Date Revision Comments Author

2017-05-22 1.0 Initialdocument IlyaTretyakov



TableofContents

RevisionHistory..........................................................................................................................................2

Vocabulary.................................................................................................................................................4

Overview....................................................................................................................................................4

InteractionScheme....................................................................................................................................5

EmbeddedForm(EF)..............................................................................................................................6

CustomForm(CF)...................................................................................................................................6

UsingEmbeddedForm(EF)........................................................................................................................6

UsingCustomForm(CF).............................................................................................................................9

3DSecureVerification..............................................................................................................................10

APIdescription.........................................................................................................................................11

EFpopupsettings.................................................................................................................................11

EFtagattributesdescription................................................................................................................12

“getToken”functiondescription(CF)...................................................................................................12



VocabularySCA SparrowClient(Front-end)APIInitialdocument

TT Payment'stemporarytoken

EF EmbeddedForm

CF CustomForm

OverviewThisguidewasmadefortechnicalstaffandotherspecialistswhomaintainsites,onlineshopsandothersources,whichprovidepaymentopportunitythroughthe"Sparrowglobalpaymentsolution".

The“SparrowClient(Front-end)API”(hereinafterreferredtoSCA)allowsmerchantstoreceivepaymentswithoutstoringpaymentinformationontheirservers(PCIDSSlicenseisnotrequired)aswellaswithoutusing "Payment Redirect". Therefore, this possibility suggests using JavaScript at the sales resource(merchant'ssite).

Important!At thecurrentversion,SCAprovidesonly thesimplecreditcardpayment,which includessuchfieldsasCreditCardNumber,Cardholder,ExpirationDateandCVV(CVC).



InteractionSchemeTheinteractionschemeconsistsoftwoconsecutiverequests,eachofwhichisdirectedintothesameserver"Sparrow".

Thefirstrequest:

• 'POST'frommerchant'ssitefront-endusingJavaScript,thesecondrequest-'POST'frommerchant'sserver-side.

• Sendspaymentinformation(creditcardnumber,cardholdername,CVVetc.)andreceivespaymenttemporarytoken(hereinafterreferredtoTT).

Thesecondrequest:

• 'POST'frommerchant'sserver-side.• MakesapaymentusingTTandotherspecialinfo.

Thefollowingschemeshowsthisinteraction:

:



HowdoesitworkThere are two differentways to use it: Embedded Form (hereinafter referred EF) and Custom Form(hereinafterreferredCF).

EmbeddedForm(EF)

SCAallowsyounottothinkabouthtml-layoutofpaymentformsandJS-logicofreceivingTT.Ifyourtaskistodrawoneormorepaymentbuttonsforeachgood(forexample)andyoudonotwanttospendyourtimeoncustomformlayout-EFisyourchoice.SCAprovidesmechanismofdrawingpaymentformbasedonitsownJavaScriptcodeandCSS"fromthebox".YourdutieswillbyonlyaddSCACSSfileonyourpagebesidesSCAJS,renderingparticulartagswith"data-"attributesaswellandmakinganAJAXfunctionforback-endlogicofpayment.YoucanalsoredefineourCSSstylesinaccordancewithyoursite’stheme.

CustomForm(CF)

Inthiscase,youhavetowriteallclientsandservers logic independently.ToobtainaTTyouuseSCAfunction“getToken”(see“APIdescription”section).

UsingEmbeddedForm(EF)1. AddfollowingJS-andCSS-filesatthe“head”ofyourpage(data-name="sparrowApi"attribute

isnecessary!):

Makesurethesefilesareloadedsuccessful.

2. Configurepaymentbuttonsatthe“body”sectionofyourpage:

<link href="https://secure.5thdl.com/clientapi/sparrow-api.css?v=1.1" rel="stylesheet" />

<script src="https://secure.5thdl.com/clientapi/sparrow-api.js?v=1.1" type="text/javascript" data-name="sparrowApi"></script>



The assignment of the attributes see at the “API description” section.“embeddedFormCode.getTokenCallback” and “embeddedFormCode.getTokenCallback2” aredefinedbelow.

3. Now let’swrite some JS-code (with comments along the text).Be careful, your customAjaxfunction forpaymentshouldreturn"Promise"object (suchas"iQuery.Deferred").Deferredobject has to involve either “done” or “then” methods. It's necessary for right "loading-animation"behaviorEF:

<div data-pkey="[Your public key]"

data-buttontext="Pay $200.4"

data-title="One thing by $200.4"

data-tokencallback="embeddedFormCode.getTokenCallback"

data-purchasebuttontext="Purchase $200.4"

data-amount="200.4">

</div>

<br />

<div data-pkey="[Your public key]"

data-buttontext="Pay €3.45"

data-tokencallback="embeddedFormCode.getTokenCallback2"

data-amount="3.45">

</div>

<script type="text/javascript">

// Configure EF if it is necessary (see “API description” section)

Sparrow.modals.disableClose = false;

...



// Embedded form code example7

var embeddedFormCode = (function () {

var embeddedFormCallback = function (response) {

Sparrow.closePopups(); // you may close popup window after purchase

// use response here

},

// User purchase function should returns Deferred object (jQuery Deferred for example)

embeddedPurchase = function (token, amount) {

return [Your Purchase function](token, amount)

.done(embeddedFormCallback);

}

// callbacks which you use at 'data-tokencallback' attributes

return {

getTokenCallback: function (token) {

return embeddedPurchase(token, 200.4);



UsingCustomForm(CF)Theexampleinvolvesonly“Sparrow.getToken”functioncall.Doitwhereyouwant.Thenusecallbackforfurtherpaymentoperation.

Sparrow.getToken([Your pkey], {

cardnum: [Buyer Card Number],

cardholder: [Cardholder],

cardexp: [Month + Year], // Format string “MMYY”

cvv: [CVC],

amount: [Amount] // Required for 3D secure verification

}, function (token) {



3DSecureVerification3-DSecureisanauthenticatedpaymentsystemtoimproveonlinetransactionsecurityandencouragethegrowthofe-commercepayments.

Theinteractionschemewithcreditcardverificationconsistoffollowingsteps:

1. Merchantsendsthe‘POST’requestfrommerchant’ssiteusingJavaScript.2. SparrowsendstomerchantresponsewithredirectURLfor3Dsecureverification.3. SparrowAPIredirectsconsumertothe3Dsecureverificationpage,whichwillopen inthepopup

window.4. Consumerpass3DsecureverificationandcardissuessendtoSparrow3Dsecureauthenticationdata.5. SparrowgenerateandsendtomerchantsiteTT.6. MerchantsendstosparrowsalerequestwithTT.7. Sparrowsendstomerchantresponsewithsaleoperationresult.



Notes:

• Please,contactadministratortoenable3Dsecureverificationfeature• Thefield‘amount’isrequiredfor3Dsecureverification.Don’tforgettoadd“data-amount”attribute

toEmbeddedform(exampleonpage7),or“amount”parameterto“data”objectforCustomForm(exampleonpage9)

• Toavoidcaching,please,usepostfixwithClientAPIcurrentversionforJS-andCSS-filesatthe“head”ofyourpage(exampleonpage6).

APIdescription

EFpopupsettings

Property Description Values Default

Sparrow.modals Object,whichstorespopupwindowbehavior

JSON

Sparrow.modals.disableClose Allows/forbidsclosingthepopup ifthetargetcontrolisdisabled

true/false false

Sparrow.modals.bgClose Allows/forbids closing the popupontobackground(overlay)click

true/false false

Sparrow.modals.escapeClose Allows/forbids closing the popupusingEscapebutton

true/false false

Sparrow.modals.fadeOutOpen Switchon/offthesimpleanimationduringthepopupwindowopening

true/false true



EFtagattributesdescription

Attribute Description Default Required

data-pkey MerchantPublicKey yes

data-buttontext Caption on the button which openspopupwindow

Purchase no

data-title Thetitleofthepopupwindow Purchase no

data-purchasebuttontext Captiononthepurchasebutton Purchase no

data-amount Purchase amount, required for 3Dsecureverification

Onlyfor3Dsecure

verification

data-tokencallback Callback function that will be calledafterreceivingthetoken.

Has to return Promise(jQuery.Deferredforexample)

yes

“getToken”functiondescription(CF)

Parameter Description Required

pkey MerchantPublicKeystring yes

data JSONobject–datawhichwillberequiredforpaymentholding

yes

success Successfunctionthatwillbecalledafterreceivingthetoken

yes

error Errorfunctionthatwillbecallediftheerrorappears no

complete Complete function. It will be called after the ajaxrequestfinishanyway

no

Sparrow Client (Front-end) API “Sparrow Client (Front-end) API” (hereinafter referred to SCA)...

Documents

Transcript of Sparrow Client (Front-end) API “Sparrow Client (Front-end) API” (hereinafter referred to SCA)...