Simple SDKs

eWAY is the easiest way to accept payments in your app or on your website. Get integrated and start selling more, faster - in a range of languages using the eWAY SDKs, helpful documentation, and 24/7 support from real humans. eWAY - with you every step of the way.

iOS SDK – Getting Started

iOS Apple Logo

Use the eWAY iOS SDK to easily accept payments in your iPhone or iPad application!

The eWAY iOS SDK provides the following functions:

  • Encrypt card details for passing through the merchant’s servers to eWAY
  • Complete a payment on a user’s iOS device
  • Translate response messages to user friendly text
  • Support for Apple Pay (​in Australia only)

Requirements

The eWAY iOS SDK supports iOS 7 and above. Apple Pay requires iOS 8 or above.

Installation

CocoaPods

Installing with CocoaPods is quick and easy:

  1. Add the eWAY iOS SDK to the project’s Podfile:

    1. pod 'eWAYPaymentsSDK'
  2. Then run

    1. pod install

    to download and install the SDK

 

Example project

Two example projects ​are included in the eWAY iOS SDK GitHub repository to demonstrate the available functions. One is a demonstrate integrating eWAY, while the other contains an example Apple Pay integration. To use these:

  1. Clone the repository to your development machine
    1. git clone https://github.com/eWAYPayment/eway-rapid-ios.git
  2. Choose a project from the Example directory and run
    1. pod install

Headers

To use the eWAY iOS SDK in your project, don’t forget to include the RapidAPI in the header of classes that use the SDK:

  1. #import "RapidAPI.h"

Configuration

The eWAY iOS SDK requires two pieces of information to connect to eWAY, your eWAY account’s Public API Key and the endpoint.

To find your account’s Public API Key:

  1. In MYeWAY (production or sandbox), go to My Account > User Security > Manage Users

  2. Select the “Actions” dropdown for the Rapid API user and select “View Api Keys

  3. Select the “Pay Now Button Public API Key”, this is your Public API Key.

The Endpoint should be one of the Rapid API endpoints:

  • Sandbox: https://api.sandbox.ewaypayments.com/
  • Production: https://api.ewaypayments.com/


These values are passed to the eWAY iOS SDK in the following way:

  1. #import "eWAYPaymentsSDKAppDelegate.h"
  2. #import "RapidAPI.h"

  3. @implementation eWAYPaymentsSDKAppDelegate

  4. - (BOOL)application🙁UIApplication *)application didFinishLaunchingWithOptions🙁NSDictionary *)launchOptions
  5. {
  6.  [[RapidAPI sharedManager] setRapidEndpoint:@"https://api.sandbox.ewaypayments.com/"];
  7.  [[RapidAPI sharedManager] setPublicAPIKey:@"epk-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"];

  8.  return YES;
  9. }

  10. @end

Don’t forget to change these properties to the production API Key & Endpoint when sending your app live!

Apple Pay

Details for adding Apple Pay to your iOS app can be found on the iOS with Apple Pay page.

Encrypt Values

To secure a customer’s card data for transmission to your server for processing, you can use the encryptValues method. Once encrypted, the values can be sent to your server with any other data to be processed using eWAY’s Rapid Direct Connection API.

Once the eWAY iOS SDK has been initialised, the encryptValues method can be called with a NSMutableArray:

  1. arrNVpair = [NSMutableArray new];

  2. NVpair *nvpair1 = [[NVpair alloc] init];
  3. nvpair1.name = @"cards";
  4. nvpair1.value = @"4444333322221111";


  5. NVpair *nvpair2 = [[NVpair alloc] init];

  6. nvpair2.name = @"CVN";

  7. nvpair2.value = @"123";
  8.  

  9. [arrNVpair addObject:nvpair1];

  10. [arrNVpair addObject:nvpair2];
  11.  

  12. [RapidAPI encryptValues:arrNVpair completed:^(EncryptValuesResponse *encryptValuesResponse) {

  13. if (encryptValuesResponse.Status == Success) {

  14.      NSMutableArray *values = [NSMutableArray new];

  15.      for (NVpair *nv in encryptValuesResponse.Values) {

  16.          [values addObject:[nv dictionary]];

  17.      }
  18.  

  19. }

  20. }];

The response contains the encrypted values which can be fetched as follows:

  1. NSMutableArray *values = [NSMutableArray new];
  2. for (NVpair *nv in encryptValuesResponse.Values) {
  3.     [values addObject:[nv dictionary]];
  4. }

If there was a problem with encrypting the values, the error can be fetched from the Errors property. If no errors occurred then null will be returned. See Handling Errors for more information.


Make a Payment

