Mifos Docs
Search…
Bulk Disbursement Integration

Bulk Payment Design

  • Provide scalable and fault tolerant design with easy integration
  • Allow easy plugging with different payment types (Mojaloop, GSMA, Afrimoney and others)
  • Enable reuse of existing BPMNs to facilitate transfers

Prioritizing New Use Cases

Title
Sells Well
Drives Vol
Changes Market
Tech Diverse
Index Score
Request To Pay
HIGH
HIGH
HIGH
HIGH
12
Bulk Payment
HIGH
MEDIUM
MEDIUM
MEDIUM
10

Staging the Payment

  • Bulk processing is designed as a separate system within Payment Hub EE architecture supporting
  • File integrity check with MD5/SHA256 checksum when received in channel connector
  • Bulk processor
    • Parse CSV file
    • Order payments
    • Format data as per requirement
    • Publish to Kafka payment topic
  • Workflow Initiator
    • Pull messages from Kafka payments topic
    • Format data based on payment connector requirements
    • Initiate payment type-specific workflows
Key Considerations:
  • Kafka provides auto partitioning within topics based on throughput and data
  • Scalable and fault-tolerant system provided by the multi-cluster setup
  • Handle backpressure from Zeebe and throttle workflow initiation
    • Kafka will act as a buffer in this case
  • Advantageous when Zeebe is overloaded
    • Due to resource limitations
    • Or not fast enough scaling
  • Reduces cascading Denial of Service for other payment connectors.
  • Provide a visual workflow representation with Zeebe
  • Stores every state for workflow instances
  • Timers surviving node failures without interruptions
  • Using an efficient, high-performance binary protocol (gRPC) for the clients to connect and receive tasks for execution
  • Retry mechanism on the entire subprocess
    • But retry is already in place within subprocesses
  • Unified payment architecture
  • Easy integration with AMS if payment staging requires it
    • In case of beneficiary creation during transfer
  • Using Raft for log replication
    • Kafka to write ahead log replication as well.
  • Easy integration of pre and post-transaction workers
    • Such as bulk notification

References:

API Specification

  • Provide developer friendly consumer APIs
  • Enable easy integration by abstracting underlying payment type API complexities
  • Group common fields across various payment APIs and make em mandatory field
    • All fields in the spec below are mandatory fields
  • Allow addition of payment type specific fields as optional

1. Create Transfer

curl -X POST <https://ph.ee/channel/{payment_mode}/transfer> \\
-H "Content-Type: application/json" \\
-d '{
"request_id": "UUID",
"account_number": "7878780080316316",
"amount": 1000000,
"currency": "RWF",
"note": "Sample Transaction"
}'
{
"id": "UUID",
"request_id": "UUID",
"amount": 1000000,
"currency": "RWF",
"note": "Sample Transaction",
"fees": 0,
"tax": 0,
"status": "queued",
"mode": "payment_mode",
"batch_id": null,
"failure_reason": null,
"created_at": 1545383037
}

2. Transaction Status

Single Transaction
curl -X GET <https://ph.ee/channel/{payment_mode}/transfer?id=UUID>
curl -X GET <https://ph.ee/channel/{payment_mode}/transfer?request_id=UUID>
{
"id": "UUID",
"request_id": "UUID",
"amount": 1000000,
"currency": "RWF",
"note": "Sample Transaction",
"fees": 0,
"tax": 0,
"status": "competed",
"mode": "payment_mode",
"batch_id": null,
"failure_reason": null,
"created_at": 1545383037
}
All Transactions
curl -X GET <https://ph.ee/channel/{payment_mode}/transfer>
[
{
"id": "UUID",
"request_id": "UUID",
"amount": 1000000,
"currency": "RWF",
"note": "Sample Transaction",
"fees": 0,
"tax": 0,
"status": "competed",
"mode": "payment_mode",
"batch_id": null,
"failure_reason": null,
"created_at": 1545383037
}
]

3. Bulk Transfer

curl -X POST <https://ph.ee/channel/bulk/transfer> \\
-H "Content-Type: multipart/form-data" \\
-F "[email protected]" -F "note=Bulk transfers" -F "checksum={hash}" -F "request_id={UUID}"
{
"batch_id": "UUID",
"request_id": "UUID",
"notes": "Bulk transfers",
"status": "queued",
"purpose": "refund",
"failure_reason": null,
"created_at": 1545383037
}

4. Bulk Transfer Status

curl -X GET <https://ph.ee/channel/bulk/transfer?batch_id={UUID}&detailed={true/false}>
curl -X GET <https://ph.ee/channel/bulk/transfer?request_id={UUID}&detailed={true/false}>
{
"batch_id": "UUID",
"request_id": "UUID",
"notes": "Bulk transfers",
"status": "processing",
"mode": "{payment_mode}",
"purpose": "refund",
"total": 1000,
"successful": 980,
"failed": 20,
"file": "S3 link", // Based on detailed boolean passed in req param
"created_at": 1545383037
}

Payment Routing

  • Route enables user to split payments received and transfer the funds to various vendors/beneficiaries.
  • Sample request body
{
"amount": 2000,
"currency": "INR",
"transfers": [
{
"account": "acc_CPRsN1LkFccllA",
"amount": 1000,
"currency": "INR",
"notes": {
"branch": "Acme Corp Bangalore North",
"name": "Gaurav Kumar"
},
},
{
"account": "acc_CNo3jSI8OkFJJJ",
"amount": 1000,
"currency": "INR",
"notes": {
"branch": "Acme Corp Bangalore South",
"name": "Saurav Kumar"
},
}
]
}
  • With Auto Payout
    • Targeting individuals
    • Money is transferred directly to bank accounts / mobile money wallets from the sender float account.
    • No involvement of AMS.
  • Without Auto Payout
    • Targeting organisations
    • Money is transferred to Fineract wallets of the receivers.
    • Receiver can choose if they want to withdraw the money out of the wallet
    • Or consider using the money in float/current/checking account for L2 beneficiaries (clear invoices, payroll) seamlessly in one platform (L1 beneficiary amount remains in closed loop)
    • This provides an advantage to beneficiary orgs to manage their payouts if they have a legacy current/checking account with mostly manual payout processing.