GuidesAPI Reference

iOS

Suggest Edits

Currently there are two ways to integrate Zip into your mobile iOS app:

*Standard Checkout*

  • Most similar to our traditional integration
  • Robust features and options for creating and managing orders

Virtual Card Checkout

  • 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 athttps://docs.us.zip.co/docs/virtual-checkout.


📘

Need Help?

Please reach out to [email protected] if you have any questions or if you need assistance.

Updated about 2 months ago