Customize the iOS SDK

Last updated: October 20, 2022

When a customer initiates a payment with the iOS SDK, their payment information is collected via 2 customizable forms:

Payment Form: prompts users for their payment card details
Billing Form: prompts users for their billing information

The styling of these forms can be customized through the use of the paymentFormStyle and billingFormStyle objects, which are wrapped in the PaymentStyle wrapper.


1PaymentStyle(paymentFormStyle: YourPaymentStyle(),
2             billingFormStyle: YourBillingStyle())

You can choose between three different options for customization, depending on how much control you need over the forms' UI design. In order of increasing complexity these are:

The default integration is the quickest way to display the forms required to collect payment information, with no additional customization required.

Localization support for the following languages is built into the default integration:

Arabic
Dutch
English
French
German
Italian
Romanian
Spanish

You can also add your own localized strings to add support for additional languages.

For basic customization, the DefaultPaymentFormStyle and DefaultBillingFormStyle objects expose properties that allow you to change the text and colors displayed on the forms.


1// Create a new DefaultPaymentFormStyle object
2var paymentFormStyle = DefaultPaymentFormStyle()
3
4// Change the payment form's background color
5paymentFormStyle.backgroundColor = UIColor.darkGray
6
7// Change the card number field's placeholder value
8paymentFormStyle.expiryDate.textfield.placeholder = "00 / 00"
9
10// Change the payment button text
11paymentFormStyle.payButton.text = "Pay £54.63"
12
13
14// Create a new DefaultBillingFormStyle object
15var billingFormStyle = DefaultBillingFormStyle()
16
17// Change the billing form header's font color
18billingFormStyle.header.headerLabel.textColor = UIColor.darkGray
19
20// Change the billing form header text
21paymentFormStyle.header.headerLabel.text = "Billing info"
22
23// Wrap the styling in a PaymentStyle wrapper
24let paymentStyle = PaymentStyle(paymentFormStyle: paymentFormStyle,
25                                billingFormStyle: billingFormStyle)

See our example project on GitHub.

If you want to customize your forms beyond what is supported by the default integration, you can apply a theme using the Theme object.

When instantiating a new Theme object, you must supply the following fields at a minimum:

primaryFontColor
secondaryFontColor
buttonFontColor
errorFontColor
backgroundColor
errorBorderColor

You can then optionally provide additional values to customize other elements including button styling, custom placeholder and error text, and field input controls.

Dynamic font sizing based on the user's device is built-in to the Theme object.


1// Create a new Theme object
2var theme = Theme(primaryFontColor: UIColor(red: 0 / 255, green: 204 / 255, blue: 45 / 255, alpha: 1),
3    secondaryFontColor: UIColor(red: 177 / 255, green: 177 / 255, blue: 177 / 255, alpha: 1),
4    buttonFontColor: .green,
5    errorFontColor: .red,
6    backgroundColor: UIColor(red: 23 / 255, green: 32 / 255, blue: 30 / 255, alpha: 1),
7    errorBorderColor: .red)
8
9// Add a border and corner radius around text input fields
10theme.textInputBackgroundColor = UIColor(red: 36 / 255.0, green: 48 / 255.0, blue: 45 / 255.0, alpha: 1.0)
11theme.textInputBorderRadius = 4
12
13// Add a border around input sections
14theme.borderRadius = 4
15
16// Create a new payment form style, only providing custom text values
17var paymentFormStyle = theme.buildPaymentForm(
18    headerView: theme.buildPaymentHeader(title: "Payment details",
19                                        subtitle: "Accepting your favorite payment methods"),
20    addBillingButton: theme.buildAddBillingSectionButton(text: "Add billing details",
21                                                        isBillingAddressMandatory: false,
22                                                        titleText: "Billing details"),
23    billingSummary: theme.buildBillingSummary(buttonText: "Change billing details",
24                                            titleText: "Billing details"),
25    cardNumber: theme.buildPaymentInput(isTextFieldNumericInput: true,
26                                        titleText: "Card number",
27                                        errorText: "Please enter valid card number"),
28    expiryDate: theme.buildPaymentInput(textFieldPlaceholder: "__ / __",
29                                        isTextFieldNumericInput: false,
30                                        titleText: "Expiry date",
31                                        errorText: "Please enter valid expiry date"),
32    securityCode: theme.buildPaymentInput(isTextFieldNumericInput: true,
33                                        titleText: "CVV date",
34                                        errorText: "Please enter valid security code"),
35    payButton: theme.buildPayButton(text: "Pay now"))
36
37// Override a custom property from the resulting payment form style
38paymentFormStyle.payButton.disabledTextColor = UIColor.lightGray
39
40// Create a new billing form style, and modify each field's properties individually
41var billingFormStyle = theme.buildBillingForm(
42            header: theme.buildBillingHeader(title: "Billing information",
43                                             cancelButtonTitle: "Cancel",
44                                             doneButtonTitle: "Done"),
45            cells: [.fullName(theme.buildBillingInput(text: "", isNumericInput: false, isMandatory: false, title: "Your name")),
46                    .addressLine1(theme.buildBillingInput(text: "", isNumericInput: false, isMandatory: true, title: "Address")),
47                    .city(theme.buildBillingInput(text: "", isNumericInput: false, isMandatory: true, title: "City")),
48                    .country(theme.buildBillingCountryInput(buttonText: "Select your country", title: "Country")),
49                    .phoneNumber(theme.buildBillingInput(text: "", isNumericInput: true, isMandatory: true, title: "Phone number"))])

