Payments migration

Learn how to migrate your payments to Mambu Payments (formerly Numeral)

Mambu Payments (formerly Numeral) enables customers to migrate and manage their historical payment operations, giving them full visibility of their payment history and control over R transactions.

Process

Mambu Payments (formerly Numeral) offers 4 CSV file templates used to import payment orders, incoming payments, return requests, and direct debit mandates. The remaining of this guide explains how to populate these files.

Once populated and received, Mambu Payments (formerly Numeral) will import, test, and validate data in a test environment before repeating the import into a production environment.

Use cases supported

Payment types

Use cases

Credit transfer / instant payments

  • Importing a credit transfer incoming payment from <13 months ago to potentially receive a Recall / RRO on it
  • Importing a credit transfer incoming payment from <3 days ago to potentially send a Return on it (SCT only)
  • Importing a credit transfer payment order from <3 days ago to potentially receive a Return on it (SCT only)
  • Importing a credit transfer payment order from <13 months ago to potentially send a Recall / RRO on it
  • Importing an incoming return request (Recall / RRO) from <15 days to reply to it with a positive / negative response
  • Importing an outgoing return request (Recall / RRO) from <15 days to be sure to properly catch its positive / negative response

Direct debit payments

  • Importing direct debit mandates (outgoing or incoming)
  • Importing a direct debit incoming payment from <13 months ago to potentially send a Return / Refund on it
  • Importing a direct debit incoming payment from <5 days ago to potentially receive a reversal on it
  • Importing a direct debit payment order <13 months ago to potentially receive a Return / Refund on it
  • Importing a direct debit payment order from <5 days ago to potentially send a reversal on it

CSV templates

  • Templates contain mandatory and optional columns. See the full description of each columns for import type below
  • Each entry must contain an id column filled with a unique internal ID (ideally a UUID v4, but it can also be a custom format). Return requests will be imported after payment orders and incoming payments, as their related_payment_id column must reference the id column of payment orders or incoming payments previously imported
  • Files can contain up to 100,000 entries each
  • CSV separator used is ";". Make sure to escape this character or encapsulate all strings that could include this character with double quotes

Payment orders

Field

Mandatory?

Format

Notes

id

Yes

UUID

Unique ID representing the record

connected_account_id

Yes

UUID

Mambu Payments (formerly Numeral) connected account UUID

direction

Yes

  • credit (for credit transfer)
  • debit (for direct debit)

payment_type

Yes

See payment type values

amount

Yes

Integer, expressed in minimal currency unit (e.g. EUR 10.00 = 1000)

See data types

currency

Yes

ISO 4217 currency code

See currency codes

value_date

Yes

Date in YYYY-MM-DD, e.g. 2024-04-25

Value date of the payment

status

Yes

  • executed: successfully executed
  • rejected: payment was rejected
  • pending: on hold for AML / CFT
  • returned: payment was returned
  • pending_return: open return request

purpose

No

String

Only applicable to Swift payments (purpose code)

reference

Yes

String

Reference of the payment

confidentiality_option

No

payroll

Only for salary/payroll payments

treasury_option

No

local, international, or relocated

Only for “treasury” type payments

fee_option

No

originator, shared, receiver

Only for Swift payments

origin_holder_name

Conditional

String

Mandatory for indirect payments

origin_bank_account

Conditional

IBAN or local account number

Mandatory for indirect payments

origin_bank_code

Conditional

Swift / BIC or local bank code (sort code, BSB, etc.)

Mandatory for indirect payments

origin_creditor_identifier

Conditional

Creditor identifier (SEPA creditor identifier / ICS or UK SUN)

Mandatory for direct debit indirect payments

origin_holder_address.building_number

No

String

Optional for indirect payments

origin_holder_address.street_name

No

String

Optional for indirect payments

origin_holder_address.postal_code

No

String

Optional for indirect payments

origin_holder_address.city

No

String

Recommended for indirect payments

origin_holder_address.country

No

ISO 3166 alpha-2, e.g. GB, FR, US

Recommended for indirect payments

origin_holder_address.line_1

No

String

Optional for indirect payments

origin_holder_address.line_2

No

String

Optional for indirect payments

origin_private_identification.birth_date

No

Date in YYYY-MM-DD, e.g. 2000-01-01

origin_private_identification.birth_city

No

String

origin_private_identification.birth_country

No

String

origin_private_identification.other.
identification

No

String

origin_private_identification.other.
identification_type

No

