Interbancaire (partner-bank money-in)

1. Purpose

A partner bank pushes money into a customer's wallet. Each partner bank holds its own Masrvi account, and a transfer received from the partner is an inbound credit to the destination customer wallet. The flow is one direction only, partner to beneficiary, and it is not started by the customer, who is not on a screen when the funds arrive. The integration verifies the destination customer with the customer-details lookup (the number exists, the customer is allowed to receive, the account status is good), checks the partner's own Masrvi account holds enough balance, then in one posting debits the partner account and credits the customer account. The amount credited is the amount received, currency 929, with no tax, no commission, and no fee added on top. The customer is told the wallet was credited.

2. The flow

The customer does nothing to start this flow and is not on a screen. The partner-facing dialog (authentication and the partner submitting and settling the transfer) runs in the BMCI middleware and arrives as one inbound transfer. The platform's own work is the customer-details check, the partner-balance check, the single debit-partner credit-customer posting, and the customer notification.

1. Transfer received. A partner bank pushes a transfer toward the beneficiary wallet. It carries the destination number, the amount, currency 929, the source institution, and the partner's transfer reference.
2. Verify the customer. The destination number is looked up through the customer-details lookup. It returns not found if the customer does not exist. The integration deduces from the profile and the status whether the customer is allowed to receive (a restricted profile or a blocked status may not), and reads the customer account to credit.
3. Verify the partner balance. The partner's own Masrvi account is checked for enough balance to cover the received amount.
4. Debit the partner, credit the customer. If the customer is available and the partner holds the balance, one posting debits the partner Masrvi account and credits the customer account, for the received amount, currency 929, against the partner's transfer reference. One debit, one credit, no fee leg, no balancing movement.
5. Notify the customer. On the credit the platform notifies the customer (a push if push is enabled, otherwise an SMS), since the customer was not on a screen and would otherwise not know the funds arrived.

The posting carries the partner's transfer reference as its external reference, which is the idempotency key. There is no second debit and no reverse flow, a wallet-to-partner payout does not exist on this channel, it is inbound only.

Transfer received (the inbound transfer, amount in minor units, currency 929, externalReferenceId the partner's transfer reference and the idempotency key).

{ "beneficiaryMsisdn": "+222 22 12 34 56", "amount": 500000, "currency": "929", "externalReferenceId": "PTNR-2026-000123", "sourceInstitution": "BNM", "narration": "Incoming transfer" }

Customer-details lookup (request, then response). The lookup returns not found if the customer does not exist. The profile and the status decide whether the customer is allowed to receive, and the account number is the credited party.

{ "msisdn": "+222 22 12 34 56" }

{ "profile": "STANDARD", "status": "OPENED", "accountNumber": "+222 22 12 34 56", "customerName": "Mohamed Lemine" }

Posting (debit the partner Masrvi account, credit the customer account, one debit one credit, value in minor units, currency 929). The same externalId (the partner's transfer reference) ties the ledger entry, the receipt, and the reconciliation to one value.

{
  "accounting": [
    {
      "srcAccount": "PARTNER-BNM",
      "dstAccount": "+222 22 12 34 56",
      "type": "TRANSFER",
      "amount": { "value": 500000, "currency": "929", "display": "5000 MRU" }
    }
  ],
  "operation": "INTERBANK_MONEY_IN",
  "externalId": "PTNR-2026-000123",
  "mode": "TRANSACTION"
}

Status response (one of three states. Pending is returned when the credit result is not yet clear, and is reconciled afterward by the external reference).

{ "status": "credited", "transactionId": "MBQ-2026-0001", "externalReferenceId": "PTNR-2026-000123", "message": "Wallet credited" }
{ "status": "rejected", "transactionId": "",            "externalReferenceId": "PTNR-2026-000123", "message": "Beneficiary not creditable" }
{ "status": "pending",  "transactionId": "",            "externalReferenceId": "PTNR-2026-000123", "message": "Credit in progress" }

sequenceDiagram
  participant Partner as Partner bank
  participant BMCI as BMCI integration
  participant Mob as Wallet (Mobiquity)
  participant Cust as Customer
  Partner->>BMCI: transfer received (amount, destination number, reference, currency 929)
  BMCI->>Mob: customer-details lookup (destination number)
  alt customer not found or not eligible
    Mob-->>BMCI: not found / not creditable
    BMCI-->>Partner: rejected (no money moved)
  else customer creditable
    Mob-->>BMCI: profile, status, account
    BMCI->>Mob: check partner Masrvi account balance
    alt partner balance insufficient
      Mob-->>BMCI: insufficient
      BMCI-->>Partner: rejected (no money moved)
    else partner has balance
      BMCI->>Mob: posting, debit partner account, credit customer account, externalReference
      alt credit clear
        Mob-->>BMCI: credited (transactionId)
        Mob->>Cust: notify (push if enabled, else SMS)
      else credit in doubt
        Mob-->>BMCI: pending
        Note over BMCI,Mob: reconcile by external reference, no blind re-credit,<br/>then notify on resolution
      end
    end
  end

3. Error handling

For the wallet platform there are clean outcomes, and only the credit moves money. The customer-details check and the partner-balance check both run before the posting, so a rejection means the platform performed no credit.

• Customer not found or not eligible. The destination number does not resolve, or the profile or the status does not permit a credit. Reject before any money moves, no posting and no notification.
• Partner balance insufficient. The partner's own Masrvi account does not hold enough to cover the amount. Reject before any money moves, no posting and no notification.
• Credited. The customer was creditable and the partner held the balance, the posting debited the partner and credited the customer, the customer is notified, the wallet history carries the new line, and a wallet-platform transaction identifier is returned.
• In doubt (pending). The posting was attempted but the result is not yet clear (a timeout or an unclear response). Do not re-credit blindly. The credit is left pending and reconciled by its external reference, then resolved to credited or rejected. This protects the customer from a double credit and the bank from a lost credit.

The external reference (the partner's transfer reference) is the single idempotency and dedup key, carried on the posting. A duplicate reference returns the same result and never credits twice. Currency 929 and customer creditability are checked before the credit, so the posting never runs on an ineligible target.

4. Notifications and receipt

This is load-bearing for this flow, because it is not started on the wallet platform and the customer is not on a screen when the credit lands. On the credit completion the platform tells the customer: a push notification if push is enabled, otherwise a fall-back SMS, confirming the wallet was credited and by how much. On a rejected transfer no notification is sent (no credit happened). On an in-doubt transfer the notification is sent once the credit is reconciled to credited.

The receipt is the credit entry on the wallet statement, carrying:

• The transfer reference, prominent. This is the partner's transfer reference, and it is the same value as the posting external reference and the status-lookup key, so the customer-visible reference, the ledger reference, and the reconciliation key are one value, never three different numbers. It is the reference the customer quotes for support.
• The source institution, the sending partner bank, by name.
• The amount credited, in ouguiya (currency 929), matching the wallet movement exactly. There is no tax or fee on this flow, so the amount credited and the total are the same.
• The operation, an inbound partner-bank credit.
• The status, credited (or pending while an in-doubt credit is reconciled, then credited once resolved).
• The timestamp of the credit.