iOS
Currently there are two ways to integrate Zip into your mobile iOS app:
- Most similar to our traditional integration
- Robust features and options for creating and managing orders
- Quickest to implement when you can accept standard Visa credit cards
- Uses identical rails to a standard Visa credit card transaction
Overview
Items you will need:
- The Zip iOS SDK
- The Start Checkout call in your iOS app
- An order confirmation endpoint on your server
Implementation
The Zip iOS SDK
- Our SDK is currently public, simply add the following to your Podfile and run pod install
pod 'QuadPaySDK'
https://cocoapods.org/pods/QuadPaySDK
How to start a Zip checkout in your iOS App
Initialize the Zip SDK
Your merchant id will be provided by your Zip account manager.
Please make sure you are using the production merchantId with environment "production" and the sandbox merchantId with environment "sandbox".
For enablement in other markets, set locale with your locale variable ("US" for the United States).
Typically this is done in didFinishLaunchingWithOptions:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[[Zip sharedInstance] initialize:@"<merchant_id>"
environment:@"production"
locale:@"US"
];
return YES;
}
Start the Zip Checkout
Once presented the customer will be shown the Zip checkout flow.
UINavigationController *navController = [
QuadPay startCheckout
delegate:self
amount:@"123.45"
merchantReference"@"unique-order-id"
customerFirstName@"Zip"
customerLastName:@"Customer"
customerEmail:@"[email protected]"
customerPhoneNumber:@"+15555555555"
customerAddressLine1:@"123 Main St."
customerAddressLine2:@"10th Floor"
customerCity:@"New York"
customerState:@"NY"
customerPostalCode:@"10003"
customerCountry:@"US"
];
[self presentViewController:navController animated:YES completion:nil];
Implement the QPCheckoutDelegate functions
These functions give your application information regarding the result of the Zip checkout flow.
Checkout Success
This function returns an order id you may use to confirm an order has been created.
- (void) checkoutSuccessful:(QuadPayCheckoutViewController*)viewController orderId:(NSString*)orderId
{
// The user has completed checkout -- the order id must be used to confirm the transaction from the backend
NSLog(@"Zip checkout succeeded with order id: %@", orderId);
}
Checkout Cancelled
This function is called when the user cancels the Zip process or is declined.
- (void)checkoutCancelled:(QuadPayCheckoutViewController*)viewController reason:(NSString *)reason
{
// The Zip checkout session has been cancelled
NSLog(@"Zip checkout cancelled, reason: %@", reason);
}
Confirming your Zip orders
As soon as your customer has completed checkout an order id will be issued. To finalize the transaction this order id must be submitted to Zip's confirmation endpoint. The order id will last for 24 hours under default settings to be confirmed.
The timing of your shipping can be any time after you have confirmed the order. When submitting the order id you will have a chance to finalize the order amount.
Post the order id to the confirmation endpoint
See https://docs.quadpay.com/docs/custom-integration-guide#signing-requests for information regarding signing requests
Post:
curl -X post https://gateway.quadpay.com/orders/{orderId}/confirm
-H 'content-type: application/json'
-H 'X-QP-Signature: [signature]'
-d '{
"orderId": [orderId],
"totalOrderAmount": <number>, (optional)
"taxAmount": <number>, (optional),
"shippingAmount": <number>, (optional)
}'
An order id will be returned:
{
"orderId": [order id]
}
Service after confirmation
Once the order has been confirmed and an order id has been received the user should be guided to a success page.
This order id can also be used to update the order using our normal orders integration API at https://docs.us.zip.co/docs/custom-integration-guide.
Overview
Items you will need:
- The Zip iOS SDK
- The Start Checkout call in your iOS app
- A payment processor for credit card transactions
Implementation
The Zip iOS SDK
- Our SDK is currently public, simply add the following to your Podfile and run pod install
pod 'QuadPaySDK'
https://cocoapods.org/pods/QuadPaySDK
How to start a Zip checkout in your iOS App
Initialize the Zip SDK
Your merchant id will be provided by your Zip account manager.
Please make sure you are using the production merchantId with environment "production" and the sandbox merchantId with environment "sandbox".
Typically this is done in didFinishLaunchingWithOptions:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[[QuadPay sharedInstance] initialize:@"<merchant_id>"
environment:@"production"
locale:@"US"
];
return YES;
}
Start the Zip Checkout
Once presented the customer will be shown the Zip checkout flow.
UINavigationController *navController = [
QuadPay startVirtualCheckout
delegate:self
amount:@"123.45"
merchantReference"@"unique-order-id"
customerFirstName@"Zip"
customerLastName:@"Customer"
customerEmail:@"[email protected]"
customerPhoneNumber:@"+15555555555"
customerAddressLine1:@"123 Main St."
customerAddressLine2:@"10th Floor"
customerCity:@"New York"
customerState:@"NY"
customerPostalCode:@"10003"
customerCountry:@"US"
merchantFeeForPaymentPlan: "0"
];
[self presentViewController:navController animated:YES completion:nil];
Implement the QPVirtualCheckoutDelegate functions
These functions give your application information regarding the result of the QuadPay checkout flow.
Checkout Success
This function returns a token you may exchange to confirm an order has been created.
- (void)checkoutSuccessful:(QuadPayCard *)card cardholder:(QuadPayCardHolder *)cardholder orderId:(nonnull NSString *)orderId
{
// The user has completed checkout
// A virtual card has been returned
// Pass the details in card and cardholder into your standard payment processor
NSLog(@"%@", [NSString stringWithFormat:@"Card: %@ Issued for %@", [card toString], [cardholder toString], [orderId]]);
}
For card and cardholder types please see https://docs.quadpay.com/docs/virtual-checkout#card
Checkout Cancelled
This function is called when the user cancels the Zip process or is declined.
- (void)checkoutCancelled:(NSString *)reason
{
// The Zip checkout session has been cancelled
NSLog(@"%@", [NSString stringWithFormat:@"User cancelled QuadPay checkout with reason %@", reason]);
}
Finishing the Zip order
Once you have received a virtual card number in a success delegate you may authorize and capture it up to the value provided at the beginning of checkout. The card that is issued is a standard Visa card and all authorize/capture/refund functionality will work as expected.
More information and frequently asked questions are available at https://docs.us.zip.co/docs/virtual-checkout.
Need Help?
Please reach out to [email protected] if you have any questions or need assistance.
Updated 4 months ago