Skip to content

DEV Community

katorymnddev

Posted on Nov 7

Exploring Pawapay Deposits, Refunds, and Payouts: A Hands-On Preview

#pawapayintegration #mobilepayments #apidevelopment #webdev

Exploring Pawapay Deposits, Refunds, and Payouts: A Hands-On Preview

Hello everyone! 👋

I'm excited to share a sneak peek of our latest integration with Pawapay—a mobile payment solution that streamlines deposits, refunds, and payouts. In the accompanying video, you'll see these features in action, including validation processes and the success responses from the Pawapay Mobile API.

But first, let's dive into what Pawapay offers and how it can elevate your application's payment capabilities.

📖 What is Pawapay?

Pawapay is a leading mobile money payment gateway in Africa, enabling businesses to transact seamlessly across various mobile networks and countries. With a single API, you can:

Accept deposits from users' mobile money accounts.
Process refunds efficiently.
Initiate payouts to users or vendors.

🚀 Getting Started with Pawapay Integration

Before we jump into the functionalities, ensure you've set up your Pawapay account and obtained your API credentials.

# Install the pawaPay PHP SDK via composer
composer require katorymnd/pawa-pay-integration

Authentication

Authenticate your API requests using your API key:

// Set the environment and SSL verification based on the production status
$environment = getenv('ENVIRONMENT') ?: 'sandbox'; // Default to sandbox if not specified
$sslVerify = $environment === 'production';  // SSL verification true in production

// Dynamically construct the API token key
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';

// Get the API token based on the environment
$apiToken = $_ENV[$apiTokenKey] ?? null;

💰 Deposits

Depositing funds into your application is straightforward.

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Generate a unique deposit ID using a helper method (UUID v4)
$depositId = Helpers::generateUniqueId();

// Prepare metadata if needed (up to 10 items allowed)
$metadata = [];

try {
    // Step 1: Validate the amount using Symfony validation and custom validation
    $validatedAmount = Validator::symfonyValidateAmount($amount);  // Symfony Validator for amount

    // Step 2: Use the Validator to check if the description is valid (alphanumeric and length)
    $validatedDescription = Validator::validateStatementDescription($description);

    // Step 3: Validate the number of metadata items only if metadata is provided
    if (!empty($metadata)) {
        Validator::validateMetadataItemCount($metadata);
    }

    // Step 4: Initiate the deposit using the submitted details
    $response = $pawaPayClient->initiateDeposit(
        $depositId,
        $validatedAmount,
        $currency,
        $mno,
        $payerMsisdn,
        $validatedDescription,
        $metadata
    );

    if ($response['status'] === 200) {
        // Log initiation success
        $log->info('Deposit initiated successfully', [
            'depositId' => $depositId,
            'response' => $response['response']
        ]);

        // Proceed to check the transaction status
        $statusResponse = $pawaPayClient->checkTransactionStatus($depositId, 'deposit');

        if ($statusResponse['status'] === 200) {
            $depositInfo = $statusResponse['response'][0]; // Get the deposit info
            $depositStatus = $depositInfo['status'];

            if ($depositStatus === 'COMPLETED') {
                // Log successful deposit
                $log->info('Deposit completed successfully', [
                    'depositId' => $depositId,
                    'response' => $depositInfo
                ]);

                // Send success response back to JavaScript
                echo json_encode([
                    'success' => true,
                    'transactionId' => $depositId,
                    'message' => 'Payment processed successfully.'
                ]);
            } elseif ($depositStatus === 'FAILED') {
                // Deposit failed
                $failureReason = $depositInfo['failureReason'];
                $failureCode = $failureReason['failureCode'];
                $failureMessage = FailureCodeHelper::getFailureMessage($failureCode);

                $log->error('Deposit failed', [
                    'depositId' => $depositId,
                    'failureCode' => $failureCode,
                    'failureMessage' => $failureMessage,
                    'response' => $depositInfo
                ]);

                // Send error response back to JavaScript
                echo json_encode([
                    'success' => false,
                    'errorMessage' => 'Payment failed: ' . $failureMessage
                ]);
            } else {
                // Deposit is pending or in another state
                $log->info('Deposit is in state: ' . $depositStatus, [
                    'depositId' => $depositId,
                    'response' => $depositInfo
                ]);

                // Send pending response back to JavaScript
                echo json_encode([
                    'success' => false,
                    'errorMessage' => 'Payment is processing. Please wait and check your account.'
                ]);
            }
        } else {
            // Failed to retrieve deposit status
            $log->error('Failed to retrieve deposit status', [
                'depositId' => $depositId,
                'response' => $statusResponse
            ]);
            echo json_encode([
                'success' => false,
                'errorMessage' => 'Unable to retrieve deposit status.'
            ]);
        }
    } else {
        // Log initiation failure
        $log->error('Deposit initiation failed', [
            'depositId' => $depositId,
            'response' => $response
        ]);

        // Send error response back to JavaScript
        echo json_encode([
            'success' => false,
            'errorMessage' => 'Payment initiation failed: ' . $response['response']['message']
        ]);
    }
} catch (Exception $e) {
    // Catch validation errors and display the message
    $errorMessage = "Validation Error: " . $e->getMessage();

    // Log the validation error
    $log->error('Validation error occurred', [
        'depositId' => $depositId,
        'error' => $errorMessage
    ]);

    // Send error response back to JavaScript
    echo json_encode([
        'success' => false,
        'errorMessage' => $errorMessage
    ]);
}

