Native Pay Methods
Apple Pay
In the Flutter SDK, Apple Pay can be used to process payments with a smooth, native experience. Before displaying the Apple Pay sheet, it is essential to:
- Configure Apple Pay (optionally) to collect billing data.
- Ensure that the device supports Apple Pay.
- Decide which approach to use for processing payments.
1. (Optional) Configuring Apple Pay to Collect Billing Data
If you need to collect specific billing data from the user during the payment process and use it as part of the billing data, you can configure the collectibleBillingData
accordingly.
import 'package:moneyhash/moneyhash.dart';
void main() {
// Create a custom Apple Pay configuration
final applePayConfig = ApplePayConfiguration(
collectibleBillingData: [CollectibleBillingData.email],
);
// Initialize the SDK with the custom Apple Pay configuration
final moneyHash = MoneyHashSDKBuilder()
.setNativeApplePayConfig(applePayConfig)
.build();
print("MoneyHash SDK initialized with Apple Pay configuration.");
}
collectibleBillingData
is a list ofCollectibleBillingData
enums. Currently, onlyCollectibleBillingData.email
is available.- To disable billing data collection, you can pass an empty list
[]
.
2. Check if the Device is Compatible with Apple Pay
Before attempting to show the Apple Pay sheet, confirm that the device supports Apple Pay by calling:
final isCompatible = await moneyHash.isDeviceCompatibleWithApplePay();
if (isCompatible) {
// Proceed with Apple Pay
} else {
// Handle case where the device is not compatible
print("This device does not support Apple Pay");
}
Note: This feature is only supported on iOS devices. Calling this method on other platforms will throw an
UnsupportedError
.
Approaches for Apple Pay Payments
You can handle Apple Pay payments in two different ways:
- Approach #1: Directly use
proceedWithApplePay
(requires anintentId
upfront). - Approach #2: Generate an Apple Pay receipt first, then submit that receipt separately (no
intentId
initially required).
Approach #1: Direct Payment with proceedWithApplePay
proceedWithApplePay
If you already have your intentId
, you can directly display the Apple Pay sheet and complete the payment in one step using proceedWithApplePay
.
Retrieve Apple Pay Data from NativePay State
When handling an intent state, you may receive a NativePay
state that includes an ApplePayData
object. It typically contains:
merchantId
: The Apple Pay merchant identifiercountryCode
: The country code for the paymentcurrencyCode
: The currency code for the paymentamount
: The total amount for the payment
These values can be passed into proceedWithApplePay
.
Code Example:
if (intentState is NativePay) {
final applePayData = intentState.nativePayData as ApplePayData?;
if (applePayData != null) {
try {
final intentId = "<intent_id>"; // Unique identifier for the payment intent
final depositAmount = applePayData.amount ?? 0.0;
final merchantIdentifier = applePayData.merchantId ?? "merchant.com.example";
final currencyCode = applePayData.currencyCode ?? "USD";
final countryCode = applePayData.countryCode ?? "US";
// Display Apple Pay sheet and process payment
final IntentDetails? intentDetails = await moneyHash.proceedWithApplePay(
intentId,
depositAmount,
merchantIdentifier,
currencyCode,
countryCode,
);
if (intentDetails != null) {
// Handle successful payment
print("Payment completed successfully: $intentDetails");
} else {
// Handle case where no result is returned
print("Payment was cancelled or no result was returned.");
}
} on MHException catch (e) {
// Handle any Apple Pay errors
print("Error during Apple Pay: ${e.message}");
}
} else {
print("No Apple Pay data available in NativePay state.");
}
}
- This displays the Apple Pay sheet to the user, processes the payment, and returns
IntentDetails
on success or throws an error (MHException
) if something goes wrong. - If billing data is required but not configured or available, the SDK will throw an error prompting you to supply the needed data.
Approach #2: Generate a Receipt First, Then Submit the Receipt
This new approach does not require an intentId
up front. Instead, you generate an Apple Pay receipt, and once you have or create an intentId
, you submit that receipt.
Step 1: Generate the Apple Pay Receipt
Use generateApplePayReceipt
to show the Apple Pay sheet, collect payment data, and generate a NativePayReceipt
without requiring an intentId
:
if (intentState is NativePay) {
final applePayData = intentState.nativePayData as ApplePayData?;
if (applePayData != null) {
try {
// Extract payment details from applePayData
final depositAmount = applePayData.amount ?? 0.0;
final merchantIdentifier = applePayData.merchantId ?? "merchant.com.example";
final currencyCode = applePayData.currencyCode ?? "USD";
final countryCode = applePayData.countryCode ?? "US";
// Show Apple Pay sheet and generate the receipt
final NativePayReceipt? receipt = await moneyHash.generateApplePayReceipt(
depositAmount,
merchantIdentifier,
currencyCode,
countryCode,
);
if (receipt != null) {
print("Apple Pay Receipt generated successfully: $receipt");
// Store 'receipt' until you're ready to submit the payment
} else {
print("Apple Pay receipt generation was cancelled.");
}
} on MHException catch (e) {
// Handle any Apple Pay errors
print("Error generating Apple Pay receipt: ${e.message}");
}
} else {
print("No Apple Pay data available in NativePay state.");
}
}
Important: The generated
NativePayReceipt
is only valid for a short period. Make sure to submit it promptly once you have theintentId
.
Step 2: Submit the Payment Receipt
After generating the NativePayReceipt
, use submitPaymentReceipt
to finalize the payment. This method requires an intentId
.
try {
final intentId = "<intent_id>"; // Obtain or generate this after receipt creation
// Submit the receipt to complete the payment
final IntentDetails? intentDetails = await moneyHash.submitPaymentReceipt(
intentId,
receipt,
);
if (intentDetails != null) {
print("Payment completed successfully: $intentDetails");
} else {
print("Payment was cancelled or no result was returned.");
}
} on MHException catch (e) {
// Handle error during payment submission
print("Error submitting payment receipt: ${e.message}");
}
If billing data is required but not provided, the SDK will throw an
MHException
prompting you to supply the necessary information before completing the payment.
Google Pay
(No changes from your original text are required here, since the question specifically requested Apple Pay documentation updates. The Google Pay documentation remains as provided.)
Summary
- Configure (Optional): Call
setNativeApplePayConfig(...)
inMoneyHashSDKBuilder
to specify any billing data Apple Pay may collect (e.g.,email
). - Check Compatibility: Always verify that the device supports Apple Pay using
isDeviceCompatibleWithApplePay()
. - Approach #1 (Direct): If you already have an
intentId
, useproceedWithApplePay
to handle everything in one go. - Approach #2 (Two-Step): If you don’t have an
intentId
initially or want to separate generation of the Apple Pay receipt from final payment submission, usegenerateApplePayReceipt
first, then callsubmitPaymentReceipt
once you have theintentId
.
By following these steps, you can integrate Apple Pay into your Flutter application using the MoneyHash SDK, providing users with a seamless and secure payment experience.
Updated 30 days ago