Usage Guide

Learn how to use the @guiddini/react-native-epay SDK for seamless payments in your React Native app.

Getting Started

This guide covers how to use the @guiddini/react-native-epay SDK to initiate and manage payments in your React Native application.

1. Importing the SDK

Ensure you have installed the SDK as per the Installation Guide. Then, import the necessary modules:

import { useGPay } from "@guiddini/react-native-epay";

2. Initializing a Payment

To start a payment transaction, use the initiatePayment method from the useGPay hook:

const { initiatePayment } = useGPay();
 
const handlePayment = async () => {
  try {
    const response = await initiatePayment(100); // Amount in your currency unit
    console.log("Payment Response:", response);
  } catch (error) {
    console.error("Payment Error:", error);
  }
};

Response Object Structure:

{
    "data": {
        "type": "transaction",
        "id": "1HYS74O4ZV2804SOCOCG",
        "attributes": {
            "amount": "2500",
            "status": "processing",
            "form_url": "https://test.satim.dz/payment/merchants/merchant1/payment_fr.html?mdOrder=Yco1duIqHQxaU4AAF4OR"
        }
    }
}

Note

A webview will automatically open to handle the payment process and the user will be redirected back to your app after the transaction is completed.

3. Deep Linking for Payment Callback

Ensure your app has deep linking configured to handle payment results. Check the Installation Guide for setup instructions.

4. Handling Payment Results

After a transaction is completed, your app will receive the order_number as a query parameter in the deep link. You can then fetch the transaction details using fetchTransaction from useGPay:

import { useGPay } from "@guiddini/react-native-epay";
import { useEffect, useState } from "react";
import { useRoute } from "@react-navigation/native";
 
const PaymentResultScreen = () => {
  const { fetchTransaction } = useGPay();
  const route = useRoute();
  const [transaction, setTransaction] = useState(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    const orderNumber = route?.params?.order_number;
    if (orderNumber) {
      fetchTransaction(orderNumber)
        .then((data) => setTransaction(data?.data))
        .catch((error) => console.error("Error fetching transaction:", error))
        .finally(() => setLoading(false));
    }
  }, [route?.params?.order_number]);
 
  if (loading) return <Text>Loading...</Text>;
 
  return (
    <View>
      <Text>Transaction Status: {transaction?.status}</Text>
      <Text>Amount: {transaction?.amount}</Text>
      <Text>Confirmation Status: {transaction?.confirmation_status}</Text>
    </View>
  );
};

Transaction Object Structure:

export interface TransactionAttributes {
  action_code: string;
  action_code_description: string;
  amount: string;
  confirmation_status: "confirmed" | "failed" | "pending";
  order_number: string;
  status: "user_cancelled" | "paid" | "pending";
}

5. Testing the Payment Flow

Before going live, test your integration using Guiddini’s sandbox environment. Use test API keys to simulate transactions.

6. Error Handling

Handle different error scenarios to enhance user experience:

try {
  const response = await initiatePayment(100);
  if (!response || response.status !== "success") {
    throw new Error(response?.message || "Unknown error");
  }
} catch (error) {
  console.error("Payment Failed:", error);
}

Conclusion

With these steps, you can efficiently integrate and manage payments using @guiddini/react-native-epay.

On this page