What happens here?

Validation: The API validates the phone number and amount.
Initiation: A deposit request is sent to the user's mobile money account.
Response: You receive a transaction ID and status.

🔄 Refunds

Processing refunds is just as simple.

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Retrieve and sanitize form data
$depositId = isset($_POST['depositId']) ? trim($_POST['depositId']) : '';
$amount = isset($_POST['amount']) ? trim($_POST['amount']) : '';

// Retrieve metadata fields from the form
$metadataFieldNames = isset($_POST['metadataFieldName']) ? $_POST['metadataFieldName'] : [];
$metadataFieldValues = isset($_POST['metadataFieldValue']) ? $_POST['metadataFieldValue'] : [];
$metadataIsPII = isset($_POST['metadataIsPII']) ? $_POST['metadataIsPII'] : [];

// Ensure that metadata fields are arrays
$metadataFieldNames = is_array($metadataFieldNames) ? $metadataFieldNames : [$metadataFieldNames];
$metadataFieldValues = is_array($metadataFieldValues) ? $metadataFieldValues : [$metadataFieldValues];
$metadataIsPII = is_array($metadataIsPII) ? $metadataIsPII : [$metadataIsPII];

// Construct metadata array
$metadata = [];
for ($i = 0; $i < count($metadataFieldNames); $i++) {
    $fieldName = trim($metadataFieldNames[$i]);
    $fieldValue = trim($metadataFieldValues[$i]);
    $isPII = isset($metadataIsPII[$i]) ? true : false;

    // Skip empty metadata fields
    if ($fieldName === '' || $fieldValue === '') {
        continue;
    }

    $metadataItem = [
        'fieldName' => $fieldName,
        'fieldValue' => $fieldValue,
    ];

    if ($isPII) {
        $metadataItem['isPII'] = true;
    }

    $metadata[] = $metadataItem;
}

// Function to validate UUID (version 4)
function isValidUUIDv4($uuid)
{
    return preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i', $uuid);
}

// Function to validate email
function isValidEmail($email)
{
    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
}

// Prepare the request payload (keeping it as provided)
$refundId = Helpers::generateUniqueId();  // Generate a valid UUID for the refundId
// Note: The depositId is obtained from the form
// The amount is obtained from the form
// Metadata is constructed from the form inputs

