Integrate PayGate Global payment platform seamlessly into your Flutter applications with support for T-Money and Moov Money (Flooz) payment providers.
- 🔄 Dual API Support: Choose between API v1 (direct) and v2 (hosted page)
- 📱 Mobile Money Integration: Support for T-Money and Moov Money
- 🔒 Secure Payments: All transactions are secured by PayGate Global
- ✅ Transaction Verification: Built-in status checking
Add to your pubspec.yaml:
dependencies:
flutter_paygateglobal: ^0.1.5Run:
flutter pub get
## Defining terms uses
- Transaction identifier : identifier you generate yourself (or let this plugin generate) and with which you will be able to identify the transaction and check it's status.
- Transaction amount : amount of money you want to take from user mobile money account.
- Transaction callbackUrl : url you want to be called when the transaction is completed.
- Transaction provider : providers are (at this instant) MoovAfrica (MoovMoney) and Togocom (TMoney).
- Transaction Reference : reference generated by Paygate Global itself. You can also use it to check transaction status.
## Getting started
Before you start to use this package, you need to have a Paygate API Key. Create an account on the [Paygate Website](https://paygateglobal.com/), fill your E-Commerce platform informations and you will receive your account APi Key.
## Usage
First of all you need to initialize the plugin. Just call the Paygate.init() method. This method require your production Paygate API Key.
You can also configure the API version you want to use per default when you call the _pay_ method without specifying the version to use (if not specified the second method is used per default).
```dart
Paygate.init(
apiKey: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
apiVersion: PaygateVersion.v1, // default PaygateVersion.v2
apiKeyDebug: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', // optional
identifierLength: 20, // optional, default 20
);You can initialize with a additionnal API key used when you are in debug. You can also specify the default length of the identifiers generated by the plugin (default = 20).
Paygate has two API versions. Depends on when you want to make a request post, or use the preconfigured payment page with a get request.
- You make a post request and Paygate return the payment transaction reference with which you can check later the transaction status.
NewTransactionResponse response = await Paygate.payV1(
amount: 1000,
provider: PaygateProvider.moovMoney, // required : PaygateProvider.moovMoney or PaygateProvider.tMoney
identifier: 'TR000000010', // optional : if empty, the transaction identifier will be generated by the plugin.
description: 'My awesome transaction', // optional : description of the transaction
phoneNumber: '90010203', // required : phone number of the user
);
if (response.ok) {
print('Transaction initiated: ${response.txReference}');
// Save reference for later verification
} else {
print('Transaction failed: ${response.exception}');
}2.You make a get request to a payment page provided and secured by Paygate.
NewTransactionResponse response = await Paygate.payV2(
amount: 1000,
callbackUrl: 'https://myapp.com/callback',
provider: PaygateProvider.moovMoney, // required : PaygateProvider.moovMoney or PaygateProvider.tMoney
identifier: 'TR000000010', // optional : if empty, the transaction identifier will be generated by the plugin.
description: 'My awesome transaction', // optional : description of the transaction
phoneNumber: '90010203', // required : phone number of the user
);
if (response.ok) {
print('Payment page opened: ${response.txReference}');
}Once payment is made by the customer, PayGateGlobal will send a confirmation message to the e-commerce return URL (If previously provided). The message is HTTP Post Method, served with JSON payload, structured as follows:
| Property | Description |
|---|---|
| tx_reference | Unique identifier generated by PayGateGlobal for the transaction |
| identifier | Internal identifier of the e-commerce transaction. |
| payment_reference | Payment reference code generated by Flooz. |
| amount | Amount paid by customer |
| datetime | Payment Date and Time |
| phone_number | Telephone number of the customer who made the payment. |
| payment_method | Payment method used by the customer. Possible values: FLOOZ, T-Money. |
With either method 1 or 2, user never quit the application. This package use the custom_tabs package to open the Paygate Global payment page, when you the API version 2.
After you have initialized a transaction, you can check the status of the transaction with the verify method, called on the response (NewTransactionResponse) object. Or either juste the static method verifyTransaction, which require the transaction reference or the identifier.
if (response.ok) {
saveReference(response.txReference); // or save the identifier in your database saveIdentifier(response.identifier);
} else {
// Retry or debug (a message will be displayed in the console).
/// You can access the exception with response.exception .
}
// After a delay, you can check the transaction status.
Transaction transaction = await response.verify();
// Or using static method
Transaction transaction = await Paygate.verifyTransaction(
txReference: 'your-tx-reference', // From PayGate
// OR
trxIdentifier: 'your-identifier', // Your custom identifier
);
switch (transaction.status) {
case TransactionStatus.success:
print('Payment successful!');
break;
case TransactionStatus.pending:
print('Payment pending...');
break;
case TransactionStatus.failed:
print('Payment failed');
break;
default:
print('Unknown status');
}Please check the example directory for a complete example with suitable UI implementations.
| Provider | Code | Network | Countries |
|---|---|---|---|
| T-Money | PaygateProvider.tmoney |
Togocom | Togo |
| Moov Money (Flooz) | PaygateProvider.moovMoney |
Moov Africa | Togo |
- Initiate: Call
payV1()orpayV2() - Process: User completes payment via mobile money
- Callback: PayGate sends confirmation to your callback URL (v2 only)
- Verify: Check transaction status programmatically
- Complete: Handle successful/failed payments in your app
When using API v2, PayGate sends this JSON to your callback URL:
{
"tx_reference": "PG_12345_67890",
"identifier": "your_custom_identifier",
"payment_reference": "TM_98765_43210",
"amount": "1000",
"datetime": "2024-01-15T10:30:00Z",
"phone_number": "90123456",
"payment_method": "T-Money"
}Run tests:
flutter testTest with mock data:
void initTestEnvironment() {
Paygate.init(
apiKey: 'test-api-key-12345678-1234-1234-1234-123456789012',
apiVersion: PaygateVersion.v2,
);
}Invalid Phone Number
- Ensure format: 8 digits starting with 9, 7, or 2
- Examples:
90123456,70123456,22890123456
Transaction Failed
- Check your API key validity
- Verify phone number has sufficient balance
- Ensure amount is between 1 and 1,000,000 CFA
Network Errors
- Check internet connectivity
- Verify PayGate Global service status
- Test with debug API key first
Paygate: Main class for payment operationsNewTransactionResponse: Response from payment initiationTransaction: Transaction status and detailsPaygateProvider: Enum for payment providersPaygateVersion: Enum for API versions
PaygateValidationException: Invalid input parametersPaygateNetworkException: Network connectivity issuesPaygateApiException: API-related errorsPaygateConfigurationException: Setup/configuration issues
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE
- 📧 Email: agbavonbienvenu@gmail.com
- 🐛 Issues: GitHub Issues
See CHANGELOG.md for version history.
Made with ❤️ for the Flutter community, by The Authentic Dev (https://00auth.dev).