One of alien_registration_number, passport_number, customer_identification_number, drivers_license_number, employee_identification_number, national_identity_number, social_security_number, telephone_number, tax_identification_number, person_commercial_identification

origin_private_identification.other.
custom_identification_type

No

String

origin_private_identification.other.
identification_issuer

No

String

destination_holder_name

Yes

String

destination_bank_account

Yes

IBAN or local account number

destination_bank_code

Yes

Swift / BIC or local bank code (sort code, BSB, etc.)

destination_holder_address.building_number

No

String

Recommended

destination_holder_address.street_name

No

String

Recommended

destination_holder_address.postal_code

No

String

Recommended

destination_holder_address.city

No

String

Recommended

destination_holder_address.country

No

ISO 3166 alpha-2

Recommended

destination_holder_address.line_1

No

String

Recommended

destination_holder_address.line_2

No

String

Recommended

destination_private_identification.birth_date

No

Date in YYYY-MM-DD, e.g. 2000-01-01

destination_private_identification.birth_city

No

String

destination_private_identification.birth_country

No

String

destination_private_identification.other.
identification

No

String

destination_private_identification.other.
identification_type

No

One of alien_registration_number, passport_number, customer_identification_number, drivers_license_number, employee_identification_number, national_identity_number, social_security_number, telephone_number, tax_identification_number, person_commercial_identification

destination_private_identification.other.
custom_identification_type

No

String

destination_private_identification.other.
identification_issuer

No

String

sdd_mandate_sequence

Conditional

one_off or recurring

Mandatory for direct debit payments

sdd_mandate_type

Conditional

sepa_core, sepa_b2b, or bacs_debit

Mandatory for direct debit payments

sdd_mandate_signature_date

Conditional

Date in YYYY-MM-DD, e.g. 2024-04-25

Mandatory for direct debit payments

sdd_mandate_reference

Conditional

String

Mandatory for direct debit payments

bank_data.message_id

No

String

Highly recommended

bank_data.end_to_end_id

No

String

Highly recommended

bank_data.transaction_id

No

String

Highly recommended

custom_fields

No

String, format is “key=val|key2=val2”

key=val|key2=val2

metadata

No

String, format is “key=val|key2=val2”

key=val|key2=val2

Incoming payments

Field

Mandatory?

Format

Notes

id

Yes

UUID / custom ID

Unique ID representing the record

connected_account_id

Yes

UUID

Mambu Payments (formerly Numeral) connected account UUID

payment_type

Yes

See payment type values

direction

Yes

  • credit (for credit transfer)
  • debit (for direct debit)

amount

Yes

Integer, expressed in minimal currency unit (e.g. EUR 10.00 = 1000)

See data types

currency

Yes

ISO 4217 currency code

See currency codes

value_date

Yes

Date in YYYY-MM-DD, e.g. 2024-04-25

Value date of the payment

requested_execution_date

Conditional

Date in YYYY-MM-DD, e.g. 2024-04-25

Mandatory for direct debit indirect payments

status

Yes

  • received if the payment was successfully received
  • rejected, if the payment was rejected
  • pending_return, if an open return request awaits a response

reference

Yes

String

Reference of the payment

origin_holder_name

Conditional

String

Mandatory for indirect payments

origin_bank_account

Conditional

IBAN or local account number (UK, AU, etc.)

Mandatory for indirect payments

origin_bank_code

Conditional

Swift / BIC or local bank code (sort code, BSB, etc.)

Mandatory for indirect payments

origin_creditor_identifier

Conditional

Creditor identifier (SEPA creditor identifier / ICS or UK SUN)

Mandatory for direct debit indirect payments

origin_holder_address.building_number

No

String

Optional for indirect payments

origin_holder_address.street_name

No

String

Optional for indirect payments

origin_holder_address.postal_code

No

String

Optional for indirect payments

origin_holder_address.city

No

String

Recommended for indirect payments

origin_holder_address.country

No

ISO 3166 alpha-2 country code, e.g. GB, FR, or US

Recommended for indirect payments

origin_holder_address.line_1

No

String

Optional for indirect payments

origin_holder_address.line_2

No

String

Optional for indirect payments

origin_private_identification.birth_date

No

Date in YYYY-MM-DD, e.g. 2000-01-01

origin_private_identification.birth_city

No

String

origin_private_identification.birth_country

No

String

origin_private_identification.other.
identification

No

String

origin_private_identification.other.
identification_type

No

