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.
Automaticly 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
loanorcredit_arrangement. - Mambu Payments sends you a creation webhook confirming the object is ready.
Make sure you setup the following webhooks:
- Webhook 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 Mambu Payments API key
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"
}Manually via the API
Call POST /loans or POST /credit_arrangements directly with the fields below.
Loan fields POST /loans
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_detailsandrepayment_detailsmust be left empty on the loan — the credit arrangement supplies them for all its loans.
Credit arrangement fields — POST /credit_arrangements
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.
Updated 3 days ago