Skip to content

Commit 6d5d576

Browse files
YczarYczar
authored
Merge pull request #80 from Dartmind-OpenSource/feature/charge-authentication-enhancements
feat: comprehensive charge utilities, helpers, and validation framework
2 parents 9165121 + a44dfb3 commit 6d5d576

File tree

15 files changed

+4143
-0
lines changed

15 files changed

+4143
-0
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@
33
chargeIssues/dependencies.md
44
ISSUES.md
55
apps/ex02_charge_terminal/.env
6+
mind_paystack_server/

‎apps/ex02_charge_terminal/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# https://dart.dev/guides/libraries/private-files
2+
# Created by `dart pub`
3+
.dart_tool/

‎apps/ex02_charge_terminal/CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## 1.0.0
2+
3+
- Initial version.

‎apps/ex02_charge_terminal/README.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# ex02_charge_terminal
2+
3+
Terminal application demonstrating MindPaystack charge flows with card processing.
4+
5+
## Overview
6+
7+
This command-line application showcases the complete charge lifecycle using the MindPaystack SDK, including:
8+
9+
**💳 Charge Creation Options:**
10+
- **Card Charges**: Process payments with new card details (number, CVV, expiry, PIN)
11+
- **Bank Transfer Charges**: Generate temporary account numbers for bank transfers
12+
- **USSD Charges**: Enable USSD dial codes for mobile payments (*737#, *966#, etc.)
13+
- **Mobile Money Charges**: Support MTN, Vodafone, Airtel-Tigo, M-Pesa payments
14+
- **QR Code Charges**: Generate QR codes for scan-to-pay transactions
15+
- **Saved Card Charges**: Use authorization codes from previous successful payments
16+
17+
**🔐 Authorization Submissions:**
18+
- **PIN Submission**: Handle PIN-based authorization for debit cards
19+
- **OTP Submission**: Process one-time password verification
20+
- **Phone Verification**: Submit phone numbers for verification
21+
- **Birthday Verification**: Handle date of birth verification
22+
- **Address Verification**: Submit billing address details
23+
24+
**📊 Status Management:**
25+
- **Charge Status Checking**: Monitor pending charge status and progress
26+
27+
## Features
28+
29+
- ✨ **Interactive CLI Menu**: User-friendly command-line interface
30+
- 💳 **Card Validation**: Built-in Luhn algorithm and card type detection
31+
- 🔐 **Comprehensive Auth Flows**: Support for all Paystack authorization methods
32+
- 📊 **Detailed Response Display**: Formatted charge status and transaction details
33+
- 🛡️ **Error Handling**: Proper exception handling with user-friendly messages
34+
- 🔧 **Environment Configuration**: Flexible SDK initialization options
35+
36+
## Setup
37+
38+
### 1. Environment Configuration
39+
40+
Create a `.env` file in the project root with your Paystack credentials:
41+
42+
```env
43+
PAYSTACK_PUBLIC_KEY=pk_test_your_public_key_here
44+
PAYSTACK_SECRET_KEY=sk_test_your_secret_key_here
45+
PAYSTACK_ENVIRONMENT=test
46+
PAYSTACK_LOG_LEVEL=info
47+
```
48+
49+
### 2. Install Dependencies
50+
51+
```bash
52+
dart pub get
53+
```
54+
55+
### 3. Run the Application
56+
57+
```bash
58+
dart run
59+
```
60+
61+
## Usage
62+
63+
The application provides an interactive menu with the following operations:
64+
65+
## 💳 CREATE CHARGES
66+
67+
### 1. Create Card Charge
68+
Process a payment using card details:
69+
- Enter customer email and amount
70+
- Provide card number, CVV, expiry date
71+
- Optional PIN for debit cards
72+
- Automatic card validation and type detection
73+
74+
**Test Card Numbers:**
75+
- Visa: `4084084084084081`
76+
- Mastercard: `5060666666666666666`
77+
- Verve: `5061020000000000094`
78+
79+
### 2. Create Bank Transfer Charge
80+
Generate temporary account for bank transfers:
81+
- Enter customer email and amount
82+
- Optional account expiry date
83+
- Customer transfers to generated account number
84+
85+
### 3. Create USSD Charge
86+
Enable mobile USSD payments:
87+
- Enter customer email and amount
88+
- Choose from popular USSD codes:
89+
- GTB: *737#
90+
- Zenith: *966#
91+
- UBA: *919#
92+
- Custom USSD code
93+
94+
### 4. Create Mobile Money Charge
95+
Process mobile money payments:
96+
- Enter customer email and amount
97+
- Select provider:
98+
- 🇬🇭 Ghana: MTN, Vodafone, AirtelTigo
99+
- 🇰🇪 Kenya: M-Pesa
100+
- Provide mobile number
101+
102+
### 5. Create QR Code Charge
103+
Generate QR codes for payments:
104+
- Enter customer email and amount
105+
- Choose QR provider:
106+
- Scan-to-Pay
107+
- Visa QR
108+
- Custom provider
109+
110+
### 6. Create Saved Card Charge
111+
Use previously saved payment methods:
112+
- Enter customer email and amount
113+
- Provide authorization code from previous transaction
114+
- One-click payment experience
115+
116+
## 🔐 SUBMIT AUTHORIZATION
117+
118+
### 7. Submit PIN
119+
Authorize charge using card PIN:
120+
- Enter charge reference
121+
- Provide card PIN (4 digits)
122+
123+
### 8. Submit OTP
124+
Complete OTP verification:
125+
- Enter charge reference
126+
- Provide OTP from SMS/email
127+
128+
### 9. Submit Phone
129+
Verify phone number:
130+
- Enter charge reference
131+
- Provide phone number (international format)
132+
133+
### 10. Submit Birthday
134+
Verify date of birth:
135+
- Enter charge reference
136+
- Provide birthday (YYYY-MM-DD format)
137+
138+
### 11. Submit Address
139+
Provide billing address:
140+
- Enter charge reference
141+
- Complete address (street, city, state, ZIP)
142+
143+
## 📊 STATUS CHECK
144+
145+
### 12. Check Pending Charge
146+
Monitor charge status:
147+
- Enter charge reference
148+
- View current status and details
149+
150+
## Example Flows
151+
152+
### Card Payment Flow
153+
1. **Start Application**: `dart run`
154+
2. **Create Card Charge**: Select option 1, enter email/amount, provide card details
155+
3. **Handle Authorization**: Based on response, use options 7-11 for verification
156+
4. **Check Status**: Use option 12 to monitor progress
157+
5. **Complete**: Charge shows "success" status when processed
158+
159+
### Bank Transfer Flow
160+
1. **Create Bank Transfer**: Select option 2, enter email and amount
161+
2. **Customer Action**: Customer transfers to generated account number
162+
3. **Monitor Status**: Use option 12 to check when transfer is received
163+
164+
### USSD Payment Flow
165+
1. **Create USSD Charge**: Select option 3, choose USSD code
166+
2. **Customer Action**: Customer dials USSD code on phone
167+
3. **Complete**: Payment processed through mobile banking
168+
169+
### Mobile Money Flow
170+
1. **Create Mobile Money**: Select option 4, choose provider and phone
171+
2. **Customer Action**: Customer approves payment on mobile wallet
172+
3. **Verify**: Payment confirmed through mobile money service
173+
174+
### Saved Card Flow
175+
1. **Create Saved Card**: Select option 6, enter authorization code
176+
2. **Complete**: Instant payment using saved payment method
177+
178+
## Response Statuses
179+
180+
- **success**: Payment completed successfully
181+
- **pending**: Requires additional verification (PIN, OTP, etc.)
182+
- **failed**: Payment was declined or failed
183+
- **abandoned**: Customer abandoned the payment flow
184+
185+
## Development
186+
187+
### Project Structure
188+
189+
```
190+
lib/
191+
ex02_charge_terminal.dart # Main ChargeTerminal class
192+
bin/
193+
ex02_charge_terminal.dart # Entry point
194+
pubspec.yaml # Dependencies
195+
README.md # This file
196+
```
197+
198+
### Key Components
199+
200+
- **ChargeTerminal**: Main application class handling all charge operations
201+
- **Interactive Menu**: Command-line interface for user interactions
202+
- **Card Validation**: Built-in validation using Luhn algorithm
203+
- **Response Display**: Formatted output for charge responses and status
204+
205+
## Dependencies
206+
207+
- **mind_paystack**: Core SDK for Paystack integration
208+
- **dotenv**: Environment variable management for configuration
209+
210+
## Security Notes
211+
212+
- Never commit `.env` files containing real API keys
213+
- Use test keys during development
214+
- Ensure HTTPS when handling card data in production
215+
- Follow PCI DSS compliance guidelines for card data handling
216+
217+
## Troubleshooting
218+
219+
**Import Errors**: Run `dart pub get` to install dependencies
220+
**SDK Initialization**: Verify `.env` file contains valid Paystack keys
221+
**Network Issues**: Check internet connection for API calls
222+
**Test Cards**: Use provided test card numbers for development
223+
224+
For more examples and documentation, visit the [MindPaystack GitHub repository](https://github.com/mind-paystack).

‎apps/ex02_charge_terminal/analysis_options.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# This file configures the static analysis results for your project (errors,
2+
# warnings, and lints).
3+
#
4+
# This enables the 'recommended' set of lints from `package:lints`.
5+
# This set helps identify many issues that may lead to problems when running
6+
# or consuming Dart code, and enforces writing Dart using a single, idiomatic
7+
# style and format.
8+
#
9+
# If you want a smaller set of lints you can change this to specify
10+
# 'package:lints/core.yaml'. These are just the most critical lints
11+
# (the recommended set includes the core lints).
12+
# The core lints are also what is used by pub.dev for scoring packages.
13+
14+
include: package:lints/recommended.yaml
15+
16+
# Uncomment the following section to specify additional rules.
17+
18+
# linter:
19+
# rules:
20+
# - camel_case_types
21+
22+
# analyzer:
23+
# exclude:
24+
# - path/to/excluded/files/**
25+
26+
# For more information about the core and recommended set of lints, see
27+
# https://dart.dev/go/core-lints
28+
29+
# For additional information about configuring this file, see
30+
# https://dart.dev/guides/language/analysis-options

‎apps/ex02_charge_terminal/bin/ex02_charge_terminal.dart‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import 'package:ex02_charge_terminal/ex02_charge_terminal.dart';
2+
3+
/// Entry point for the MindPaystack Charge Terminal application.
4+
///
5+
/// This application demonstrates charge flows with card processing using
6+
/// the MindPaystack SDK. It provides an interactive command-line interface
7+
/// for creating charges and handling various submission flows.
8+
Future<void> main(List<String> arguments) async {
9+
try {
10+
// Initialize the charge terminal with SDK configuration
11+
final terminal = await ChargeTerminal.create();
12+
13+
// Start the interactive session
14+
await terminal.runInteractiveSession();
15+
} catch (e) {
16+
print('Failed to start charge terminal: $e');
17+
}
18+
}

0 commit comments

Comments
 (0)