A payment can also be made directly from the app using the eWAY iOS SDK, instead of sending details to a server. Note that the result of the transaction (succeeded or failed) can still only be requested using Rapid API from a server – see Getting the Result below.

First collect the details for the payment (such as the customer’s name and card details) and prepare the data for sending. All the fields available in RapidAPI’s Direct Connection can be used when submitting a transaction. The following is a simple example:

  1. transaction = [[Transaction alloc] init];

  2. Customer *customerObj = [[Customer alloc] init];
  3. customerObj.Reference = @"A12345";
  4. customerObj.Title = @"Mr.";
  5. customerObj.FirstName = @"Nico";
  6. customerObj.LastName = @"Vulture";
  7. customerObj.CompanyName = @"All Web Pty Ltd";
  8. customerObj.JobDescription = @"Developer";
  9. customerObj.Phone = @"09 889 0986";
  10. customerObj.Mobile = @"09 889 0986";

  11. Address *customerAddress = [[Address alloc] init];
  12. customerAddress.Street1 = @"Level 5";
  13. customerAddress.Street2 = @"369 Queen Street";
  14. customerAddress.City = @"Sydney";
  15. customerAddress.State = @"NSW";
  16. customerAddress.PostalCode = @"2010";
  17. customerAddress.Country = @"au";

  18. customerObj.Address = customerAddress;

  19. CardDetails *cardDetails = [[CardDetails alloc] init];
  20. cardDetails.Name = @"Nico Vulture";
  21. cardDetails.Number = @"378282246310005";
  22. cardDetails.ExpiryMonth = @"10";
  23. cardDetails.ExpiryYear = @"19";
  24. cardDetails.CVN = @"836";
  25. customerObj.CardDetails = cardDetails;

  26. transaction.Customer = customerObj;

  27. //payment
  28. Payment *payment = [[Payment alloc] init];
  29. payment.Payment = 100;
  30. payment.InvoiceNumber = @"Inv 21540";
  31. payment.InvoiceDescription = @"Individual Invoice Description";
  32. payment.InvoiceReference = @"513456";
  33. payment.CurrencyCode = @"AUD";

  34. transaction.Payment = payment;

Then submit the data to eWAY with the submitPayment method:

  1. [RapidAPI submitPayment:transaction completed:^(SubmitPaymentResponse *submitPaymentResponse) {
  2.  NSString *submissionID = submitPaymentResponse.SubmissionID;
  3. }];


Getting the Result

RapidAPI will then return a response object, which contains an eWAY Access Code. This can be fetched using the getSubmissionID property. The Access Code is an identifier to look up the transaction result. The transaction result cannot be retrieved with the eWAY iOS SDK, instead the Access Code should be passed to a server which can use the eWAY RapidAPI Transaction Query to get the result.

  1. NSString *submissionID = submitPaymentResponse.SubmissionID;

The response object also contains status and error properties. The status is set to one of “Accepted” or “Error”. This does not indicate whether the transaction was successful, it indicates if the SDK received a response.

If an error did occur, the errors property will contain one or more comma separated error codes. These codes can be translated with userMessage – see Handling Errors below for more details.

Handling Errors

If a call with the eWAY iOS SDK fails for some reason, an error code will be returned in the response object. Note that only SDK errors will be returned – if there was an error with the transaction (such as card declined) no error will be supplied to the SDK.

To check for a transaction or validation failure, use the Access Code to do a server side Transaction Query with eWAY’s Rapid API.

To check if an SDK error occurred, test if the status is Error::

  1. if (submitPaymentResponse.Status == Error) {
  2.     // handle errors

If there is an error, it can be looked up using userMessage to return a user friendly version of the response (only English is available at this time):

  1. [RapidAPI userMessage:submitPaymentResponse.Errors Language:@"EN" completed:^(UserMessageResponse *userMessageResponse) {
  2. NSString *msg = [NSString stringWithFormat:@"%@ \n %@",userMessageResponse.Errors, userMessageResponse.Messages];
  3. }]

Error Codes

The following error codes are specific to the eWAY iOS SDK. They can be translated using the userMessage as described in the Handling Errors section.

  Error Code

  Purpose

  S9990

  Library does not have Endpoint initialised, or not initialise to a URL

  S9991

  Library does not have PublicAPI key initialised, or Key is Invalid.

  S9992

  Communication error with Rapid API.

  S9993

  Authentication error with Rapid API.

  S9994

  Internal system error communicating with Rapid API.

  S9995

  Internal SDK Error, Bad Parameters etc.



eWAY makes it easy for us to process and manage payments. They have an SDK that my developers liked working with and their payment management tools are very easy to use.

Dean Van Es, Managing Director FastCover