README

An unofficial package for Stanbic bank; following the ISO20022 standard.

Prerequisites

Configure sftp first before you proceed: https://laravel.com/docs/12.x/filesystem#sftp-driver-configuration

Add the SFTP configs in the config/filesystem.php. Below is the recommended set of configs. Ensure you set the corresponding env values in your .env as well:

'stanbic_sftp' => [
    'driver' => 'sftp',
    'host' => env('STANBIC_SFTP_HOST'),
    'port' => (int) env('STANBIC_SFTP_PORT', 22),
    'username' => env('STANBIC_SFTP_USERNAME'),
    'privateKey' => env('STANBIC_SFTP_PRIVATE_KEY'),
    'throw' => true,
],

Installation

You can install the package via composer:

composer require akika/laravel-stanbic

Optional Steps

You can skip thse optional steps.

In your .env, configure which filesystem disk we will read and write the payment files to. This is already preconfigured to pick the sftp disk.

STANBIC_SFTP_HOST=
STANBIC_SFTP_PORT=22
STANBIC_SFTP_USERNAME=
STANBIC_SFTP_PRIVATE_KEY=

STANBIC_FILESYSTEM_DISK=sftp
STANBIC_INPUT_ROOT="Input"
STANBIC_OUTPUT_ROOT="Output"

You can publish the config file with (optional):

php artisan vendor:publish --tag="laravel-stanbic-config"

Usage

Credit Transfer Initiation with Pain00100103

This package provides a Laravel implementation for generating ISO 20022 PAIN.001.001.03 XML messages for credit transfers.

Basic Usage

<?php

namespace App\Console\Commands;

use Akika\LaravelStanbic\Data\AggregateRoots\Pain00100103;
use Akika\LaravelStanbic\Data\ValueObjects\CreditTransferTransactionInfo;
use Akika\LaravelStanbic\Data\ValueObjects\GroupHeader;
use Akika\LaravelStanbic\Data\ValueObjects\PaymentInfo;
use Akika\LaravelStanbic\Data\ValueObjects\PostalAddress;
use Akika\LaravelStanbic\Enums\ChargeBearerType;
use Akika\LaravelStanbic\Enums\CountryCode;
use Akika\LaravelStanbic\Enums\Currency;
use Akika\LaravelStanbic\Enums\InstructionPriority;
use Akika\LaravelStanbic\Enums\PaymentMethod;
use Illuminate\Console\Command;

class DemoSinglePaymentCommand extends Command
{
    protected $signature = 'demo:single-payment';

    protected $description = 'Create a demo single payment';

    public function handle()
    {
        $messageId = fake()->regexify('MSG0[A-Z0-9]{5}');
        $companyName = 'MY.COMPANY/NAMEC2C';
        $companyAcNo = '1234567891234';

        // 1. Create group header
        $groupHeader = GroupHeader::make()
            ->setMessageId($messageId)
            ->setCreationDate(now())
            ->setInitiatingParty(null, $companyName);

        $filePath = Pain00100103::make()
            ->setGroupHeader($groupHeader)
            ->addPaymentInfo($this->getPaymentInfo($companyName, $companyAcNo))
            ->store();

        $this->line("Saved to: \n\t{$filePath}");
    }

    public function getPaymentInfo(string $companyName, string $companyAcNo): PaymentInfo
    {
        $debtorBankCode = '190101';
        $paymentInfoId = fake()->regexify('PMTINF0[A-Z0-9]{5}');

        $paymentInfo = PaymentInfo::make()
            ->setPaymentInfoId($paymentInfoId)
            ->setPaymentMethod(PaymentMethod::CreditTransfer)
            ->setBatchBooking(true)
            ->setPaymentTypeInfo(InstructionPriority::Norm)
            ->setRequestedExecutionDate(now())
            ->setDebtor($companyName, new PostalAddress(countryCode: CountryCode::Ghana))
            ->setDebtorAccount($companyAcNo, Currency::Cedi)
            ->setDebtorAgent($debtorBankCode)
            ->setChargeBearer(ChargeBearerType::Debt)
            ->addCreditTransferTransactionInfo($this->getCreditTransferTransactionInfo());

        return $paymentInfo;
    }

    public function getCreditTransferTransactionInfo(): CreditTransferTransactionInfo
    {
        $paymentId = fake()->regexify('PMT0[A-Z0-9]{5}');
        $instructionId = fake()->regexify('INST0[A-Z0-9]{5}');
        $amount = fake()->numberBetween(1_000, 1_999);

        $creditorBankCode = '190101';
        $bank = 'Stanbic Bank Ghana Ltd';
        $beneficiaryName = 'Darion Ferry';
        $beneficiaryAcNo = '4321987654321';

        $paymentDescription = fake()->words(3, true);

        return CreditTransferTransactionInfo::make()
            ->setPaymentId($paymentId, $instructionId)
            ->setAmount($amount, Currency::Cedi)
            ->setCreditorAgent($creditorBankCode, $bank, new PostalAddress(countryCode: CountryCode::Ghana))
            ->setCreditor($beneficiaryName, new PostalAddress(
                fake()->streetName(),
                fake()->buildingNumber(),
                fake()->postcode(),
                fake()->city(),
                CountryCode::Ghana,
            ))
            ->setCreditorAccount($beneficiaryAcNo)
            ->setRemittanceInfo($paymentDescription);
    }
}

• The generated XML files follow the ISO 20022 PAIN.001.001.03 standard and are automatically stored with unique filenames.
• Stanbic bank will pick the generated file from the configured stanbic.disk filesystem disk.

Reading Stanbic Status Reports

This package provides automated reading of Stanbic bank status reports (PAIN.002.001.03) from your configured storage disk.

Manual Execution

The command automatically scans for XML files containing pain.002.001.03 in the configured disk and processes each one by dispatching the event.

php artisan stanbic:read

Scheduled Execution

For Laravel 11 and above, add the command to your routes/console.php.

// Run every 15 minutes
Schedule::command('stanbic:read')->everyFifteenMinutes();

// Or run hourly
Schedule::command('stanbic:read')->hourly();

// ...etc

For Laravel 10 and below, add the command to your app/Console/Kernel.php schedule:

// Run every 15 minutes
$schedule->command('stanbic:read')->everyFifteenMinutes();

// Or run hourly
$schedule->command('stanbic:read')->hourly();

// ...etc

Event Handling

The command dispatches a Pain00200103ReportReceived event for each status report found. Hook into this event to process the reports:

Create an Event Listener

php artisan make:listener ProcessStatusReport

Register the Listener

For Laravel 11 and above, In your AppServiceProvider.php's boot method:

Event::listen(Pain00200103ReportReceived::class, ProcessStatusReport::class);

For Laravel 10 and below, In your app/Providers/EventServiceProvider.php:

use Akika\LaravelStanbic\Events\Pain00200103ReportReceived;
use App\Listeners\ProcessStatusReport;

protected $listen = [
    Pain00200103ReportReceived::class => [
        ProcessStatusReport::class,
    ],
];

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Akika Digital
• All Contributors

License

The MIT License (MIT). Please see License File for more information.