try {
    // Validate required fields
    if (empty($depositId) || empty($amount)) {
        throw new Exception('Missing required fields: Deposit ID and Refund Amount are required.');
    }

    // Validate Deposit ID
    if (!isValidUUIDv4($depositId)) {
        throw new Exception('Invalid Deposit ID format. It must be a valid UUID version 4.');
    }

    // Validate Refund Amount
    if (!is_numeric($amount) || floatval($amount) <= 0) {
        throw new Exception('Invalid Refund Amount. It must be a positive number.');
    }

    // Validate Metadata
    // Ensure predefined metadata fields are modified
    $predefinedMetadata = [
        'orderId' => 'ORD-123456789',
        'customerId' => 'customer@email.com'
    ];

    foreach ($metadata as $meta) {
        if (array_key_exists($meta['fieldName'], $predefinedMetadata)) {
            if ($meta['fieldValue'] === $predefinedMetadata[$meta['fieldName']]) {
                throw new Exception("Please update the pre-filled {$meta['fieldName']} value before submitting.");
            }

            // Additional validation for customerId
            if ($meta['fieldName'] === 'customerId' && !isValidEmail($meta['fieldValue'])) {
                throw new Exception("Please enter a valid email address for customerId.");
            }
        }
    }

    // Validate metadata count (maximum 10)
    if (count($metadata) > 10) {
        throw new Exception('You cannot add more than 10 metadata fields.');
    }

    // Prepare the data payload
    $data = [
        'refundId' => $refundId,
        'depositId' => $depositId,
        'amount' => floatval($amount),
        'metadata' => $metadata
    ];

    // Initiate the refund using ApiClient
    $response = $pawaPayClient->initiateRefund($refundId, $depositId, floatval($amount), $metadata);

    // Check the API response status
    if ($response['status'] === 200) {
        // Log refund initiation success
        $log->info('Refund initiated successfully', [
            'refundId' => $refundId,
            'depositId' => $depositId,
            'amount' => $amount,
            'metadata' => $metadata,
            'response' => $response['response']
        ]);

        // Now check the refund status
        try {
            $statusResponse = $pawaPayClient->checkTransactionStatus($refundId, 'refund');

            if ($statusResponse['status'] === 200) {
                // Log refund status retrieval success
                $log->info('Refund status retrieved successfully', [
                    'refundId' => $refundId,
                    'statusResponse' => $statusResponse['response']
                ]);

                // Send success response back to the client with refund status
                echo json_encode([
                    'success' => true,
                    'refundId' => $refundId,
                    'message' => 'Refund initiated and status retrieved successfully.',
                    'refundStatus' => $statusResponse['response']
                ]);
            } else {
                // Log failure to retrieve refund status
                $log->error('Failed to retrieve refund status', [
                    'refundId' => $refundId,
                    'statusResponse' => $statusResponse
                ]);

                // Send response indicating refund initiation success but unable to retrieve status
                echo json_encode([
                    'success' => true,
                    'refundId' => $refundId,
                    'message' => 'Refund initiated successfully, but unable to retrieve refund status.',
                    'error' => 'Unable to retrieve refund status.'
                ]);
            }
        } catch (Exception $e) {
            // Log the error
            $log->error('Error occurred while checking refund status', [
                'refundId' => $refundId,
                'error' => $e->getMessage()
            ]);

            // Send response indicating refund initiation success but error in retrieving status
            echo json_encode([
                'success' => true,
                'refundId' => $refundId,
                'message' => 'Refund initiated successfully, but an error occurred while retrieving refund status.',
                'error' => $e->getMessage()
            ]);
        }
    } else {
        // Log initiation failure
        $log->error('Refund initiation failed', [
            'refundId' => $refundId,
            'depositId' => $depositId,
            'amount' => $amount,
            'metadata' => $metadata,
            'response' => $response
        ]);

        // Extract error message from response
        $errorMessage = isset($response['response']['message']) ? $response['response']['message'] : 'Unknown error occurred.';
        echo json_encode([
            'success' => false,
            'errorMessage' => 'Refund initiation failed: ' . $errorMessage
        ]);
    }
} catch (Exception $e) {
    // Catch validation errors and return the message
    $errorMessage = $e->getMessage();

    // Log the error
    $log->error('Error occurred during refund initiation', [
        'refundId' => $refundId,
        'depositId' => $depositId,
        'amount' => $amount,
        'metadata' => $metadata,
        'error' => $errorMessage
    ]);

    // Send error response back to the client
    echo json_encode([
        'success' => false,
        'errorMessage' => $errorMessage
    ]);
}

