Skip to main content

The Hashtech

How Do I Add Apple Pay and STC Pay to My App?

Published Date
4 November, 2026
How Do I Add Apple Pay and STC Pay to My App?

To add Apple Pay and STC Pay, you usually do not connect to either one directly. You choose a payment gateway that supports both, set up Apple Pay in your Apple Developer account, enable STC Pay on your merchant account, and then use the gateway’s SDK or API. Your app collects the payment, and your backend confirms the result with the gateway.

The setup is mostly configuration. The mistakes come from certificates, missing payment networks, and trusting the app instead of the server. This guide covers both methods, step by step.

How Apple Pay and STC Pay Work

The two methods feel different to users, and they run differently under the hood.

Apple Pay STC Pay
Type Tokenized card payment on Apple devices Digital wallet payment
User action Taps the Apple Pay button, then confirms with Face ID, Touch ID, or passcode Enters an STC Pay mobile number, then an SMS one-time code
Platforms iPhone, iPad, Apple Watch, and Safari Any app, through a gateway SDK or API
What you need Apple Developer account, Merchant ID, payment processing certificate STC Pay merchant account and merchant ID
Currency Set by your merchant account Saudi riyal (SAR) only
Confirmation Encrypted token sent to your gateway Gateway confirms after the code is verified

Both usually settle through your payment gateway. That is why the first decision is the gateway.

Step 1: Choose a Payment Gateway

Pick the gateway before you touch any code. Check these points:

  • It supports both Apple Pay and STC Pay
  • It supports the MADA network for Apple Pay
  • It offers an SDK for your framework (Swift, Kotlin, Flutter, or React Native)
  • It settles in SAR and fits your bank
  • It offers a sandbox with test codes
  • Its fees, onboarding documents, and timeline are clear in writing

Several gateways publish documentation for these methods. For example, Moyasar documents Apple Pay and STC Pay for iOS and Flutter. Checkout.com documents STC Pay for mobile apps through its Flow component. Amazon Payment Services documents STC Pay with a mobile SDK. Geidea and Noon Payments document Apple Pay with the mada network. Coverage changes, so confirm the current list before you commit.

Prefer the Gateway-Managed Certificate Route

Some gateways let you manage the Apple Pay payment processing certificate on their side. Others let you manage it on your own backend. The second route puts you in a higher PCI DSS scope. For most apps, the gateway-managed route is simpler and safer.

Step 2: Add Apple Pay (iOS)

Follow this order on iOS.

  1. Create a Merchant ID. Register it in your Apple Developer account. One Merchant ID can serve several apps.
  2. Create the payment processing certificate. Your gateway gives you a certificate signing request (CSR). Upload it in Apple Developer, download the certificate, and upload it back to the gateway.
  3. Enable Apple Pay for your App ID. Then regenerate your provisioning profiles.
  4. Add the Apple Pay capability in Xcode. Select your Merchant ID. The ID in your code must match the one in the entitlement.
  5. Build the payment request. Set the country, currency, summary items, and supported networks.
  6. Show the Apple Pay button. Display it only if the device can make payments.
  7. Present the payment sheet. Use the PassKit authorization controller.
  8. Send the token to your backend. Your backend forwards it to the gateway.
  9. Close the sheet with the real result. Report success or failure only after the backend confirms.

Our custom iOS app development team follows this order on every Apple Pay project.

The Payment Request

Here is a minimal Swift example for Saudi Arabia:

let request = PKPaymentRequest()

request.merchantIdentifier = “merchant.com.yourcompany.app”

request.countryCode = “SA”

request.currencyCode = “SAR”

request.supportedNetworks = [.visa, .masterCard, .mada]

request.merchantCapabilities = .threeDSecure

request.paymentSummaryItems = [

    PKPaymentSummaryItem(

        label: “Order 1234”,

        amount: NSDecimalNumber(string: “99.00”)

    )

]

Do not forget .mada in the supported networks. Gateway documentation states that you must include it to accept Mada cards. Without it, many Saudi cards will not appear in the payment sheet.

Step 3: Add STC Pay (iOS and Android)

STC Pay works the same way on both platforms. The user enters a phone number, receives a one-time code by SMS, and confirms it.

  1. Open an STC Pay merchant account. Complete verification in STC Pay’s merchant process.
  2. Get your merchant ID. You can find it in STC Pay’s merchant portal.
  3. Ask your gateway to enable STC Pay. Send your merchant ID to your account manager.
  4. Build the phone number screen. Ask for a Saudi mobile number and validate the format.
  5. Start the payment. Your SDK or backend sends the number and amount to the gateway.
  6. Build the code screen. The user enters the SMS code. Show a countdown and a resend option.
  7. Confirm the payment. The gateway verifies the code and returns a status.
  8. Verify on the server. Use the gateway’s webhook before you mark the order paid.

Most gateway SDKs include a ready-made STC Pay view that handles the phone number and code steps. Use it first. Build a custom screen only when your design needs it.

Step 4: Handle Android

Apple Pay does not run in Android apps. Apple Pay works on Apple devices. For Android users, offer these options instead:

  • Google Pay. Gateways support it through their Android SDKs. Saudi Arabia added Google Pay through the Mada network in 2025.
  • STC Pay. Use the same gateway SDK and the same phone and code flow.
  • Cards. Offer Mada and international cards through the gateway form.

