sparrow client (front-end) api “sparrow client (front-end) api” (hereinafter referred to sca)...
TRANSCRIPT
MerchantPublicServices 2017
2 Confidential©2017SPARROW,LLC.allrightsreserved
RevisionHistory
Date Revision Comments Author
2017-05-22 1.0 Initialdocument IlyaTretyakov
MerchantPublicServices 2017
3 Confidential©2017SPARROW,LLC.allrightsreserved
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
MerchantPublicServices 2017
4 Confidential©2017SPARROW,LLC.allrightsreserved
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).
MerchantPublicServices 2017
5 Confidential©2017SPARROW,LLC.allrightsreserved
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:
:
MerchantPublicServices 2017
6 Confidential©2017SPARROW,LLC.allrightsreserved
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>
MerchantPublicServices 2017
7 Confidential©2017SPARROW,LLC.allrightsreserved
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;
...
MerchantPublicServices 2017
8 Confidential©2017SPARROW,LLC.allrightsreserved
// 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);
MerchantPublicServices 2017
9 Confidential©2017SPARROW,LLC.allrightsreserved
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) {
MerchantPublicServices 2017
10 Confidential©2017SPARROW,LLC.allrightsreserved
3DSecureVerification3-DSecureisanauthenticatedpaymentsystemtoimproveonlinetransactionsecurityandencouragethegrowthofe-commercepayments.
Theinteractionschemewithcreditcardverificationconsistoffollowingsteps:
1. Merchantsendsthe‘POST’requestfrommerchant’ssiteusingJavaScript.2. SparrowsendstomerchantresponsewithredirectURLfor3Dsecureverification.3. SparrowAPIredirectsconsumertothe3Dsecureverificationpage,whichwillopen inthepopup
window.4. Consumerpass3DsecureverificationandcardissuessendtoSparrow3Dsecureauthenticationdata.5. SparrowgenerateandsendtomerchantsiteTT.6. MerchantsendstosparrowsalerequestwithTT.7. Sparrowsendstomerchantresponsewithsaleoperationresult.
MerchantPublicServices 2017
11 Confidential©2017SPARROW,LLC.allrightsreserved
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
MerchantPublicServices 2017
12 Confidential©2017SPARROW,LLC.allrightsreserved
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