Checkout - iOS
This guide helps you get started with the Checkout SDK on iOS.
Prerequisites
- A
ClientId
and an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard - A User and their associated Wallet to complete the pay-in
- A card to register or payment method setup (see Testing - Payment methods for testing information)
For iOS:
- iOS 13+
- Xcode 12.2
- Swift 5.3+
Best practice – Check out our example app and demo
To support you with your integration, be sure to make use of our example app on GitHub.
Installation
You can install the Mangopay Checkout SDK using SPM or Cocoapods.
Swift Package Manager (recommended)
- Open your Xcode project and go to File > Swift Packages > Add Package Dependency
- In the prompted dialog, enter the repository URL https://github.com/Mangopay/mangopay-ios-sdk
- Select the checkout-ios-sdk package by checking the corresponding checkbox
- Follow the on-screen instructions to complete the installation
Cocoapods
Open your podfile
and add:
Add these sources above your podfile:
Initialization
Initialize the SDK with your ClientId
and select your environment (Sandbox or Production).
Note – Initialize once per app instance
The initialization should only be done once for an instance of the application.
We recommend putting this inside the AppDelegate
class.
Initialization parameters
Property | Type | Description |
---|---|---|
clientId | String | The unique identifier associated with the Mangopay API key, giving access to the Mangopay API. |
profilingMerchantId | String | The unique identifier associated with your fraud protection package. Contact Mangopay to obtain this value. |
checkoutReference | String | An identifier for your checkout session. |
environment | Environment | The Mangopay environment. |
Payment sheet configuration
To configure the Checkout SDK’s payment sheet:
Create a payment sheet instance in your ViewController
Configure paymentSheet with paymentMethodOptions
Present the payment sheet
Handling redirection
Warning – Use Mangopay Checkout domain as return URL
When making the pay-in request from your backend, use the Mangopay Checkout URL as the SecureModeReturnURL
or ReturnURL
(depending on the payment method):
http://checkout.mangopay.com
The user must be returned to this URL after redirection.
Some payment methods (card, Google Pay, PayPal) require or may require the user to be redirected to authorize or complete a transaction.
The Checkout SDK allows you to manage the entire payment flow seamlessly while retaining control over transaction logic in your backend. Once a payment method is selected and payment details are provided, use the onCreatePayment
function to request the transaction from your backend.
Subsequently, and when necessary for the transaction type, the Checkout SDK seamlessly manages additional redirect actions for 3DS authorization or otherwise validating the payment.
To manage transaction redirects effectively with the SDK:
Define onCreatePayment
In your paymentMethodOptions
configurations, define an onCreatePayment
attribute as a function.
Within your function:
- Request a transaction from your server and subsequently, Mangopay.
- Return the unaltered transaction response object to the SDK.
The SDK:
- Redirects the user to the payment authentication page when necessary.
- Manages payment provider redirects back to the SDK.
- Triggers the
onPaymentComplete
event with the ID and status of the transaction. - Confirms the redirect result on your server by invoking the corresponding GET API of the transaction.
- Presents the payment result to the user.
Redirection example
Creating payment handler callbacks
Callback parameters
Property | Type | Description |
---|---|---|
onPaymentMethodSelected | ((PaymentMethod) -> Void) | Triggered when a payment method has been selected. |
onTokenizationCompleted | ((TokenizedCardData) -> Void) | Triggered when a card tokenization is completed and a CardId is returned. |
onCreateCardRegistration | ((MGPCardInfo) async -> MGPCardRegistration?) | Triggered only when the user selects card payment. This callback gives you control over making the card registration optional during the session. |
onPaymentCompleted | ((PaymentMethod, String?) async -> Payable?) | Triggered when the transaction is completed, whatever the outcome (whether successful or failed). |
onCancelled | () -> Void)? | Called when the payment sheet is closed. |
onError | Triggered when an internal Checkout SDK error has occurred. |
Presenting the payment result
Configuring card payments
Property | Type | Description |
---|---|---|
supportedCardSchemes | Array<[CardType]> | The card brands to be shown. |
cardRegistration | CardRegistration? | You can provide CardRegistration optionally from configuration or provide it from callbacks. |
Card tokenization
In the options for the card payment method, create a function to handle creation of Card Registration event handler in the payment methods object:
- Your
onCreateCardRegistration
function calls your server, and passes it the card brand of the user. - Your server makes a request to Create a Card Registration.
- In response, your server receives a Card Registration object.
- In your
onCreateCardRegistration
function, return the unmodified Card Registration object to the SDK. - The SDK tokenizes the card and updates the Card Registration object to create the
CardId
which is used for payment.
tokenizationComplete output
Managing cards
You can use the following endpoints to manage cards:
- View a Card provides key information about the card, including its Fingerprint which can be used as an anti-fraud tool
- Deactivate or edit a Card allows you to irreversibly set the card as inactive
Warning - End user’s approval needed to save card details
Under no circumstances should card information be kept without the end user’s approval.
If you don’t have the end user’s approval, you need to deactivate the card systematically after use in your implementation.
Requesting card pay-ins
You can use a registered card (CardId
) for requests with the following API objects:
- The Card Validation object, to validate a card without debit
- The Direct Card PayIn object, for one-shot card payments
- The Recurring PayIn Registration object, for recurring card payments
- The Preauthorization object, for 7-day preauthorized card payments
- The Deposit Preauthorization object, for 30-day preauthorized card payments
In your requests:
- Ensure that the
SecureModeReturnURL
parameter is set tohttps://checkout.mangopay.com
- Submit the
PreferredCardNetwork
value if it was received byonCreatePayment
Configuring Apple Pay
Note - Apple Pay integration required
Offering Apple Pay requires additional setup by the platform, including certification and integration. For more information, see the How to process an Apple Pay payment tutorial.
Apple Pay configuration parameters
Property | Type | Description |
---|---|---|
amount | Double REQUIRED | The amount being paid. |
delegate | MGPApplePayHandlerDelegate REQUIRED | The event handler. |
merchantIdentifier | String | The merchant identifier. REQUIRED |
merchantCapabilities | PKMerchantCapability REQUIRED | A bit field of the payment processing protocols and card types supported. |
currencyCode | String REQUIRED | The three-letter ISO 4217 code (EUR, GBP, etc) of a supported currency (depends on feature, contract, and activation settings). |
countryCode | String REQUIRED | The platform’s two-letter ISO 3166 country code. |
supportedNetworks | Array<PKPaymentNetwork>
REQUIRED | The card networks supported by Mangopay. Allowed values: VISA, MASTERCARD |
requiredBillingContactFields | Set<PKContactField> | |
billingContact | PKContact | |
shippingContact | PKContact | |
shippingType | PKShippingType | |
shippingMethods | Array<PKShippingMethod> | |
applicationData | Data | |
requiredShippingContactFields | Set<PKContactField> |
Handling Apple Pay result
Configuring PayPal
PayPal configuration parameters
Property | Type | Description |
---|---|---|
color | PayPalButton.Color | Color of the paypal button. Default to gold if not provided. |
edges | PaymentButtonEdges | Edges of the button. Default to softEdges if not provided. |
label | PayPalButton.Label | Label displayed next to the button’s logo. Default to no label. |
Verifying the payment result
Once the onPaymentComplete
event is triggered, verify the status of the relevant Mangopay API object:
Caution – Check payment result from backend
You should confirm the transaction result returned by the Checkout SDK by calling the Mangopay API from your backend.
Using Card Element
The Card Element offers a ready-made component that allows you to create your own card payment experience and tokenize card payment details. With our Card Element, you can easily incorporate a custom pay button and have control over the tokenization process.
When using Card Element, you still benefit from card data validation, and the ability to customize the payment form.
1. Create an instance of the MangopayCheckoutForm
MGPPaymentForm parameters
Property | Type | Description |
---|---|---|
paymentFormStyle | PaymentFormStyle | Property for styling the payment form. |
supportedCardBrands | Array<CardType> | The supported card brands listed above the payment form. |
2. Add payment form to your parent view and add the appropriate layout constraints
Using MangopayCheckoutForm
with card tokenization
2.1 Create card registration object
2.2 Call tokenizeCard()
when pay button is tapped
MangopayCoreiOS.tokenizeCard()
Property | Type | Description |
---|---|---|
form | MangopayCheckoutForm | The payment form instance. |
with | MGPCardRegistration | The card registration object. |
presentIn | UIViewController | |
callBack | typealias MangoPayTokenizedCallBack = ((TokenizedCardData?, MGPError?) -> ()) | A callback that handles events of the payment form tokenization process. |
TokenizedCardData
Property | Type | Description |
---|---|---|
card | CardRegistration | Tokenized Card object. |
profilingAttemptReference | String | The unique reference for the profiling session. |
Branding
You can customize the appearance of the payment sheet using the PaymentFormStyle
object.
Property | Type | Description |
---|---|---|
font | UIFont | The font of the text fields and labels. |
borderType | BorderType | The border type of the text fields. Allowed values: square , round |
textColor | UIColor | Color of the text in the text fields. |
placeHolderColor | UIColor | The color of the placeholder text in the text fields. |
borderColor | UIColor | The color of the text field borders. |
borderFocusedColor | UIColor | The color of the text field borders when highlighted. |
errorColor | UIColor | The color of the error labels. |
checkoutButtonTextColor | UIColor | The color of the text on the confirmation button. |
checkoutButtonBackgroundColor | UIColor | The color of the background of the confirmation button. |
checkoutButtonDisabledBackgroundColor | UIColor | The color of the background of the confirmation button when disabled. |
checkoutButtonText | String | The text of the confirmation button. |
checkoutTitleText | String | The text of the payment form title. |
applePayButtonType | PKPaymentButtonType | The Apple Pay button type. |
applePayButtonStyle | PKPaymentButtonStyle | The Apple Pay button style. |
applePayButtonCornerRadius | CGFloat | The corner radius of the Apple Pay button. |