Key Points:

Partial Refunds: You can refund any amount up to the original transaction amount.
Validation: The API checks if the transaction is eligible for a refund.

📤 Payouts

Send payouts to users or vendors effortlessly.

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Get the raw POST data (JSON) sent from the JavaScript fetch request
$data = json_decode(file_get_contents('php://input'), true);

if ($data) {
    // Access the form data in the $data array
    $recipientsData = isset($data['recipients']) ? $data['recipients'] : [];

    $responses = []; // To collect responses for each recipient

    foreach ($recipientsData as $index => $recipientData) {
        try {
            // Prepare recipient data
            $recipient = [
                'payoutId' => Helpers::generateUniqueId(), // Generate a unique payout ID for each recipient
                'amount' => $recipientData['amount'],
                'currency' => $recipientData['currency'],
                'correspondent' => $recipientData['correspondent'],
                'recipientMsisdn' => $recipientData['recipientMsisdn'],
                'statementDescription' => $recipientData['statementDescription'],
            ];

            // Prepare metadata if available
            $metadata = isset($recipientData['metadata']) ? $recipientData['metadata'] : [];

            // Validate the amount using Symfony validation
            $validatedAmount = Validator::symfonyValidateAmount($recipient['amount']);

            // Validate the description for each recipient
            $validatedDescription = Validator::validateStatementDescription($recipient['statementDescription']);

            // Initiate the payout for each recipient
            $initiateResponse = $pawaPayClient->initiatePayout(
                $recipient['payoutId'],
                $validatedAmount,
                $recipient['currency'],
                $recipient['correspondent'],
                $recipient['recipientMsisdn'],
                $validatedDescription,
                $metadata
            );

            // Simulate a short delay
            sleep(2); // Reduced delay for better performance

            // Check the payout status
            $statusResponse = $pawaPayClient->checkTransactionStatus($recipient['payoutId'], 'payout');

            // Prepare the final response based on the payout status
            if ($statusResponse['status'] === 200 && isset($statusResponse['response'][0]['status']) && $statusResponse['response'][0]['status'] === 'COMPLETED') {
                // Payout completed successfully
                $responses[] = [
                    'recipientMsisdn' => $recipient['recipientMsisdn'],
                    'success' => true,
                    'details' => sprintf(
                        'Payout of %s %s to %s was completed successfully with Payout ID: %s.',
                        $validatedAmount,
                        $recipient['currency'],
                        $recipient['recipientMsisdn'],
                        $recipient['payoutId']
                    ),
                    'response' => $statusResponse['response']
                ];
                $log->info('Payout completed successfully', [
                    'payoutId' => $recipient['payoutId'],
                    'response' => $statusResponse['response']
                ]);
            } else {
                // Payout failed
                $failureReason = $statusResponse['response'][0]['failureReason']['failureMessage'] ?? 'Unknown error';
                $responses[] = [
                    'recipientMsisdn' => $recipient['recipientMsisdn'],
                    'success' => false,
                    'details' => sprintf(
                        'Payout of %s %s to %s failed with Payout ID: %s. Reason: %s.',
                        $validatedAmount,
                        $recipient['currency'],
                        $recipient['recipientMsisdn'],
                        $recipient['payoutId'],
                        $failureReason
                    ),
                    'error' => $failureReason
                ];
                $log->error('Payout failed', [
                    'payoutId' => $recipient['payoutId'],
                    'error' => $failureReason
                ]);
            }

        } catch (Exception $e) {
            // Catch validation errors and display the message
            $responses[] = [
                'recipientMsisdn' => $recipientData['recipientMsisdn'],
                'success' => false,
                'details' => sprintf(
                    'Payout of %s %s to %s failed during processing. Reason: %s.',
                    $recipientData['amount'],
                    $recipientData['currency'],
                    $recipientData['recipientMsisdn'],
                    $e->getMessage()
                ),
                'error' => $e->getMessage()
            ];
            // Log the error if payoutId is set, else log with recipient info
            $log->error('Payout processing error', [
                'recipientMsisdn' => $recipientData['recipientMsisdn'],
                'error' => $e->getMessage()
            ]);
        }
    }

    // Summarize the outcome of all payout attempts
    $successfulCount = count(array_filter($responses, fn ($item) => $item['success']));
    $failedCount = count($responses) - $successfulCount;

    // Return the responses as JSON
    $response = [
        'success' => $failedCount === 0,
        'message' => sprintf(
            'Payout processing completed. %d successful and %d failed.',
            $successfulCount,
            $failedCount
        ),
        'responses' => $responses,
        'total_recipients' => count($recipientsData)
    ];

    echo json_encode($response, JSON_PRETTY_PRINT);

} else {
    // Handle the error (if no data received)
    $response = [
        'success' => false,
        'message' => 'No data received.'
    ];
    echo json_encode($response, JSON_PRETTY_PRINT);
}