If you build with Flutter or React Native, you can share most of the checkout logic across both platforms. You still configure Apple Pay only on iOS. Our Android app development team builds Google Pay and wallet flows alongside the iOS checkout so both platforms launch together.

Backend Rules That Protect Your Money

The app collects the payment, but the backend decides what is true.

  • Never trust the app for success. Mark an order paid only after the gateway confirms through a webhook or a server call.
  • Set the amount on the server. Do not let the app send the final price.
  • Save the gateway payment ID. You need it for refunds and reconciliation.
  • Make requests idempotent. A double tap should not create two charges.
  • Keep keys on the server. Secret keys never belong in the app.
  • Do not log tokens or codes. Treat payment data as sensitive.
  • Handle every status. Plan for pending, paid, failed, and expired payments.

Checkout UX Details

A correct integration can still lose sales if checkout feels unclear.

  • Show Apple Pay only when it is available. Hide the button on devices that cannot use it.
  • Put the fastest option first. Apple Pay or a saved method should lead.
  • Validate the phone number early. Catch format errors before the SMS is sent.
  • Show the code timer. Users should see how long the code lasts.
  • Write clear Arabic errors. “Payment declined” should explain what to do next.
  • Offer a fallback. If STC Pay fails, let users switch to a card without starting over.

Payments and Arabic localization also shape your budget. We explain how in our guide to mobile app development cost in Saudi Arabia.

An App Store Rule to Check

Apple treats digital goods differently from physical goods and services. Digital content and subscriptions used inside the app generally use Apple’s in-app purchase. Physical goods and services that users consume outside the app, such as deliveries, bookings, and retail orders, can use Apple Pay and other payment methods. Check the current guidelines for your exact product before you design checkout.

Testing Checklist

Run these checks in the gateway sandbox, then with small live payments.

  • Apple Pay success on a real device
  • Apple Pay cancel and decline
  • A mada card in the Apple Pay sheet
  • STC Pay success with a test code
  • STC Pay wrong code and expired code
  • Weak network during payment
  • App sent to the background mid-payment
  • Double taps and repeated requests
  • Webhook delay and duplicate webhooks
  • Refund and reconciliation
  • Arabic and English screens

Common Mistakes When You Add Apple Pay and STC Pay

  1. Forgetting .mada. Many Saudi cards will not show up.
  2. Mismatched Merchant IDs. The ID must match across your code, Xcode, Apple Developer, and the gateway.
  3. Skipping the provisioning profile refresh. The capability change invalidates old profiles.
  4. Trusting the client. Always verify payment status on the server.
  5. Building a custom STC Pay screen too early. The SDK view already handles the flow.
  6. Ignoring webhooks. Users close apps mid-payment, so the app may never see the result.
  7. No fallback. A single failed method should not end the sale.
  8. Testing only success. Declines, timeouts, and wrong codes cause most support tickets.

Cost and Timeline

Gateway fees, onboarding time, and settlement terms differ by provider, and no single public price applies. Ask each gateway for fees and onboarding steps in writing. Add development time for the checkout screens, backend, webhooks, and testing.

Planning payments early also helps the whole build. Our team of mobile app development in Saudi Arabia scopes payments during discovery, so certificates, merchant accounts, and approvals start before the checkout screens are ready.

Final Thoughts

To add Apple Pay and STC Pay cleanly, start with the gateway, finish the account setup early, and keep the server in charge of payment truth. Apple Pay gives iPhone users a fast, secure tap. STC Pay gives wallet users a familiar code-based flow. Together, they cover many Saudi shoppers.

Teams that plan certificates, merchant IDs, and webhooks in the first sprint avoid the long delays at the end. The integration code is small. The setup around it is what takes time.

Frequently Asked Questions

Do I need a payment gateway to add Apple Pay and STC Pay?

In most cases, yes. A gateway receives the Apple Pay token or confirms the STC Pay code, then settles the money to you. Most apps use a gateway that supports both methods.

Does Apple Pay support mada cards?

Yes, when your gateway and your payment request support the MADA network. Include the MADA network in your supported networks list.

Can I use Apple Pay in an Android app?

No. Apple Pay works on Apple devices. Offer Google Pay, STC Pay, and card payments to Android users.

How does STC Pay work in an app?

The user enters an STC Pay mobile number, receives a one-time code by SMS, and enters it in your app. The gateway verifies the code and confirms the payment.

Does STC Pay support currencies other than SAR?

Gateway documentation states that STC Pay supports Saudi riyal transactions only.

Can I use Apple Pay for digital subscriptions inside my iOS app?

Digital content and subscriptions inside an iOS app generally need Apple’s in-app purchase. Apple Pay fits physical goods and services. Check the current App Store guidelines for your case.

Do I need PCI compliance?

Card data security rules still apply. Using a gateway-managed flow keeps raw card data away from your servers and reduces your scope. Confirm your obligations with your gateway and compliance team.

Technical details come from public documentation from Apple and from payment gateways including Moyasar, Checkout.com, Amazon Payment Services, Geidea, and Noon Payments. Gateways and Apple update their requirements often, so confirm the latest steps in your own accounts before you build.

Planning Payments for Your App?

We set up gateways, certificates, and checkout flows for iOS and Android. Talk to our team and we will scope Apple Pay and STC Pay before you commit to a build.

 

Lara Hawkins
Lara Hawkins is a Senior Content Writer Specialist with expertise in creating clear and SEO-focused content. She specializes in technology, mobile app development, business, and education topics, helping brands communicate complex ideas in a simple and reader-friendly way.