One of alien_registration_number, passport_number, customer_identification_number, drivers_license_number, employee_identification_number, national_identity_number, social_security_number, telephone_number, tax_identification_number, person_commercial_identification

origin_private_identification.other.
custom_identification_type

No

String

origin_private_identification.other.
identification_issuer

No

String

destination_holder_name

Yes

String

destination_bank_account

Yes

IBAN or local account number (UK, AU, etc.)

destination_bank_code

Yes

Swift / BIC or local bank code (sort code, BSB, etc.)

destination_holder_address.building_number

No

String

Recommended

destination_holder_address.street_name

No

String

Recommended

destination_holder_address.postal_code

No

String

Recommended

destination_holder_address.city

No

String

Recommended

destination_holder_address.country

No

ISO 3166 alpha-2 country code, e.g. GB, FR, or US

Recommended

destination_holder_address.line_1

No

String

Recommended

destination_holder_address.line_2

No

String

Recommended

destination_private_identification.birth_date

No

Date in YYYY-MM-DD, e.g. 2000-01-01

destination_private_identification.birth_city

No

String

destination_private_identification.birth_country

No

String

destination_private_identification.other.
identification

No

String

destination_private_identification.other.
identification_type

No

One of alien_registration_number, passport_number, customer_identification_number, drivers_license_number, employee_identification_number, national_identity_number, social_security_number, telephone_number, tax_identification_number, person_commercial_identification

destination_private_identification.other.
custom_identification_type

No

String

destination_private_identification.other.
identification_issuer

No

String

sdd_mandate_sequence

Conditional

one_off or recurring

Mandatory for direct debit payments

sdd_mandate_type

Conditional

sepa_core, sepa_b2b, or bacs_debit

Mandatory for direct debit payments

sdd_mandate_signature_date

Conditional

Date in YYYY-MM-DD, e.g. 2024-04-25

Mandatory for direct debit payments

sdd_mandate_reference

Conditional

String

Mandatory for direct debit payments

bank_data.message_id

No

String

Highly recommended

bank_data.end_to_end_id

No

String

Highly recommended

bank_data.transaction_id

No

String

Highly recommended

metadata

No

String, format is “key=val|key2=val2”

key=val|key2=val2

Return requests

Field

Mandatory?

Format

Notes

id

Yes

UUID / custom ID

Unique ID representing the record

connected_account_id

Yes

UUID

Mambu Payments (formerly Numeral) connected account UUID

related_payment_id

Yes

UUID

Related imported payment order or incoming payment id column value

related_payment_nature

Yes

payment_order or incoming_payment

  • Use payment_order if the return request was sent and relates to a payment order.
  • Use incoming_payment if the return request was received and relates to an incoming payment.

payment_type

Yes

sepa or sepa_instant

Depending on the underlying payment’s type

return_reason

Yes

String

SEPA return reason (e.g. DUPL, TECH, FRAD, CUST, AM09, AC03)

value_date

Yes

Date in YYYY-MM-DD, e.g. 2024-04-25

Value date of the payment

origin_holder_name

No

String

Mandatory for indirect payments

origin_bank_account

No

IBAN or local account number (UK, AU, etc.)

Mandatory for indirect payments

origin_bank_code

No

Swift / BIC or local bank code (sort code, BSB, etc.)

Mandatory for indirect payments

origin_holder_address.building_number

No

String

Optional for indirect payments

origin_holder_address.street_name

No

String

Optional for indirect payments

origin_holder_address.postal_code

No

String

Optional for indirect payments

origin_holder_address.city

No

String

Recommended for indirect payments

origin_holder_address.country

No

ISO 3166 alpha-2 country code, e.g. GB, FR, or US

Recommended for indirect payments

origin_holder_address.line_1

No

String

Optional for indirect payments

origin_holder_address.line_2

No

String

Optional for indirect payments

origin_private_identification.birth_date

No

Date in YYYY-MM-DD, e.g. 2000-01-01

origin_private_identification.birth_city

No

String

origin_private_identification.birth_country

No

String

origin_private_identification.other.
identification

No

String

origin_private_identification.other.
identification_type

No

One of alien_registration_number, passport_number, customer_identification_number, drivers_license_number, employee_identification_number, national_identity_number, social_security_number, telephone_number, tax_identification_number, person_commercial_identification

origin_private_identification.other.
custom_identification_type

No

String

origin_private_identification.other.
identification_issuer

No

String

destination_holder_name

No

String

destination_bank_account

No

IBAN or local account number (UK, AU, etc.)

destination_bank_code

No