Notes:

Multiple Currencies: Support for various African currencies.
Compliance: Automatically handles compliance and regulatory requirements.

✅ Success Responses

Understanding the API responses is crucial for seamless integration.

Deposit Success Response:

 // Send success response back to JavaScript
                echo json_encode([
                    'success' => true,
                    'transactionId' => $depositId,
                    'message' => 'Payment processed successfully.'
                ]);

Refund Success Response:

 // Send success response back to the client with refund status
                echo json_encode([
                    'success' => true,
                    'refundId' => $refundId,
                    'message' => 'Refund initiated and status retrieved successfully.',
                    'refundStatus' => $statusResponse['response']
                ]);

Payout Success Response:

// Summarize the outcome of all payout attempts
    $successfulCount = count(array_filter($responses, fn ($item) => $item['success']));
    $failedCount = count($responses) - $successfulCount;

    // Return the responses as JSON
    $response = [
        'success' => $failedCount === 0,
        'message' => sprintf(
            'Payout processing completed. %d successful and %d failed.',
            $successfulCount,
            $failedCount
        ),
        'responses' => $responses,
        'total_recipients' => count($recipientsData)
    ];

    echo json_encode($response, JSON_PRETTY_PRINT);

These responses help you update your application's state and notify users accordingly.

🎥 Watch It in Action!

The video at the top showcases all these features with live validation and API interactions. You'll see how deposits, refunds, and payouts work seamlessly, along with the success responses from Pawapay.

🔗 Useful Links

🌟 Conclusion

Integrating Pawapay opens up a world of possibilities for handling mobile money transactions in your application. I hope this post and the accompanying video provide valuable insights into what you can achieve.

Feel free to reach out or leave a comment—let's build something amazing together!

Top comments (0)

Subscribe

Read next

Why Web/App Developers Should Learn from Game Developers

Tom J. - Nov 6

🚀 12 Dev Tools + Gen Z UX Secrets + CSS Animations (5-min read)

Adam Marsden - Nov 6

Logging and Monitoring in Node.js: Best Practices

Sushant Gaurav - Nov 6

What is Thunder Client? A Complete Guide to Its Advantages and Disadvantages

Daniel Ma - Nov 6