Accounts mapping

Mambu Payments mirrors your Mambu Core objects. Each Mambu Core loan account becomes a loan in Mambu Payments. Each Mambu Core credit arrangement becomes a credit_arrangement. These objects are the anchor for all disbursement and repayment flows.

Object mapping

IDs are generated deterministically, you never need a separate mapping table:

loan.id = UUIDv5(namespace = legal_entity_id, name = loanAccount.ID)
credit_arrangement.id = UUIDv5(namespace = legal_entity_id, name = creditArrangement.ID)

Any Mambu Payments ID is always derivable from the Mambu Core ID using your tenant's legal_entity_id.

Creation flow

You can create objects in two ways.

Automatic, via Mambu Core webhooks

Set up webhooks in Mambu Core (see more details below)
Create and approve a loan or credit arrangement in Mambu Core.
Mambu Core fires an approval webhook.
Mambu Payments ingests the webhook and creates the corresponding loan or credit_arrangement.
Mambu Payments sends you a creation webhook confirming the object is ready.

Make sure you setup the following webhooks:

Web Hook URL: https://sandbox.numeral.io/v1/loans for sandbox.Please read https://docs.numeral.io/reference/environments for more details.
Request Type: POST
Authorization: No authorization
Content Type: application/json
Custom Request Headers
- x-api-key: your API key from Mambu Payments

Please find below webhook templates to be setup in Mambu Core:

{
  "cbs_source": "mambu",
  "cbs_account_type": "loan",
  "cbs_account_id": "{ACCOUNT_ID}",
  "float_amount":{LOAN_AMOUNT},
  "currency": "{ACCOUNT_CURRENCY_CODE}",
  "cbs_account_key": "{ENCODED_KEY}",
  
	// If loan is part of a credit arrangement
	"cbs_credit_arrangement_id": "{LINE_OF_CREDIT_ID}"
}

{
  "cbs_source": "mambu",
  "cbs_account_type": "credit_arrangement",
  "cbs_account_id": "{LINE_OF_CREDIT_ID}",
  "float_amount": {APPROVED_CREDIT_AMOUNT},
	"currency": "EUR"
}

Manual — via the API

Call POST /loans or POST /credit_arrangements directly with the fields below.

Loan fields `POST /loans`

Field	Required	Description
`amount`	Yes	Loan amount in smallest currency units (e.g. `200000` = €2,000.00).
`currency`	Yes	ISO 4217 currency code (e.g. `EUR`).
`cbs_source`	Yes	Always `mambu`.
`cbs_account_type`	Yes	Always `loan`.
`cbs_account_id`	Yes	The loan account ID in Mambu Core (e.g. `LOAN-001`).
`credit_arrangement_id`	No	Attach the loan to an existing active `credit_arrangement`. When set, `disbursement_details` and `repayment_details` must be left empty, they are inherited from the credit arrangement.
`disbursement_details.connected_account_id`	No	ID of the enabled connected account used to disburse. Omit when `credit_arrangement_id` is set.
`disbursement_details.receiving_account_id`	No	ID of the approved `external_account` that receives the disbursement funds.
`repayment_details.direct_debit_mandate_id`	No	ID of an active outgoing direct debit mandate. Used for debit-based repayment collection.
`repayment_details.receiving_account_id`	No	ID of an active `internal_account` used to receive repayments via credit transfer.
`metadata`	No	Additional JSON key/value pairs. Useful for storing your internal loan reference.

When a loan is attached to a credit_arrangement, disbursement_details and repayment_details must be left empty on the loan — the credit arrangement supplies them for all its loans.

Credit arrangement fields — `POST /credit_arrangements`

Field	Required	Description
`amount`	Yes	Total credit line in smallest currency units.
`currency`	Yes	ISO 4217 currency code.
`cbs_source`	Yes	Always `mambu`.
`cbs_account_type`	Yes	Always `credit_arrangement`.
`cbs_account_id`	Yes	The credit arrangement ID in Mambu Core.
`loan_ids`	No	Array of loan IDs to attach at creation time.
`disbursement_details.connected_account_id`	No	Connected account used for all disbursements under this arrangement.
`disbursement_details.receiving_account_id`	No	External account that receives disbursement funds.
`disbursement_details.cbs_booking_account`	No	Mambu Core account where the disbursement is booked. Contains `source` (always `mambu`), `type` (always `deposit`), and `id`.
`repayment_details.direct_debit_mandate_id`	No	Direct debit mandate used for collections across all loans under the arrangement.
`repayment_details.receiving_account_id`	No	Internal account receiving credit transfer repayments.
`repayment_details.cbs_booking_account`	No	Mambu Core account where repayments are booked. Contains `source`, `type`, and `id`.
`metadata`	No	Additional JSON key/value pairs.

A credit arrangement acts as the configuration hub for all loans beneath it. Payment routing, booking accounts, and mandate references set on the arrangement are inherited by all attached loans.

Object mapping

Creation flow

Loan fields POST /loans

Credit arrangement fields — POST /credit_arrangements

Loan fields `POST /loans`

Credit arrangement fields — `POST /credit_arrangements`