Swift / BIC or local bank code (sort code, BSB, etc.)

destination_holder_address.building_number

No

String

Recommended

destination_holder_address.street_name

No

String

Recommended

destination_holder_address.postal_code

No

String

Recommended

destination_holder_address.city

No

String

Recommended

destination_holder_address.country

No

ISO 3166 alpha-2 country code, e.g. GB, FR, or US

Recommended

destination_holder_address.line_1

No

String

Recommended

destination_holder_address.line_2

No

String

Recommended

destination_private_identification.birth_date

No

Date in YYYY-MM-DD, e.g. 2000-01-01

destination_private_identification.birth_city

No

String

destination_private_identification.birth_country

No

String

destination_private_identification.other.
identification

No

String

destination_private_identification.other.
identification_type

No

One of alien_registration_number, passport_number, customer_identification_number, drivers_license_number, employee_identification_number, national_identity_number, social_security_number, telephone_number, tax_identification_number, person_commercial_identification

destination_private_identification.other.
custom_identification_type

No

String

destination_private_identification.other.
identification_issuer

No

String

status

Yes

  • received: return request was received (for incoming payments)
  • sent: return request was sent (for payment orders)
  • denied: return request was denied
  • accepted: return request was accepted

bank_data.assignment_id

Yes

String

Assignment ID / message ID of the return request

bank_data.cancellation_id

Yes

String

Cancellation ID / transaction ID of the return request

bank_data.original_message_id

Yes

String

Original message ID of the underlying payment

bank_data.original_end_to_end_id

Yes

String

Original end-to-end ID of the underlying payment

bank_data.original_transaction_id

Yes

String

Original transaction ID of the underlying payment

bank_data.original_payment_value_date

No

String

Recommended

bank_data.original_payment_amount

No

Integer (in minor units, e.g. EUR 10.00 = 1000)

Recommended

bank_data.original_payment_currency

No

ISO 4217 currency code

Recommended

metadata

No

String, format is “key=val|key2=val2”

key=val|key2=val2

ℹ️

Relationships between return requests and payment orders are preserved via related_payment_id andrelated_payment_type fields.

Direct debit mandates

Field

Mandatory?

Format

Notes

id

Yes

UUID

Unique UUID v4 representing the record

connected_account_id

Yes

UUID

Mambu Payments (formerly Numeral) connected account UUID

status

Yes

  • active for active mandates
  • blocked for temporarily blocked mandates
  • disabled for permanently disabled mandates

direction

Yes

  • incoming (for incoming direct debits)
  • outgoing (for outgoing direct debits)

type

Yes

sepa_core, sepa_b2b, or bacs_debit

sequence

Yes

one_off or recurring

reference

Yes

String

Unique reference of the mandate

signature_date

Conditional

Date in YYYY-MM-DD, e.g. 2024-04-25

Mandatory for SEPA direct debit payments

creditor_holder_name

Conditional

String

Mandatory for indirect payments

creditor_bank_account

Conditional

IBAN or local account number (UK, AU, etc.)

Mandatory for indirect payments

creditor_bank_code

Conditional

Swift / BIC or local bank code (sort code, BSB, etc.)

Mandatory for indirect payments

creditor_creditor_identifier

Conditional

Creditor identifier (SEPA creditor identifier / ICS or UK SUN)

Mandatory for direct debit indirect payments

creditor_holder_address.building_number

No

String

creditor_holder_address.street_name

No

String

creditor_holder_address.postal_code

No

String

creditor_holder_address.city

No

String

Recommended for indirect payments

creditor_holder_address.country

No

ISO 3166 alpha-2 country code, e.g. GB, FR, or US

Recommended for indirect payments

creditor_holder_address.line_1

No

String

creditor_holder_address.line_2

No

String

debtor_holder_name

Yes

String

debtor_bank_account

Yes

IBAN or local account number (UK, AU, etc.)

debtor_bank_code

Yes

Swift / BIC or local bank code (sort code, BSB, etc.)

debtor_holder_address.building_number

No

String

Recommended

debtor_holder_address.street_name

No

String

Recommended

debtor_holder_address.postal_code

No

String

Recommended

debtor_holder_address.city

No

String

Recommended

debtor_holder_address.country

No

ISO 3166 alpha-2 country code, e.g. GB, FR, or US

Recommended

debtor_holder_address.line_1

No

String

Recommended

debtor_holder_address.line_2

No

String

Recommended

metadata

No

String, format is “key=val|key2=val2”

key=val|key2=val2