See our example project on GitHub.

For complete control over how the various UI elements on your forms look, you can use the fully custom solution.

You can use the properties listed in the structs below to edit each individual UI component displayed across the forms:


1private enum Constants {
2    static let mainFontColor = UIColor(red: 0 / 255, green: 204 / 255, blue: 45 / 255, alpha: 1)
3    static let secondaryFontColor = UIColor(red: 177 / 255, green: 177 / 255, blue: 177 / 255, alpha: 1)
4    static let errorColor = UIColor.red
5    static let backgroundColor = UIColor(red: 23 / 255, green: 32 / 255, blue: 30 / 255, alpha: 1)
6    static let textFieldBackgroundColor = UIColor(red: 36 / 255.0, green: 48 / 255.0, blue: 45 / 255.0, alpha: 1.0)
7    static let borderRadius: CGFloat = 4
8    static let borderWidth: CGFloat = 1
9}
10
11// Main payment form
12
13struct PaymentFormStyleCustom1: PaymentFormStyle {
14  var backgroundColor: UIColor = Constants.backgroundColor
15  var headerView: PaymentHeaderCellStyle = StyleOrganiser.PaymentHeaderViewStyle()
16  var addBillingSummary: CellButtonStyle? = StyleOrganiser.BillingStartButton()
17  var editBillingSummary: BillingSummaryViewStyle? = StyleOrganiser.BillingSummaryStyle()
18  var cardholderInput: CellTextFieldStyle?
19  var cardNumber: CellTextFieldStyle = StyleOrganiser.CardNumberSection()
20  var expiryDate: CellTextFieldStyle = StyleOrganiser.ExpiryDateSection()
21  var securityCode: CellTextFieldStyle? = StyleOrganiser.SecurityNumberSection()
22  var payButton: ElementButtonStyle = StyleOrganiser.PayButtonFormStyleCustom1()
23}
24
25struct BillingFormStyleCustom1: BillingFormStyle {
26  var mainBackground: UIColor = Constants.backgroundColor
27  var header: BillingFormHeaderCellStyle = StyleOrganiser.BillingHeaderViewStyle()
28  var cells: [BillingFormCell] = [
29    .fullName(StyleOrganiser.BillingFullNameInput()),
30    .addressLine1(StyleOrganiser.BillingAddressLine1Input()),
31    .addressLine2(StyleOrganiser.BillingAddressLine2Input()),
32    .city(StyleOrganiser.BillingCityInput()),
33    .state(StyleOrganiser.BillingStateInput()),
34    .postcode(StyleOrganiser.BillingPostcodeInput()),
35    .country(StyleOrganiser.BillingCountryInput()),
36    .phoneNumber(StyleOrganiser.BillingPhoneInput())
37  ]
38}
39
40private enum StyleOrganiser {
41
42    struct PaymentHeaderViewStyle: PaymentHeaderCellStyle {
43        var shouldHideAcceptedCardsList = true
44        var backgroundColor: UIColor = Constants.backgroundColor
45        var headerLabel: ElementStyle? = PaymentHeaderLabel()
46        var subtitleLabel: ElementStyle? = PaymentHeaderSubtitle()
47        var schemeIcons: [UIImage?] = []
48    }
49
50    struct BillingHeaderViewStyle: BillingFormHeaderCellStyle {
51        var backgroundColor: UIColor = .clear
52        var headerLabel: ElementStyle = BillingHeaderLabel()
53        var cancelButton: ElementButtonStyle = CancelButtonStyle()
54        var doneButton: ElementButtonStyle = DoneButtonStyle()
55    }
56
57  struct BillingHeaderLabel: ElementStyle {
58        var textAlignment: NSTextAlignment = .natural
59        var isHidden = false
60        var text: String = "Billing address"
61        var font = UIFont(sfMono: .semibold, size: 24)
62        var backgroundColor: UIColor = .clear
63        var textColor: UIColor = Constants.mainFontColor
64    }
65
66    struct PayButtonFormStyleCustom1: ElementButtonStyle {
67      var image: UIImage?
68      var textAlignment: NSTextAlignment = .center
69      var text: String = "Pay 100$"
70      var font = UIFont.systemFont(ofSize: 15)
71      var disabledTextColor: UIColor = Constants.secondaryFontColor
72      var disabledTintColor: UIColor = Constants.mainFontColor.withAlphaComponent(0.2)
73      var activeTintColor: UIColor = Constants.mainFontColor
74      var backgroundColor: UIColor = Constants.mainFontColor
75      var textColor: UIColor = .white
76      var normalBorderColor: UIColor = .clear
77      var focusBorderColor: UIColor = .clear
78      var errorBorderColor: UIColor = .clear
79      var imageTintColor: UIColor = .clear
80      var isHidden = false
81      var isEnabled = true
82      var height: Double = 56
83      var width: Double = 0
84      var cornerRadius: CGFloat = 10
85      var borderWidth: CGFloat = 0
86      var textLeading: CGFloat = 0
87    }
88
89    struct CancelButtonStyle: ElementButtonStyle {
90        var textAlignment: NSTextAlignment = .natural
91        var isEnabled = true
92        var disabledTextColor: UIColor = Constants.secondaryFontColor
93        var disabledTintColor: UIColor = .clear
94        var activeTintColor: UIColor = .clear
95        var imageTintColor: UIColor = .clear
96        var normalBorderColor: UIColor = .clear
97        var focusBorderColor: UIColor = .clear
98        var errorBorderColor: UIColor = .clear
99        var image: UIImage?
100        var textLeading: CGFloat = 0
101        var cornerRadius: CGFloat = Constants.borderRadius
102        var borderWidth: CGFloat = Constants.borderWidth
103        var height: Double = 60
104        var width: Double = 70
105        var isHidden = false
106        var text: String = "Cancel"
107        var font = UIFont(sfMono: .semibold, size: 17)
108        var backgroundColor: UIColor = .clear
109        var textColor: UIColor = Constants.mainFontColor
110    }
111
112    struct DoneButtonStyle: ElementButtonStyle {
113        var textAlignment: NSTextAlignment = .natural
114        var isEnabled = true
115        var disabledTextColor: UIColor = Constants.secondaryFontColor
116        var disabledTintColor: UIColor = .clear
117        var activeTintColor: UIColor = .clear
118        var imageTintColor: UIColor = .clear
119        var normalBorderColor: UIColor = .clear
120        var focusBorderColor: UIColor = .clear
121        var errorBorderColor: UIColor = .clear
122        var image: UIImage?
123        var textLeading: CGFloat = 0
124        var cornerRadius: CGFloat = Constants.borderRadius
125        var borderWidth: CGFloat = Constants.borderWidth
126        var height: Double = 60
127        var width: Double = 70
128        var isHidden = false
129        var text: String = "Done"
130        var font = UIFont(sfMono: .semibold, size: 17)
131        var backgroundColor: UIColor = .clear
132        var textColor: UIColor = Constants.mainFontColor
133    }
134
135    struct PaymentHeaderLabel: ElementStyle {
136        var textAlignment: NSTextAlignment = .natural
137        var isHidden = false
138        var text: String = "Payment details"
139        var font = UIFont(size: 24)
140        var backgroundColor: UIColor = .clear
141        var textColor: UIColor = Constants.mainFontColor
142    }
143
144    struct PaymentHeaderSubtitle: ElementStyle {
145        var textAlignment: NSTextAlignment = .natural
146        var isHidden = false
147        var text: String = "Visa, Mastercard and Maestro accepted."
148        var font = UIFont(size: 12)
149        var backgroundColor: UIColor = .clear
150        var textColor: UIColor = Constants.mainFontColor
151    }
152
153    struct CardNumberSection: CellTextFieldStyle {
154        var isMandatory = true
155        var backgroundColor: UIColor = .clear
156        var textfield: ElementTextFieldStyle = TextFieldStyle()
157        var title: ElementStyle? = TitleStyle(text: "Card number")
158        var mandatory: ElementStyle? = MandatoryStyle(text: "")
159        var hint: ElementStyle?
160        var error: ElementErrorViewStyle? = ErrorViewStyle(text: "Insert a valid card number")
161    }
162
163    struct ExpiryDateSection: CellTextFieldStyle {
164        var textfield: ElementTextFieldStyle = TextFieldStyle(placeholder: "_ _ / _ _")
165        var isMandatory = true
166        var backgroundColor: UIColor = .clear
167        var title: ElementStyle? = TitleStyle(text: "Expiry date")
168        var mandatory: ElementStyle? = MandatoryStyle(text: "")
169        var hint: ElementStyle?
170        var error: ElementErrorViewStyle? = ErrorViewStyle(text: "Insert a valid expiry date")
171    }
172
173    struct SecurityNumberSection: CellTextFieldStyle {
174        var textfield: ElementTextFieldStyle = TextFieldStyle()
175        var isMandatory = true
176        var backgroundColor: UIColor = .clear
177        var title: ElementStyle? = TitleStyle(text: "Security code")
178        var mandatory: ElementStyle? = MandatoryStyle(text: "")
179        var hint: ElementStyle?
180        var error: ElementErrorViewStyle? = ErrorViewStyle(text: "Insert a valid security code")
181    }
182
183    struct TextFieldStyle: ElementTextFieldStyle {
184        var textAlignment: NSTextAlignment = .natural
185        var text: String = ""
186        var isSupportingNumericKeyboard = true
187        var height: Double = 56
188        var cornerRadius: CGFloat = Constants.borderRadius
189        var borderWidth: CGFloat = Constants.borderWidth
190        var placeholder: String?
191        var tintColor: UIColor = Constants.mainFontColor
192        var normalBorderColor: UIColor = .clear
193        var focusBorderColor: UIColor = .clear
194        var errorBorderColor: UIColor = Constants.errorColor
195        var isHidden = false
196        var font = UIFont(size: 15)
197        var backgroundColor: UIColor = Constants.textFieldBackgroundColor
198        var textColor: UIColor = Constants.mainFontColor
199    }
200
201    struct TitleStyle: ElementStyle {
202        var textAlignment: NSTextAlignment = .natural
203        var text: String
204        var isHidden = false
205        var font = UIFont(size: 15)
206        var backgroundColor: UIColor = .clear
207        var textColor: UIColor = Constants.mainFontColor
208    }
209
210    struct MandatoryStyle: ElementStyle {
211        var textAlignment: NSTextAlignment = .natural
212        var text: String
213        var isHidden = false
214        var font = UIFont(size: 13)
215        var backgroundColor: UIColor = .clear
216        var textColor: UIColor = Constants.secondaryFontColor
217    }
218
219    struct SubtitleElementStyle: ElementStyle {
220        var textAlignment: NSTextAlignment = .natural
221        var text: String
222        var textColor: UIColor = Constants.secondaryFontColor
223        var backgroundColor: UIColor = .clear
224        var tintColor: UIColor = Constants.mainFontColor
225        var image: UIImage?
226        var height: Double = 30
227        var isHidden = false
228        var font = UIFont(size: 13)
229    }
230
231    struct ErrorViewStyle: ElementErrorViewStyle {
232        var textAlignment: NSTextAlignment = .natural
233        var text: String
234        var textColor: UIColor = Constants.errorColor
235        var backgroundColor: UIColor = .clear
236        var tintColor: UIColor = Constants.errorColor
237        var image: UIImage?
238        var height: Double = 30
239        var isHidden = true
240        var font = UIFont(size: 13)
241    }
242
243    struct BillingStartButton: CellButtonStyle {
244        var isMandatory = true
245        var button: ElementButtonStyle = AddBillingDetailsButtonStyle()
246        var backgroundColor: UIColor = .red// .clear
247        var title: ElementStyle? = TitleStyle(text: "Billing address")
248        var mandatory: ElementStyle?
249        var hint: ElementStyle? = {
250            var element = SubtitleElementStyle(text: "We need this information as an additional security measure to verify this card.")
251            element.textColor = Constants.mainFontColor
252            return element
253        }()
254        var error: ElementErrorViewStyle?
255    }
256
257    struct BillingSummaryStyle: BillingSummaryViewStyle {
258        var summary: ElementStyle? = BillingSummaryElementStyle(text: "")
259        var cornerRadius: CGFloat = Constants.borderRadius
260        var borderWidth: CGFloat = Constants.borderWidth
261        var separatorLineColor: UIColor = Constants.secondaryFontColor
262        var borderColor: UIColor = Constants.mainFontColor
263        var button: ElementButtonStyle = AddBillingDetailsButtonStyle(textLeading: 20, text: "\u{276F} Update Billing Address")
264        var isMandatory = true
265        var backgroundColor: UIColor = .clear
266        var title: ElementStyle? = TitleStyle(text: "Billing address")
267        var mandatory: ElementStyle?
268        var hint: ElementStyle? = {
269            var element = SubtitleElementStyle(text: "We need this information as an additional security measure to verify this card.")
270            element.textColor = Constants.mainFontColor
271            return element
272        }()
273        var error: ElementErrorViewStyle?
274    }
275
276    struct AddBillingDetailsButtonStyle: ElementButtonStyle {
277        var textAlignment: NSTextAlignment = .natural
278        var isEnabled = true
279        var disabledTextColor: UIColor = Constants.secondaryFontColor
280        var disabledTintColor: UIColor = Constants.secondaryFontColor
281        var activeTintColor: UIColor = Constants.mainFontColor
282        var imageTintColor: UIColor = .clear
283        var normalBorderColor: UIColor = .clear
284        var focusBorderColor: UIColor = .clear
285        var errorBorderColor: UIColor = .clear
286        var image: UIImage?
287        var textLeading: CGFloat = 0
288        var cornerRadius: CGFloat = 0
289        var borderWidth: CGFloat = 0
290        var height: Double = 56
291        var width: Double = 300
292        var isHidden = false
293        var text: String = "\u{276F} Add billing address"
294        var font = UIFont(sfMono: .semibold, size: 15)
295        var backgroundColor: UIColor = .clear
296        var textColor: UIColor = Constants.mainFontColor
297    }
298
299    struct BillingFullNameInput: CellTextFieldStyle {
300        var textfield: ElementTextFieldStyle = TextFieldStyle(isSupportingNumericKeyboard: false)
301        var isMandatory = true
302        var backgroundColor: UIColor = .clear
303        var title: ElementStyle? = TitleStyle(text: "Full name")
304        var mandatory: ElementStyle?
305        var hint: ElementStyle?
306        var error: ElementErrorViewStyle?
307    }
308
309    struct BillingAddressLine1Input: CellTextFieldStyle {
310        var textfield: ElementTextFieldStyle = TextFieldStyle(isSupportingNumericKeyboard: false)
311        var isMandatory = true
312        var backgroundColor: UIColor = .clear
313        var title: ElementStyle? = TitleStyle(text: "Address line 1")
314        var mandatory: ElementStyle?
315        var hint: ElementStyle?
316        var error: ElementErrorViewStyle?
317    }
318
319    struct BillingAddressLine2Input: CellTextFieldStyle {
320        var textfield: ElementTextFieldStyle = TextFieldStyle(isSupportingNumericKeyboard: false)
321        var isMandatory = false
322        var backgroundColor: UIColor = .clear
323        var title: ElementStyle? = TitleStyle(text: "Address line 2")
324        var mandatory: ElementStyle? = MandatoryStyle(text: "Optional")
325        var hint: ElementStyle?
326        var error: ElementErrorViewStyle?
327    }
328
329    struct BillingCityInput: CellTextFieldStyle {
330        var textfield: ElementTextFieldStyle = TextFieldStyle(isSupportingNumericKeyboard: false)
331        var isMandatory = true
332        var backgroundColor: UIColor = .clear
333        var title: ElementStyle? = TitleStyle(text: "City")
334        var mandatory: ElementStyle?
335        var hint: ElementStyle?
336        var error: ElementErrorViewStyle?
337    }
338
339    struct BillingStateInput: CellTextFieldStyle {
340        var textfield: ElementTextFieldStyle = TextFieldStyle(isSupportingNumericKeyboard: false)
341        var isMandatory = true
342        var backgroundColor: UIColor = .clear
343        var title: ElementStyle? = TitleStyle(text: "State")
344        var mandatory: ElementStyle?
345        var hint: ElementStyle?
346        var error: ElementErrorViewStyle?
347    }
348
349    struct BillingPostcodeInput: CellTextFieldStyle {
350        var textfield: ElementTextFieldStyle = TextFieldStyle(isSupportingNumericKeyboard: false)
351        var isMandatory = true
352        var backgroundColor: UIColor = .clear
353        var title: ElementStyle? = TitleStyle(text: "Postcode/Zip")
354        var mandatory: ElementStyle?
355        var hint: ElementStyle?
356        var error: ElementErrorViewStyle?
357    }
358
359    struct BillingCountryInput: CellButtonStyle {
360        var button: ElementButtonStyle = BillingCountryButton()
361        var isMandatory = true
362        var backgroundColor: UIColor = .clear
363        var title: ElementStyle? = TitleStyle(text: "Country")
364        var mandatory: ElementStyle?
365        var hint: ElementStyle?
366        var error: ElementErrorViewStyle?
367    }
368
369    struct BillingPhoneInput: CellTextFieldStyle {
370        var textfield: ElementTextFieldStyle = TextFieldStyle()
371        var isMandatory = true
372        var backgroundColor: UIColor = .clear
373        var title: ElementStyle? = TitleStyle(text: "Phone number")
374        var mandatory: ElementStyle?
375        var hint: ElementStyle? = SubtitleElementStyle(text: "We will only use this to confirm identity if necessary")
376        var error: ElementErrorViewStyle?
377    }
378
379    struct BillingSummaryElementStyle: ElementStyle {
380        var textAlignment: NSTextAlignment = .natural
381        var isHidden = false
382        var text: String
383        var font = UIFont(size: 14)
384        var backgroundColor: UIColor = .clear
385        var textColor: UIColor = Constants.secondaryFontColor
386    }
387
388    struct BillingCountryButton: ElementButtonStyle {
389        var textAlignment: NSTextAlignment = .natural
390        var isEnabled = true
391        var disabledTextColor: UIColor = Constants.secondaryFontColor
392        var disabledTintColor: UIColor = .clear
393        var activeTintColor: UIColor = Constants.mainFontColor
394        var imageTintColor: UIColor = Constants.mainFontColor
395        var normalBorderColor: UIColor = .clear
396        var focusBorderColor: UIColor = .clear
397        var errorBorderColor: UIColor = .clear
398        var image: UIImage? = UIImage(named: "arrow_green_down")
399        var textLeading: CGFloat = 20
400        var cornerRadius: CGFloat = Constants.borderRadius
401        var borderWidth: CGFloat = 0
402        var height: Double = 20
403        var width: Double = 80
404        var isHidden = false
405        var text: String = "Please select a country"
406        var font = UIFont(size: 15)
407        var backgroundColor: UIColor = Constants.textFieldBackgroundColor
408        var textColor: UIColor = Constants.secondaryFontColor
409    }
410}

See an example on our GitHub project.

We've made some changes to our API

Customize the iOS SDK

Default form

Themed form

Custom form