Low-level API integration

Build your own entirely custom UI on top of our low-level APIs. Make sure you add dependency for Airwallex or AirwallexPayment.

How it works

The diagram below depicts the integration flow for a card payment.

Prepare payment session

Before using the low-level APIs, you need to create a payment session. See Prepare payment session for details on setting up the environment, creating a customer, payment intent, and payment session.

Collect payment information using custom UI

For native UI integration, this step is handled by the Airwallex-provided UI. For low-level API integration, you must implement your own UI to collect all the information required for payment.

Create PaymentSessionHandler

PaymentSessionHandler is at the center of the API integration.

1let paymentSessionHandler = PaymentSessionHandler(
2    session: "The session created above",
3    viewController: "hosting view controller which also handles AWXPaymentResultDelegate"
4)
5// store the `paymentSessionHandler` in your view controller or class that is tied to your view's lifecycle
6self.paymentSessionHandler = paymentSessionHandler

Pay with card

1// Confirm intent with card and billing
2paymentSessionHandler.startCardPayment(
3    with: "The AWXCard object collected by your custom UI",
4    billing: "The AWXPlaceDetails object collected by your custom UI"
5)

Pay with saved card (consent)

Pay with consent object - Confirm intent with a payment consent object (AWXPaymentConsent):

1paymentSessionHandler.startConsentPayment(with: "payment consent")

Pay with consent ID - Confirm intent with a valid payment consent ID only when the card is saved as network token:

1paymentSessionHandler.startConsentPayment(withId: "consent ID")

Pay with Apple Pay

1paymentSessionHandler.startApplePay()

Pay with redirect

1paymentSessionHandler.startRedirectPayment(
2    with: "payment method name",
3    additionalInfo: "all required information"
4)

Handle payment result

Implement AWXPaymentResultDelegate to receive payment lifecycle callbacks.

1func paymentViewController(_ controller: UIViewController?, didCompleteWith status: AirwallexPaymentStatus, error: Error?) {
2    // call back for status success / in progress / failure / cancel
3}
4
5func paymentViewController(_ controller: UIViewController?, didCompleteWithPaymentConsentId paymentConsentId: String) {
6    // If the payment consent is created during payment process, you can implement this optional function to get the ID of this payment consent for any further usage.
7}

Retrieve the payment result

For any actions subsequent to the payment such as shipping goods or sending email receipts, you can retrieve the payment result using the following options:

• Webhooks: Set up webhooks to receive notifications related to payment lifecycle events. For example, Airwallex sends the payment_intent.succeeded event when a payment succeeds. To build a reliable integration, listen for these events rather than waiting for the client-side redirect. On the client, the shopper could close the browser window or quit the app before your return URL handler is executed. For information on how to set up webhooks and listen for events, see Getting started with webhooks.

• API: On your server, call Retrieve a PaymentIntent API to inspect the status of the PaymentIntent object API.

• Web app: Check the Payment Activity screen on your Airwallex web app.