iOS MEO Wallet SDK

The MEO Wallet SDK enables your app to easily integrate with MEO Wallet in order to accept payments from your users either using the Wallet balance or a credit card.

When you start a payment your app switches to background and the payment is handled by the MEO Wallet app, if available on the device. If the MEO Wallet app is not available then the payment flow continues on Safari. At the end of this flow, your app will be opened again using a custom URL scheme.

Add the SDK to your app

• Download the tarball containing the SDK components
• Drag PTPaySDK.framework and PTPaySDK.bundle to your Xcode project
• Import the framework header where needed:

1

#import <PTPaySDK/PTPaySDK.h>

Register your URL scheme

You must register a custom URL scheme in your app’s Info.plist. This will be the scheme of the callback URLs used to return to your app at the end of the payment flow.

See Implementing Custom URL Schemes in the iOS Developer Library for instructions on how to register a custom scheme.

Usage

Create a checkout on your server

To make a payment, you must first perform a server side API call to create a checkout for the required amount. When creating the checkout, you must specify the two callback URLs that will be used to open your app at the end of the payment flow:

• url_confirm will be called when the user confirms the transaction
• url_cancel will be called when the transaction is cancelled by the user

After creating the checkout, your server will then pass to the mobile app the id and url_redirect values returned from the MEO Wallet services.

Display the MEO Wallet Pay Button

After receiving the payment data from the server, you can now present a checkout view with a standard payment button:

1
2
3

UIButton *payButton = [PTPayPayment paymentButtonWithTarget:self action:@selector(pay:)];
payButton.frame = CGRectMake((320-PTPayPaymentButtonWidth)/2, 200, PTPayPaymentButtonWidth, PTPayPaymentButtonHeight);
[self.view addSubview:payButton];

The button’s dimensions are defined by the constants PTPayPaymentButtonWidth and PTPayPaymentButtonHeight and you must not change its frame size.

Start the payment

Start the payment flow on the payment button action method (pay: on the example):

1
2
3
4
5
6

PTPayPayment *payment = [[PTPayPayment alloc] init];
NSError *error = nil;
BOOL success = [payment startPaymentWithCheckoutId:id urlRedirect:urlRedirect error:&error];
if(!success) {
    NSLog(@"Error: %@", error);
}

success will be NO in case of error; in this case error holds a NSError with the domain PTPaySDKErrorDomain and one of the following codes:

• PTPaySDKErrorCodeInvalidCheckoutId - the provided checkoutId is not valid
• PTPaySDKErrorCodeInvalidUrlRedirect - the provided urlRedirect is not valid

In case of success, your app will transition to background. The payment will be handled by the MEO Wallet app, when installed; if the user didn’t install the MEO Wallet app then the payment flow will continue on Safari.

Handle the result

When the payment flow ends, your app will be opened with one of the callback URLs specified when creating the checkout; the checkout id will be supplied as the URL parameter checkoutid.

• [url_confirm]?checkoutid=[id] - the user confirmed the transaction; you still have to confirm the checkout status server-side (get checkout) using the provided id
• [url_cancel]?checkoutid=[id] - the transaction has been cancelled, no further action needed

The SDK defines the following constants for the possible error codes:

• PTPaySDKErrorCodeNetworkError (10000) - The connection to the server could not be established and the transaction was not processed
• PTPaySDKErrorCodeNetworkTimedOut (10005) - The connection to the server timed out while confirming the purchase. You should confirm the transaction state on your server
• PTPaySDKErrorCodeCanceled (10030) - The user explicitly canceled the operation.
• PTPaySDKErrorCodeGeneric (10040) - The payment processing failed for an undisclosed reason. The user has been informed of the specific error by the Wallet app
• PTPaySDKErrorCodeTransactionAlreadyConfirmed (20110) - The transaction has already been processed
• PTPaySDKErrorCodeTransactionIsPending (20120) - The payment operation ended but the transaction is not yet complete. For instance, it might require back-end confirmation, or the user did not complete a 3DSecure verification flow

Testing

We provide a MEO Wallet sandbox environment for integration tests and a mW sandbox app linked to this environment. Create the checkout on your server using the sandbox and, when you create the PTPayPayment instance, specify the environment as follows:

1

PTPayPayment *payment = [PTPayPayment alloc] initWithEnvironment:PTPayEnvironmentSandbox];

To use the production environment, you can either call initWithEnvironment: with PTPayEnvironmentProduction or initialise PTPayPayment with no arguments.