A payment reference is remittance information attached to a payment that identifies the underlying commercial reason for the transfer, such as an invoice number or a creditor reference code.

Mambu Payments supports two types: unstructured references (free text) and structured references (machine-readable fields).

How it works

Every payment sent or received with through Mambu Payments can carry remittance information so that both sender and receiver can reconcile it against their records. The reference travels end-to-end through the clearing bank and clearing network.

Unstructured reference is a single free-text string. It is suitable when you need a simple description or invoice number.
Structured reference is a nested object with typed fields for creditor references, document details, and party information. Use this when you need automated reconciliation between payments and commercial documents.

Unstructured reference

Unstructured reference is included as a string on the payment order, incoming payment, or transaction. It maps to the ISO 20022 <Ustrd> tag.

Object	Attribute
Incoming payment	`reference`
Payment order	`reference`
Transaction	`descriptions`

Structured reference

Structured reference is an array of objects. Each entry can contain creditor reference information, commercial document details, debtor / creditor parties, and additional remittance text. It maps to the ISO 20022 <Strd> tag.

Object definition

Level	Attribute	Type	Required	ISO 20022 tag	Description
L1	`structured_reference`	`array<object>`	No	`RmtInf.Strd`	Array of structured remittance entries.
L2	`creditor_reference_information`	`object`	Usually	`RmtInf.Strd.CdtrRefInf`	Reference assigned by the creditor to uniquely identify the remittance.
L3	`type`	`object`	Usually	`CdtrRefInf.Tp`	Categorisation of the creditor reference.
L4	`code`	`string`	Usually	`CdtrRefInf.Tp.CdOrPrtry.Cd`	Creditor reference type code. Allowed values: `remittance_advice_message` `related_payment_instruction` `foreign_exchange_deal_reference` `dispatch_advice` `purchase_order` `structured_communication_reference` `other`
L4	`issuer`	`string`	No	`CdtrRefInf.Tp.Issr`	Entity that assigned the reference type code. Example: `"ISO"`.
L3	`reference`	`string`	No	`CdtrRefInf.Ref`	The creditor reference value.
L2	`referred_document_information`	`array<object>`	No	`RmtInf.Strd.RfrdDocInf`	Details about the documents being referred to (e.g. invoice).
L3	`type`	`object`	No	`RfrdDocInf.Tp`	Categorisation of the referred document.
L4	`code`	`string`	Yes (if `type` present)	`RfrdDocInf.Tp.CdOrPrtry.Cd`	Document type code. Allowed values: `commercial_invoice` `credit_note_related_to_financial_adjustment` `contract` `credit_note` `debit_note` `dispatch_advice` `debit_note_related_to_financial_adjustment` `hire_invoice` `invoice_signed` `metered_service_invoice` `proforma_invoice` `purchase_order` `quotation` `self_billed_invoice` `seller_presentment` `time_sheet` `usage_report` `account_receivable_open_item` `bill_of_lading` `commercial_contract` `statement_of_account` `trade_services_utility_transaction` `voucher` `other`
L4	`issuer`	`string`	No	`RfrdDocInf.Tp.Issr`	Entity that assigned the document type code.
L3	`number`	`string`	No	`RfrdDocInf.Nb`	Unique identifier of the referred document. Example: `"INV-2026-88"`.
L3	`related_date`	`string`	No	`RfrdDocInf.RltdDt`	Date of the referred document. Format: `YYYY-MM-DD` (ISO 8601).
L2	`invoicer`	`object`	No	`RmtInf.Strd.Invcr`	Party that issued the invoice.
L3	`name`	`string`	No	`Invcr.Nm`	Name of the invoicing party.
L2	`invoicee`	`object`	No	`RmtInf.Strd.Invcee`	Party to whom the invoice was issued.
L3	`name`	`string`	No	`Invcee.Nm`	Name of the invoiced party.
L2	`additional_remittance_info`	`array<string>`	No	`RmtInf.Strd.AddtlRmtInf`	Free-text additional information about the remittance.

Example

{
  /* rest of the object */

  "structured_reference": [{
    "referred_document_information": [{
      "type": {
        "code": "commercial_invoice",
        "issuer": "ISO"
      },
      "number": "INV-2026-88",
      "related_date": "2026-03-01"
    }],
    "referred_document_amount": {
      "due_payable_amount": 120000,
      "remitted_amount": 120000,
      "currency": "EUR"
    },
    "creditor_reference_information": {
      "type": {
        "code": "structured_communication_reference",
        "issuer": "ISO"
      },
      "reference": "RF18123456789"
    },
    "invoicer": {
      "name": "Acme Corp"
    },
    "invoicee": {
      "name": "John Doe"
    },
    "additional_remittance_info": ["Monthly Subscription"]
  }]
}

Support by object

Object	Supported	Attribute
Incoming payment	Yes	`structured_reference`
Payment order	Planned in 2026	`structured_reference`
Transaction	Planned in 2026	`structured_reference`

Mutual exclusivity

Include either an unstructured reference or a structured reference per payment, not both. Clearing banks or networks might reject payments that carry both types and dual references create ambiguity in reconciliation.