iOS

integrating ios with judopay we are currently working on updating the swift sample app see our sample apps here prerequisites you have set up your judopay account sign up for your sandbox account , to receive access to your judopay dashboard and the sandbox environment your judoids and tokens are configured and enabled as appropriate for more information on permissions, see introduction docid\ s 8hoamytkgy13t0p657 you have the latest version of the ios sdk for mobile apps, we recommend using payment session authentication integrating via swift package manager (spm) search for judokit ios add judokit ios to your package dependencies integrating via cocoapods step one to integrate the ios mobile sdk via cocoapods install cocoapods with the following command gem install cocoapods via the terminal, navigate to your project's root directory initialize cocoapods with the following command pod init a podfile is generated in the root directory step two to add the mobile sdk as a dependency open the podfile and add the following pod 'judokit ios' install the dependency with the following command pod install the pod installation complete! message appears in the terminal if the unable to find a specification error message appears, your cocoapods repository, which stores a reference to all available pods, needs updating to update your cocoapods repository run $ pod repo update ensure you always use the generated xcworkspace file instead of the xcodeproj file integrating via carthage to integrate the ios mobile sdk via carthage install carthage on your machine using brew (terminal) brew install carthage in the root folder of your project, add a new file named cartfile in cartfile, add all the dependencies you need for the purpose of this exercise github "judopay/judokit ios" in the terminal run the following command carthage update use xcframeworks platform ios check your root folder has the following cartfile resolved (file with all downloaded dependencies, including their versions) carthage folder in xcode, manually drag and drop the judokit ios xcframework and all the dependent xcframeworks into linked frameworks libraries section frameworks are stored in folder carthage > build rebuild the project import the judokit ios into your project files #import \<judokit ios/judokit ios h> the ios mobile sdk is now ready to use in your ios project initialising a judokit session to get started to access the judokit class, import the judokit ios framework #import \<judokit ios/judokit ios h> to initialise a judokit session the difference between a basic authentication method and a session authentication method is basic authentications last indefinitely session authentications are valid for one transaction this offers a more secure authentication approach use either a basic (token\ secret) authentication method, or a session (token & session) authentication method create a basic authentication instance jpbasicauthorization authorization = \[jpbasicauthorization authorizationwithtoken @"token" andsecret @"secret"] create a payment session authentication instance jpsessionauthorization authorization = \[jpsessionauthorization authorizationwithtoken @"token" andpaymentsession @"session token"] to create a judokit session judokit judo = \[\[judokit alloc] initwithauthorization\ authorization]; to communicate with the sandbox environment, enter judo issandboxed = yes; by default, judopay allows jailbroken devices to access it's features if you would like to restrict access to non jailbroken devices only, use this initializer instead judokit judo = \[\[judokit alloc]initwithauthorization\ authorization "allowjailbrokendevices\ no]; setting the parameters for a successful transaction use the jpconfiguration object to set the parameters the jpconfiguration object is passed as a method parameter and communicates how the payment flow should behave to configure the jpconfiguration object, add your judoid judoid format = 100100100 amount consumerreference jpamount myamount; jpreference myreference; jpconfiguration myconfiguration; myamount = \[\[jpamount alloc] initwithamount @"0 01" currency @"gbp"]; myreference = \[\[jpreference alloc] initwithconsumerreference @"my reference"]; myconfiguration = \[jpconfiguration alloc] initwithjudoid @"my judo id" amount\ myamount reference\ myreference]; the jpamount object sets your transaction amount currency code the jpreference object sets your reference details, for example your unique consumerreference , to identify your consumer now you can use this object to make a transaction making a transaction 3d secure 2 is available on judokit ios version 3 0 0 or higher, and is available on github (currently supports visa and mastercard amex coming soon) prerequisites you have integrated with the ios docid 09p1cru0cbxjkzea 0zpi you have set up the jpconfiguration instance with all the required properties card validation | card formatting | type | detection | is handled by judopay the available transaction types that can be passed as a parameter are payment preauth check card save card for more details, see our transaction api reference documentation once you have completed the prerequisite steps, you are ready to make a transaction to make a transaction call the method and handle the response from the completion block \[judo invoketransactionwithtype\ transactiontypepayment configuration\ configuration completion ^(jpresponse response, jperror error) { // handle response / error }]; name type description type transactiontype an enum value that sets the transaction type configuration jpconfiguration an object that configures the payment flow completion jpresponse jperror a completion block that returns the transaction response or an error user interface pre built ui component (recommended) if you are using the pre built ui component provided with our sdk, see ios docid 09p1cru0cbxjkzea 0zpi to configure the fields displayed in the default card entry ui, see customisation docid\ prt4f78qmrsju1ghjawgm custom ui component if you are building your own custom ui component , see ios docid 09p1cru0cbxjkzea 0zpi ios server to server transactions the sdk also offers server to server capabilities this works by sending the payment token back to the merchant the moment the consumer presses the pay button this allows the merchant to process and complete the transaction on their side server to server capabilities are available for both transactions made through the payments widget apple pay™ to specify a server to server transaction server to server example //set the transactionmode to transactionmodeservertoserver when calling the judopay methods \[judo invokepaymentmethodscreenwithmode\ transactionmodeservertoserver configuration\ configuration completion ^(jpresponse response, jperror error) { // handle the payment token returned from the response }]; //specify an apple pay™ transaction \[judo invokeapplepaywithmode\ transactionmodeservertoserver configuration\ configuration completion ^(jpresponse response, jperror error) { // handle the payment token returned from the response }]; token payments and preauths if you are building your own card wallet, and not using a ui you can make a /payments or /preauths transaction using a stored card token follow the steps for ios docid 09p1cru0cbxjkzea 0zpi to make a token transaction token transaction request //call the method and handle the response from the completion block \[judo invoketokentransactionwithtype\ jptransactiontypepayment configuration\ configuration details\ cardtransactiondetails completion ^(jpresponse response, jperror error) { // handle response / error }]; using the pre built ui card entry component (recommended) the easiest way to integrate 3d secure is to use the pre built ui component within judokit, as this handles the 3d secure flow for you using a 3d secure enabled credential, follow the steps for ios docid 09p1cru0cbxjkzea 0zpi we recommend using billingaddress and emailaddress fields for 3d secure 2 transactions pre built card entry ui jpamount amount = \[\[jpamount alloc] initwithamount @"1 50" currency @"gbp"]; jpreference reference = \[\[jpreference alloc] initwithconsumerreference @"consumer reference" paymentreference @"payment reference"]; jpuiconfiguration uiconfiguration = \[jpuiconfiguration new]; // sets whether 3ds 2 0 ui billing information screen should be presented to the user uiconfiguration shouldaskforbillinginformation = yes; // in case you don't want to present billing info screen to the user, you can set the address instead jpaddress address = \[\[jpaddress alloc] initwithaddress1 @"my house" address2 @"my street" town @"my town" billingcountry @"826" postcode @"tr14 8pa" countrycode @826]; jpconfiguration configuration = \[\[jpconfiguration alloc] initwithjudoid @"my judo id" amount\ amount reference\ reference]; configuration uiconfiguration = uiconfiguration; configuration cardaddress = address; // sets the value for challenge request indicator, // possible values // // nopreference // nochallenge // challengepreferred // challengeasmandate // configuration challengerequestindicator = @"challengeasmandate"; // sets the value for sca exemption, // possible values // // lowvalue // securecorporate // trustedbeneficiary // transactionriskanalysis // configuration scaexemption = @"lowvalue"; // email address configuration emailaddress = @"email\@me com"; // sets the maximum timeout for 3ds 2 0 transactions in minutes, // always use 2 characters when setting the timeout configuration threedstwomaxtimeout = 30; // sets phone number country code configuration phonecountrycode = @"44"; // phone number configuration mobilenumber = @"11223344556677"; using your own custom card entry ui you can implement a customisable ui layer, to replace the ios docid 09p1cru0cbxjkzea 0zpi provided with judopay's ios sdk this customisation does not extend to the 3d secure 2 flow, which remains unchanged and cannot be currently over ridden prerequisites from the integrating ios with judopay guide, you have completed the following ios docid 09p1cru0cbxjkzea 0zpi ios docid 09p1cru0cbxjkzea 0zpi with all the required properties setting up your custom card entry ui step one initiate the jpcardtransactionservice initiate transactionservice jpcardtransactionservice transactionservice = \[\[jpcardtransactionservice alloc] initwithauthorization\ self authorization issandboxed\ false andconfiguration\ self configuration]; step two initiate a jpcardtransactiondetails object populate the object with the necessary card details these are the details you wish to capture in your custom ui layer initiate object jpcardtransactiondetails cardtransactiondetails = \[jpcardtransactiondetails new]; cardtransactiondetails cardnumber = @"4976350000006891"; cardtransactiondetails cardholdername = @"john smith"; cardtransactiondetails expirydate = @"12/25"; cardtransactiondetails securitycode = @"123"; ( ) // other transaction details (e g billing address) use one of the following methods on the cardtransactionservice instance to initiate the following transaction types invokepaymentwithdetails invokepreauthpaymentwithdetails invokecheckcardwithdetails invokesavecardwithdetails processing a payment call the invokepaymentwithdetails method and handle the response from the completion block invokepayment \[self transactionservice invokepaymentwithdetails\ cardtransactiondetails andcompletion ^(jpresponse response, jperror error) { // handle the transaction result (including error case) here }]; processing a pre authorisation call the invokepreauthpaymentwithdetails method and handle the response from the completion block invokepreauthpayment \[self transactionservice invokepreauthpaymentwithdetails\ cardtransactiondetails andcompletion ^(jpresponse response, jperror error) { // handle the transaction result (including error case) here }]; performing a check card request call the invokecheckcardwithdetails method and handle the response from the completion block invokecheckcard \[self transactionservice invokecheckcardwithdetails\ cardtransactiondetails andcompletion ^(jpresponse response, jperror error) { // handle the transaction result (including error case) here }]; performing a save card request call the invokesavecardwithdetails method and handle the response from the completion block invokesavecard \[self transactionservice invokesavecardwithdetails\ cardtransactiondetails andcompletion ^(jpresponse response, jperror error) { // handle the transaction result (including error case) here }]; adding payment methods before you can process apple pay™ payments with judopay, you will need to set up apple pay™ setting up apple pay for ios apple pay™ is not supported on all apple devices before invoking any apple pay™ functionality within your app, test if it is supported on the device by performing these checks use pkpaymentauthorizationviewcontroller canmakepayments checks if the device supports apple pay™ and has it enabled queries both the device hardware and whether apple pay™ is enabled in the user’s region use pkpaymentauthorizationviewcontroller canmakepaymentsusingnetworks a more detailed check to query whether a user has a registered card with particular card schemes useful if you do not accept all card types both methods are explained in the apple developer documentation here getting your apple pay™ account system requirements a compatible apple device iphone 6 & 6 plus | ipad air 2 | ipad mini 3 | or newer ios 12 0 or newer xcode 14 0 or newer create a merchant id we recommend creating a merchant id for each merchant (i e business) accepting payments within your app to set up your apple pay™ account access your apple developer account navigate to certificates, identifiers & profiles from the side menu, click merchant ids in the ios merchant id settings screen, click the add button set your merchant id the identifier you enter should be a reverse dns style identifier prefixed with the word click done create an apple pay™ certificate prerequisite request a certificate signing request (csr) file from judopay when you’ve received your csr, you can create your apple pay™ certificate to create your apple pay™ certificate from the side menu, select either certificates > all merchant id the screen appears describing how to manually create your certificate signing request (csr) as you’ve already obtained your csr from judopay, click continue you will be prompted to state if you are processing transactions outside the united states select no click continue click choose file to upload the csr file provided by judopay click generate the confirmation screen appears your certificate is ready to download click download click done to complete your apple pay™ set up send the certificate to judopay once received, we will add the certificate to your account and confirm it has been added apple certificates expire just over two years after generation for example a certificate generated on 13th may 2024 will expire on the 11th june 2025 refer to your apple developer account for an accurate expiry date to generate a new certificate follow the steps above set up apple pay™ entitlement apple pay™ is built into the passkit framework, which means you will need to configure the entitlement to set up the entitlement select your build target select capabilities set the entitlement to enabled add the merchant id created earlier to the app you may need to refresh the list open the entitlements file to confirm the merchant id has been added to your app your account is now ready to process apple pay™ payments with judopay configure the ios docid 09p1cru0cbxjkzea 0zpi to start making payments apple pay™ button apple pay™ allows the consumer to bypass the standard checkout flow complete their payment with speed when integrating with apple pay™, it is recommended to consider when to introduce the apple pay™ button this can be on a single item product listing page within a basket page with multiple items both of the above scenarios the apple pay™ button enables consumers to make a purchase from the specific page they are browsing by tapping the apple pay™ button, the payment sheet is invoked to begin the checkout process for more information on the apple pay™ button, see apple’s guidance of the pkpaymentbutton class reference best practice testing you can test apple pay™ in the sandbox environment with the sandbox cards, however please note these test transactions will not work going upstream to test apple pay™ transactions, point to the live environment and use live cards we recommend performing | pre authorizations | card payments | full refunds via the judopay dashboard > history , or via an api call we strongly recommend testing apple pay™ through each of these scenarios before you release the app unsupported device use a non supported device in order to verify the whole recognition workflow works as expected card not supported use a card issued by a bank that does not support apple pay™ you can also use the test cards provided on the judopay dashboard to validate the error returned and expected behaviour payment cancelled cancel a transaction in process and see the results in the app and in your judopay dashboard history poor / loss of connection while a transaction is being processed, disconnect the internet connection to see if the app responds as expected configuring apple pay for ios to configure apple pay™ add the apple pay™ configuration call the apple pay™ method step one adding the apple pay™ configuration all judo transactions require a jpconfiguration instance passed as a method parameter the basic jpconfiguration requires judo id amount consumer reference apple pay™ transactions require additional parameters in order to work correctly to set all the apple pay™ required parameters, use the jpapplepayconfiguration nsdecimalnumber itemoneprice = \[nsdecimalnumber decimalnumberwithstring @"649 99"]; nsdecimalnumber itemtwoprice = \[nsdecimalnumber decimalnumberwithstring @"55 00"]; nsdecimalnumber totalprice = \[nsdecimalnumber decimalnumberwithstring @"704 99"]; nsarray mysummaryitems = @\[ \[jppaymentsummaryitem itemwithlabel @"iphone xr 254gb" amount\ itemoneprice], \[jppaymentsummaryitem itemwithlabel @"iphone xr case" amount\ itemtwoprice], \[jppaymentsummaryitem itemwithlabel @"apple store" amount\ totalprice], ]; for each item you wish to list, you will need to sum up the item in the basket payment summary items this is a list of jppaymentsummaryitem objects, that describe the item being purchased, including the price in the example above, the item label was set to the merchant from where the item was purchased this is how the jpapplepayconfiguration looks nsarray mysummaryitems jpapplepayconfiguration applepayconfig; applepayconfig = \[\[jpapplepayconfiguration alloc] initwithmerchantid @"my merchant id" currency @"gbp" countrycode @"gb" paymentsummaryitems\ mysummaryitems ]; parameter description merchantid nsstring your apple pay™ merchant id this confirms you are able to accept payments currency nsstring an iso 4217 currency code countrycode nsstring an iso 3166 1 alpha 2 country code paymentsummaryitems nsarray the list of items the last item in the array should always represent the total amount step two add the instance to the object add the jpapplepayconfiguration instance to the jpconfiguration object configuration applepayconfiguration = applepayconfig; call the judo method invoke apple pay™ by providing the transactionmode this allows you to select payment or, preauth set the apple pay™ configuration \[judo invokeapplepaywithmode\ transactionmodepayment configuration\ myapplepayconfiguration completion ^(jpresponse response, jperror error) { // handle response or error }]; displaying apple pay for ios to display apple pay™ as a payment method configure the jpapplepayconfiguration object from the jpconfiguration already created, call \[\[judo invokepaymentmethodscreenwithmode\ transactionmodepayment configuration\ configuration completion ^(jpresponse response, jperror error) { // handle the response and error }]; in the example, the transactionmode is set as the first method parameter adding the billing and shipping details if you would like the consumer to provide their billing and shipping details, set the following properties requiredbillingcontactfields requiredshippingcontactfields you can choose between multiple contact field types email address phone number post code for example applepayconfig requiredbillingcontactfields = jpcontactfieldname | jpcontactfieldemail; applepayconfig requiredshippingcontactfields = jpcontactfieldall; parameter description jpcontactfieldname consumer's name jpcontactfieldemail consumer's valid email address jpcontactfieldphone consumer's valid phone number jpcontactfieldpostaladdress consumer's postal address jpcontactfieldall all the values above if you set shipping details as a required field, you must also set the shippingtype and the shippingmethods properties to set the shipping type applepayconfig shippingtype = jpshippingtypedelivery; parameter description jpshippingtypeshipping shipping the default value jpshippingtypedelivery delivery jpshippingtypestorepickup store pickup jpshippingtypeservicepickup service pickup setting the shipping methods requires an array of paymentshippingmethod objects to set an array of paymentshippingmethod objects nsdecimalnumber deliverycost = \[nsdecimalnumber decimalnumberwithstring @"25 0"]; paymentshippingmethod delivery; delivery = \[\[paymentshippingmethod alloc] initwithidentifier @"delivery" detail @"deliver to your address" label @"delivery" amount\ deliverycost]; applepayconfig shippingmethods = @\[delivery]; getting the billing and shipping details to get the billing and shipping information back from the consumer set the returnedcontactinfo applepayconfig returnedcontactinfo = returnedinfobillingcontacts; parameter description jpreturnedinfobillingcontacts billing details returned the default value jpreturnedinfoshippingcontacts shipping details returned jpreturnedinfoall billing and shipping details returned apple pay recurring payments judopay provides support for apple pay™ recurring payments this feature enables merchants to utilise the apple pay™ recurring payment token , by also being able to use the token for merchant initiated transactions (mits) the apple pay™ recurring payment token is generated by apple pay's servers and sent to judopay, where it is securely stored in return, you will receive a judopay token that is linked to the stored apple pay™ token this judopay token can then be used for future mits for more information on mits, see merchant initiated transactions docid\ ek1dldo8cgr9di226zlyf you are responsible for initiating merchant initiated transactions setting up the apple pay™ transaction for recurring payments to use the apple pay™ recurring payments feature, begin with an initial apple pay™ transaction with these additional steps attach the recurring payment configuration object recurringpaymentrequest to your ios docid 09p1cru0cbxjkzea 0zpi recurring payment request // create the regular billing item jprecurringpaymentsummaryitem regularbilling = \[jprecurringpaymentsummaryitem itemwithlabel @"premium music subscription" amount @9 99 intervalunit\ nscalendarunitmonth intervalcount 1 startdate\ nil andenddate\ nil]; // create the recurring payment request configuration object nsurl managementurl = \[nsurl urlwithstring @"https //example com/manage subscription"]; jprecurringpaymentrequest request = \[jprecurringpaymentrequest requestwithpaymentdescription @"monthly subscription for premium music service" regularbilling\ regularbilling andmanagementurl\ managementurl]; request billingagreement = @"by subscribing, you agree to monthly billing of £9 99 for the music service until canceled "; // assign the recurring payment request to the apple pay configuration applepayconfiguration recurringpaymentrequest = request; jprecurringpaymentrequest name type description paymentdescription nsstring (non null / required) provide a description of the recurring payment this will be displayed in the payment sheet to the consumer regularbilling jprecurringpaymentsummaryitem (non null / required) the regular billing cycle for the recurring payment includes start date end date an interval an interval count managementurl nsurl (non null / required) a url to a web page where the consumer can update or delete the payment method for the recurring payment note it is best practice to use a universal link for this url the same link can direct the consumer to either a page in the app (if the app is installed), or to a page on the merchant’s website for more information on adopting universal links, see universal links billingagreement nsstring (nullable / optional) maximum string length = 500 characters a localised billing agreement this agreement is displayed via the payment sheet to the consumer before they authorise the payment note this string can include information on the recurring payment amount recurring intervals other payment conditions information on how the consumer can cancel payments this string is not intended to replace any payment terms that you provide outside of the apple pay™ payment sheet the apple pay™ payment sheet displays the text of the billingagreement string for long billingagreement strings that can not fit on the payment sheet, these will appear truncated with an ellipsis consumers can select the billing details on the payment sheet to read the full text jprecurringpaymentsummaryitem name type description label nsstring (non null / required) a short, localised description of the item note provide the label in title case for example vat tax gift wrap and card discount ensure you omit any punctuation and whitespace after the label the label is formatted for display by the framework amount nsdecimalnumber (non null / required) the amount of the summary item to specify the currency, set a value for the currency property on the apple pay configuration object intervalunit nscalendarunit (non null / required) the amount of time in calendar units that represents a fraction of the total payment interval the supported nscalendarunit intervalunits are minute hour day month year intervalcount nsinteger (non null / required) the number of interval units that make up the total payment interval startdate nsdate (nullable / optional) the date of the first payment the default value is nil which requests the first payment as part of the initial transaction enddate nsdate (nullable / optional) the date of the final payment the default value is nil which specifies no end date the above configuration object property descriptions are extracts from the apple developer documentation for a full description on all the object properties, see the apple pay documentation 2 to initiate a series of scheduled / recurring payments, set the initialrecurringpayment flag in the judopay configuration object to true initialrecurringpayment true jpconfiguration configuration = \[\[jpconfiguration alloc] initwith …]; ( ) configuration isinitialrecurringpayment = yes; if you plan to use the judopay token for unscheduled / ad hoc mit transaction(s) in the future, leave the initialrecurringpayment flag = false (default) going live with ios point to the live environment in viewcontroller delete the line that specifies the targeted environment judo sandboxed = yes; replace your sandbox api token and secret for the live api token and secret find these in judopay portal > your apps > { app name } > live tokens test live payments use the live environment for testing before deploying your app ensure the sdk is properly configured for the live environment use real debit or credit cards test cards provided will not work in live we recommend to perform pre authorizations followed by a void, or regular payments followed by a refund send a refund through the judopayportal > history test all payment scenarios and security features to verify the expected behaviour follow our suggested guidelines to simulate both positive / happy path scenarios, and negative scenarios in the sandbox environment to test your integration is working correctly this will give you confidence for when your integration goes live see testing ios sdk card payments docid 9t9c80adjpmu0baiys7sk testing apple pay™ wallet via mobile sdk docid\ hyanzim115id6dabs bkp