STC Pay Integration Guide

This guide will walk you through integrating STC Pay payments into your Flutter application using the Moyasar Flutter SDK.

Prerequisites

Before you begin, ensure you have:

1. A Moyasar account with STC Pay enabled
2. Your Moyasar publishable API key
3. Flutter SDK installed (v2.0.17 or later)

Installation

Add the latest version of the moyasar package to your pubspec.yaml:

dependencies:
  moyasar: ^2.1.2 # or the latest version

Then run:

flutter pub get

Implementation

1. Add STC Pay Component

// Initialize payment config
final paymentConfig = PaymentConfig(
  publishableApiKey: 'YOUR_PUBLISHABLE_API_KEY',
  amount: 10000, // 100.00 SAR
  description: 'Order #12345',
  metadata: {'order_id': '12345'},
);

// In your widget
STCPaymentComponent(
  config: paymentConfig,
  onPaymentResult: onPaymentResult,
)

// Payment result handler
void onPaymentResult(PaymentResult result) {
  if (result is PaymentResponse) {
    switch (result.status) {
      case PaymentStatus.paid:
        print('Payment successful: ${result.id}');
        break;
      case PaymentStatus.failed:
        print('Payment failed: ${result.message}');
        break;
      case PaymentStatus.initiated:
        print('Payment initiated: ${result.id}');
        break;
    }
  }
}

Testing

Test Environment

1. Use the sandbox environment for testing
2. Enter a valid Saudi mobile number starting with 05
3. For testing OTP:
   • Use 123456 for successful payment
   • Use 000000 for failed payment

Error Handling

Handle different payment statuses in your onPaymentResult callback:

void onPaymentResult(PaymentResult result) {
  if (result is PaymentResponse) {
    switch (result.status) {
      case PaymentStatus.paid:
        // Handle successful payment
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text('Payment successful!')),
        );
        break;
      case PaymentStatus.failed:
        // Handle failed payment
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('Payment failed: ${result.message}')),
        );
        break;
      case PaymentStatus.initiated:
        // Handle initiated state (waiting for OTP)
        break;
    }
  } else if (result is PaymentError) {
    // Handle errors
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('Error: ${result.message}')),
    );
  }
}

Production Deployment

Before going live:

1. Replace the test API key with your live publishable API key
2. Test the complete payment flow with real STC Pay accounts
3. Ensure you have proper error handling in place

Support

For any issues or questions, please contact Moyasar Support.