blob: 787536fcde37579c0bc47551af40da7154a1c58a [file] [log] [blame]
"name": "DotPaySDK",
"version": "2.0.0-beta1",
"summary": "DotPay SDK",
"description": "# DotPaySDK\n![SDK logo](logo.png)\n\n# Latest stable Version: \n[![](]( \"Download\")\n\n\n### Technical manual for developers: [PDF](\n\n\n---------------------------\n## old version description\n\nSDK (iOS) Version 1.0.3\n\n![SDK screenshots](screen.png)\n\n\n## Introduction\nSet of software development tools (SDK library) that allows to integrate merchant’s mobile application with Dotpay payment system.\nThanks to devolving as many steps from our web application as possible to mobile application, the payment process is more convenient for a user and a developer obtains more control over it.\nThere is an option to modify vizualization style of SDK (colors, fonts) to have best integration possible with merchant’s mobile application.\nThe SDK library was created in language Objective-C. It supports iOS version 8.0 and higher.\n\n# How to get started\n\ninstall via [CocoaPods](\n\n```obj\npod 'DotPaySDK'\n```\n\n### Classic\n \nYou have to add the SDK to a project and initialize it in a proper way to use it. Details of these steps were described in next chapters.\nIn order to make it easier to start with SDK, we deliver a test application, available in example sub-directory. Project settings\n\n- The Dotpay framework has to be added to a project. It is located in lib sub-directory (in the bookmark Build Phases please select section Embed Frameworks).\n- The JavaScriptCore framework has to be added to the project.\nThe header file has to be imported to every place that uses SDK:\n\n```objc\n#import <DotPaySDK/DotPaySDK.h> \n```\n\n### System selection\nThe SDK library may communicate both with Dotpay production and test environment. SDK library works in production version by default.\nIn order to select the test system, you need to follow the instruction:\n\n```objc\n [DotPay sharedInstance].debugMode = YES;\n```\n\nIn order to select the production system, you need to follow the instruction:\n\n```objc\n [DotPay sharedInstance].debugMode = NO;\n```\n\n### Payment process\nThe payment process consists of displaying controller `DPDotPayViewController` and awaiting calling out a delegate method that returns control.\nThe SDK library will guide the client through the process of selecting payment channel, passing on/verification client’s data, selecting extra options, accepting proper terms of use and finalizing the payment process.\nIn the event of paying for real goods, payment status received from SDK is just informational, a right order status will be delivered in the backend system according to Dotpay technical manual.\nIn next chapters there are described steps required to use payment controllers and extra options that enable adjusting payment process to own needs.\n\n### Preparing return delegate\nPreparing payment process starts from preparing delegate\n`DPDotPayViewControllerDelegate:`\n\n```objc\n-(void) dotpayViewController: (DPDotPayViewController*)viewController didFinishPaymentWithSummary: (DPPaymentSummary *)paymentSummary;\n-(void) dotpayViewController: (DPDotPayViewController*)viewController didFailToFinishPaymentWithError: (NSError *)error\n```\n\n### Initializing payment process\nA payment description has to be prepared to start the payment process. An instance of a class DPPaymentInfo has to be created and filled out with data described in the table below:\n\n| | |\n|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| merchantID | Type: `NSString` Merchant's ID number in Dotpay system |\n| amount | Type: `NSDecimalNumber` Order amount |\n| textDescription | Type: `NSString` Order description |\n| currency | Type: `DPCurrency` Default value: „PLN” It describes currency of parameter amount. In the chapter Available currencies we,described a way how to download available currency list |\n| senderInformation | Type: `NSDictionary` Default value: nil Additional information on client, e.g. name, surname, email...,Keys:,“firstname”; “lastname”; “email”; “phone”; “street\"; “street_n1” – building number; \"street_n2\" – flat number; \"postcode\"; \"city\"; \"country\" (3 letters ISO3166).,These values are not mandatory. We recommend to pass on at least name, surname and email. The payment form should be filled out with that type of data. SDK will ask a client for missing data.,Specific explanation of these fields is described in Dotpay technical manual. |\n| additionalInformation | Type: `NSDictionary` Default value: nil Extra parameters handed over in a payment process in accordance with additional technical manuals. |\n| Control | Type: `NSString` Default value: nil The parameter that defines a payment, handed over in payment confirmation, which is sent to a Shop. This parameter is required to match a payment status to an appropriate order in a Shop.,More information you will find in the Dotpay technical manual. If not set, it’s generated by SDK. ATTENTION,To have properly working payment history, this parameter should be unique for every order. |\n| urlc | Type: `NSString` Default value: nil URL address used for receiving payment information (order completed or rejected).More information you will find in the Dotpay technical manual. |\n\n\n\n# Example:\n\n```objc\nDPPaymentInfo *info = [[DPPaymentInfo alloc] init];\ninfo.currency = [DPCurrency currencyWithCode:@\"PLN\"];\ninfo.amount = [NSDecimalNumber decimalNumberWithString:@\"100.0\"];\ninfo.merchantID = @\"10000\";\ninfo.textDescription = @\"Some description\";\ninfo.senderInformation = @{@\"firstname\": @\"Jan”, @\"surname\": @\"Kowalski”,\n@\"email\": @\"\"};\ninfo.additionalInformation = @{@\"id1\": @\"12345”, @\"amount1\": @\"40”, @\"id1\": @\"67890”, @\"amount2\": @\"60\"};\n```\n\nThe next step is downloading channels list by means of one of the following methods, passing on transaction details:\n- downloads all channels\n\n```objc\n[[DotPay sharedInstance] getChannelListForPaymentInfo:info withCompletion:^(NSArray *channelList, DPPaymentDetails *paymentDetails, NSError *error) { }]\n```\n\n- downloads channels that are currently online/offline\n\n```objc\n[[DotPay sharedInstance] getChannelListForPaymentInfo:info online:online withCompletion:^(NSArray *channelList, DPPaymentDetails *paymentDetails, NSError *error) { }]\n```\n\n- downloads channels according to ID\n\n```objc\n[[DotPay sharedInstance] getChannelListForPaymentInfo:info withIds:ids withCompletion:^(NSArray *channelList, DPPaymentDetails *paymentDetails, NSError *error) { }]\n```\n\n- downloads channels of given types\n\n```objc\n[[DotPay sharedInstance] getChannelListForPaymentInfo:info group:group withCompletion:^(NSArray *channelList, DPPaymentDetails *paymentDetails, NSError *error) { }]\n```\n\nAt the end a controller in the main thread is presented asynchronous and the following operations are executed:\n\n* Initializing payment controller with channels list and payment details\n* Optional last selected channel shutdown (this option is turned on by default)\n* Set a return delegate\n* Display a controller\n\n## Example:\n\n```objc\n__weak typeOf(self) weakSelf = self;\ndispatch_async(dispatch_get_main_queue(), ^{\n DPDotPayViewController *dotPayViewController =\n [[DPDotPayViewController alloc] initWithPaymentChannelList:channelList\n paymentDetails:paymentDetails];\n dotPayViewController.useLastChannelSelection = NO;\n dotPayViewController.paymentControllerDelegate = weakSelf;\n [weakSelf presentViewController:dotPayViewController animated:YES\n completion:NULL];\n}); }];\n```\n\n## Finalizing payment process\n\nA correctly finalized payment process is signalized by a proper delegate method.\nIn the event of successful payment process, the method `dotpayViewController:didFinishPaymentWithStatus` is called out. The argument of this method is the class `DPPaymentSummary` object, that holds payment details.\n\nIf the payment process finishes with an error, the `dotpayViewController:didFailToFinishPaymentWithError:` method will be called out with argument, which is an error description.\n\n# ATTENTION!\nA finalized payment process with a success doesn’t mean the payment was processed, but it means the payment had no errors. A payment result will be returned in an appropriate event parameter.\nExamples of event handlers:\n\n```objc\n-(void) dotpayViewController: (DPDotPayViewController *)viewController didFinishPaymentWithSummary: (DPPaymentSummary *)paymentSummary {\n if([paymentSummary.type isEqualToString: kDPPaymentSummaryStatusCompleted]) {\n // payment successful\n } else if ([paymentSummary.type isEqualToString: kDPPaymentSummaryStatusRejected])\n {\n // payment rejected\n } else {\n payment is being processed\n }\n}\n-(void) dotpayViewController: (DPDotPayViewController *)viewController didFailToFinishPaymentWithError: (NSError *)error {\n //payment error\n}\n```\n \n## Available currencies\nA list of currencies supported by Dotpay can be downloaded by the following method of PaymentManager:\n\n```objc\n[[DotPay sharedInstance] getCurrencyListWithCompletion:^(NSArray *currencyList, NSError *error){\n}];\n```\n\n### Changing presentation style\nIn order to change presentation style of controls element in a payment process the `UIAppearance` has to be used.\nUsing the appearanceWhenContainedIn system control method, presentation changes may be limited only to specific payment controllers:\n- `DPPaymentChannelsViewController` – channel selection controller\n- `DPPaymentFormViewController` – Payment form controller. This controller is not available for developer,so that to use it the *NSClassFromString* is required `NSClassFromString(@”DPPaymentFormViewController”)`\n- `DPPaymentSummaryViewController` – confirmation page controller\n \n\n### Personal channel selection control\nSDK library enables replacing default channel selection control, to adjust needs of Merchant’s shop. The following steps are required to use this possibility:\n1. Prepare an object of the DPPaymentDetails class and fill it out with data (in accordance with aforementioned chapter Payment initialization)\n2. Download channels list (channels, in which we are not interested may be deleted) along with downloading payment details:\n\n```objc\n[[DotPay sharedInstance] getChannelListForPaymentInfo:info withCompletion:^(NSArray *channelList, DPPaymentDetails *paymentDetails, NSError *error) { }\n```\n\n3. At the end a controller in the main thread is presented asynchronous:\na. Initializing personal payment controller with channels list and payment details\nb. Initializing the DPDotPayViewController payment controller with indicating personal channel payment controller\nc. Setting a return delegate\nd. Displaying Dotpay payment controller\n\n#### Example:\n\n```objc\ndispatch_async(dispatch_get_main_queue(), ^{\n MyCustomChannelViewController *myChannelViewController = [[MyCustomChannelViewController alloc] initWithPaymentChannelList:channelList ];\n DPDotPayViewController *paymentViewController = [[DPDotPayViewController alloc] initWithPaymentChannelSelectionController: myChannelViewController paymentDetails:paymentDetails];\n paymentViewController.paymentControllerDelegate = self;\n [self presentViewController:paymentViewController animated:YES completion:NULL];\n});\n```\n\n### Special channels support\n\nExtra functions related to special payment channels are described.\n\n#### Credit card payment - 1Click\n1Click functionality enables quick payment process with a saved credit card. Basic credit card data are saved in Dotpay system, while CVV is saved in SDK library (after proper encoding).\nThis functionality (if available in Merchant’s shop) is turned on by default in SDK. A client’s consent is also required to use 1Click (while filling out the payment form).\nIn order to turn off 1Click, the following command is required:\n\n```objc\n[DPOneClickManager sharedInstance].enabled = NO;\n```\n\nIn order to turn off only CVV saving, the following command is required:\n\n```objc\n[DPOneClickManager sharedInstance].cvvStoreEnabled = NO;\n```\n\n### ATTENTION\nAfter turning off aforementioned options, formerly saved credit card data is not removed. To remove that data, the following commands are required.\nAn additional Developer’s duty is to create an option to remove saved credit card data. To find out, if credit card data are saved, the following command is required:\n\n```objc\n[[DPOneClickManager sharedInstance] isDataAvailable];\n```\n\nThe following method removes credit card data:\n\n```objc\n[[DPOneClickManager sharedInstance] clearData];\n```\n\nExecuting this method removes credit card number from Dotpay system and data stored locally.\nThe option of removing only CVV number is also available. In order to check, if CVV is stored locally, the following method is required:\n\n```objc\n[[DPOneClickManager sharedInstance] isCVVDataAvailable];\n```\n\nIn order to remove CVV number only, the following method is required:\n\n```objc\n[[DPOneClickManager sharedInstance] clearCVVData];\n```\n\n\n### Transaction history and status\n\nSDK library offers saving and displaying transaction history. The transaction history also displays related operations, e.g. subsequently made refunds and other additional operations.\nThe use of built-in control\nIn order to use built-in history control, the DPPaymentHistoryController controller has to be initialized and displayed:\n\n```objc\nDPPaymentHistoryController *historyController = [[DPPaymentHistoryController alloc] initWithPaymentHistory:nil];\n[self presentViewController:historyController animated:YES completion:NULL];\n```\n\n### Changing presentation style\n\nA change of presentation way of controls elements in payment process is made with a use of the UIAppearance framework. Detailes are described in the chapter A change of presentation style.\nA history controller, for which presentation change limitations may be applied to is `DPPaymentHistoryController`.\n\n#### Example:\n\n```objc\n[[UIView appearanceWhenContainedIn: [DPPaymentHistoryController class], nil] setBackgroundColor:[UIColor redColor]];\n```\n\nPersonal history control\nSDK library offers creating personal history control by downloading only data from the library, to better match web shop specification\nThe downloading payment history data is available in the paymentHistory attribute of singleton DPPaymentHistory:\n\n```objc\nNSArray *paymentSummaries = [DPPaymentHistory sharedInstance].paymentHistory;\n```\n\nAdditionally for transactions in personal history you can:\n1. Remove a single transaction\n\n```objc\n[[DPPaymentHistory sharedInstance] removePaymentSummary: paymentToRemove];\n```\n\n2. Check current payment status for a record in the history and refresh displayed data:\na. In personal view `DPPaymentHistoryObserver` observer methods are implemented, which refresh history view:\n\n```objc\n- (void)paymentHistory:(DPPaymentHistory *)paymentHistory didUpdatePaymentSummary:(DPPaymentSummary *)paymentSummary;\n- (void)paymentHistory:(DPPaymentHistory *)paymentHistory didFailedToUpdatePaymentSummary:(DPPaymentSummary *)paymentSummary withError:(NSError *)error;\n```\n\nb. Register observer waiting for history changes\n\n```objc\n[[DPPaymentHistory sharedInstance] registerObserver: self]\n```\n\nc. Call out a method that updates payment status:\n\n```objc\n[[DPPaymentHistory sharedInstance] updatePaymentSummary: paymentToUpdate];\n```\n\nd. While releasing custom history controler, unregister history change observer\n\n```objc\n[[DPPaymentHistory sharedInstance] unRegisterObserver: self]\n```\n\nLicense\n----\n\n*Academic Free License (\"AFL\") v. 3.0*",
"homepage": "",
"license": {
"type": "Academic Free License (\"AFL\") v. 3.0",
"text": "Academic Free License (\"AFL\") v. 3.0\nThis Academic Free License (the \"License\") applies to any original work of authorship (the \"Original Work\") whose owner (the \"Licensor\") has placed the following licensing notice adjacent to the copyright notice for the Original Work:\nLicensed under the Academic Free License version 3.0\n1) Grant of Copyright License. Licensor grants You a worldwide, royalty-free, non-exclusive, sublicensable license, for the duration of the copyright, to do the following:\na) to reproduce the Original Work in copies, either alone or as part of a collective work;\nb) to translate, adapt, alter, transform, modify, or arrange the Original Work, thereby creating derivative works (\"Derivative Works\") based upon the Original Work;\nc) to distribute or communicate copies of the Original Work and Derivative Works to the public, under any license of your choice that does not contradict the terms and conditions, including Licensor's reserved rights and remedies, in this Academic Free License;\nd) to perform the Original Work publicly; and\ne) to display the Original Work publicly.\n2) Grant of Patent License. Licensor grants You a worldwide, royalty-free, non-exclusive, sublicensable license, under patent claims owned or controlled by the Licensor that are embodied in the Original Work as furnished by the Licensor, for the duration of the patents, to make, use, sell, offer for sale, have made, and import the Original Work and Derivative Works.\n3) Grant of Source Code License. The term \"Source Code\" means the preferred form of the Original Work for making modifications to it and all available documentation describing how to modify the Original Work. Licensor agrees to provide a machine-readable copy of the Source Code of the Original Work along with each copy of the Original Work that Licensor distributes. Licensor reserves the right to satisfy this obligation by placing a machine-readable copy of the Source Code in an information repository reasonably calculated to permit inexpensive and convenient access by You for as long as Licensor continues to distribute the Original Work.\n4) Exclusions From License Grant. Neither the names of Licensor, nor the names of any contributors to the Original Work, nor any of their trademarks or service marks, may be used to endorse or promote products derived from this Original Work without express prior permission of the Licensor. Except as expressly stated herein, nothing in this License grants any license to Licensor's trademarks, copyrights, patents, trade secrets or any other intellectual property. No patent license is granted to make, use, sell, offer for sale, have made, or import embodiments of any patent claims other than the licensed claims defined in Section 2. No license is granted to the trademarks of Licensor even if such marks are included in the Original Work. Nothing in this License shall be interpreted to prohibit Licensor from licensing under terms different from this License any Original Work that Licensor otherwise would have a right to license.\n5) External Deployment. The term \"External Deployment\" means the use, distribution, or communication of the Original Work or Derivative Works in any way such that the Original Work or Derivative Works may be used by anyone other than You, whether those works are distributed or communicated to those persons or made available as an application intended for use over a network. As an express condition for the grants of license hereunder, You must treat any External Deployment by You of the Original Work or a Derivative Work as a distribution under section 1(c).\n6) Attribution Rights. You must retain, in the Source Code of any Derivative Works that You create, all copyright, patent, or trademark notices from the Source Code of the Original Work, as well as any notices of licensing and any descriptive text identified therein as an \"Attribution Notice.\" You must cause the Source Code for any Derivative Works that You create to carry a prominent Attribution Notice reasonably calculated to inform recipients that You have modified the Original Work.\n7) Warranty of Provenance and Disclaimer of Warranty. Licensor warrants that the copyright in and to the Original Work and the patent rights granted herein by Licensor are owned by the Licensor or are sublicensed to You under the terms of this License with the permission of the contributor(s) of those copyrights and patent rights. Except as expressly stated in the immediately preceding sentence, the Original Work is provided under this License on an \"AS IS\" BASIS and WITHOUT WARRANTY, either express or implied, including, without limitation, the warranties of non-infringement, merchantability or fitness for a particular purpose. THE ENTIRE RISK AS TO THE QUALITY OF THE ORIGINAL WORK IS WITH YOU. This DISCLAIMER OF WARRANTY constitutes an essential part of this License. No license to the Original Work is granted by this License except under this disclaimer.\n8) Limitation of Liability. Under no circumstances and under no legal theory, whether in tort (including negligence), contract, or otherwise, shall the Licensor be liable to anyone for any indirect, special, incidental, or consequential damages of any character arising as a result of this License or the use of the Original Work including, without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses. This limitation of liability shall not apply to the extent applicable law prohibits such limitation.\n9) Acceptance and Termination. If, at any time, You expressly assented to this License, that assent indicates your clear and irrevocable acceptance of this License and all of its terms and conditions. If You distribute or communicate copies of the Original Work or a Derivative Work, You must make a reasonable effort under the circumstances to obtain the express assent of recipients to the terms of this License. This License conditions your rights to undertake the activities listed in Section 1, including your right to create Derivative Works based upon the Original Work, and doing so without honoring these terms and conditions is prohibited by copyright law and international treaty. Nothing in this License is intended to affect copyright exceptions and limitations (including \"fair use\" or \"fair dealing\"). This License shall terminate immediately and You may no longer exercise any of the rights granted to You by this License upon your failure to honor the conditions in Section 1(c).\n10) Termination for Patent Action. This License shall terminate automatically and You may no longer exercise any of the rights granted to You by this License as of the date You commence an action, including a cross-claim or counterclaim, against Licensor or any licensee alleging that the Original Work infringes a patent. This termination provision shall not apply for an action alleging patent infringement by combinations of the Original Work with other software or hardware.\n11) Jurisdiction, Venue and Governing Law. Any action or suit relating to this License may be brought only in the courts of a jurisdiction wherein the Licensor resides or in which Licensor conducts its primary business, and under the laws of that jurisdiction excluding its conflict-of-law provisions. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded. Any use of the Original Work outside the scope of this License or after its termination shall be subject to the requirements and penalties of copyright or patent law in the appropriate jurisdiction. This section shall survive the termination of this License.\n12) Attorneys' Fees. In any action to enforce the terms of this License or seeking damages relating thereto, the prevailing party shall be entitled to recover its costs and expenses, including, without limitation, reasonable attorneys' fees and costs incurred in connection with such action, including any appeal of such action. This section shall survive the termination of this License.\n13) Miscellaneous. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable.\n14) Definition of \"You\" in This License. \"You\" throughout this License, whether in upper or lower case, means an individual or a legal entity exercising rights under, and complying with all of the terms of, this License. For legal entities, \"You\" includes any entity that controls, is controlled by, or is under common control with you. For purposes of this definition, \"control\" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.\n15) Right to Use. You may use the Original Work in all ways not otherwise restricted or conditioned by this License or by law, and Licensor promises not to interfere with or be responsible for such uses by You.\n16) Modification of This License. This License is Copyright © 2005 Lawrence Rosen. Permission is granted to copy, distribute, or communicate this License without modification. Nothing in this License permits You to modify this License as applied to the Original Work or to Derivative Works. However, You may modify the text of this License and copy, distribute or communicate your modified version (the \"Modified License\") and apply it to other original works of authorship subject to the following conditions: (i) You may not indicate in any way that your Modified License is the \"Academic Free License\" or \"AFL\" and you may not use those names in the name of your Modified License; (ii) You must replace the notice specified in the first paragraph above with the notice \"Licensed under <insert your license name here>\" or with a notice of your own that is not confusingly similar to the notice in this License; and (iii) You may not claim that your original works are open source software unless your Modified License has been approved by Open Source Initiative (OSI) and You comply with its license review and certification process.\n"
"authors": {
"DotPay": ""
"source": {
"http": ""
"platforms": {
"ios": "9.1"
"vendored_frameworks": [
"requires_arc": true,
"dependencies": {
"VisaCheckoutSDK": [
"~> 6.6.1"