Migrating your Payments

Learn how to migrate your payment history to Numeral during the integration.

Numeral now its enables customers to migrate and manage their historical payment operations, giving them full visibility of their payment history and control over R transactions.

Our process

The migration goes as-follows:

  • Numeral offers 4 CSV file templates used to import payment orders, incoming payments, return requests, and direct debit mandates
  • Templates contain mandatory and optional columns. See the full description of each columns for import type below
  • CSV separator used is “;”. Make sure to escape this character or encapsulate all strings that could include this character with double quotes
  • Files can contain up to 100,000 entries per file
  • Numeral will import, test, and validate data in a test environment before repeating the import into a production environment

ℹ️

Each entry must contain an id column filled with a unique internal ID (ideally an UUID v4, but it could 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.


Use cases supported

SCT / SCT Inst payments

Timeline reminder**

  • 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

Timeline reminder

  • 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

Payment order

Columns

FieldMandatory?FormatNotes
idYesUUID / custom idUnique ID representing the entry
connected_account_idYesUUIDNumeral connected account UUID
directionYes- credit (for credit transfer)
- debit (for direct debit)
payment_typeYesSee payment type values
amountYesInteger, expressed in minimal currency unit (e.g. EUR 10.00 = 1000)See data types
currencyYesISO 4217 currency codeSee currency codes
value_dateYesDate in YYYY-MM-DD, e.g. 2024-04-25Value date of the payment
statusYes- executed: successfully executed
- rejected: payment was rejected
- pending: on hold for AML/CFT
- returned: payment was returned
- pending_return: open return request
purposeNoStringOnly applicable to Swift payments (purpose code)
referenceYesStringReference of the payment
confidentiality_optionNopayrollOnly for salary/payroll payments
treasury_optionNolocal, international, or relocatedOnly for “treasury” type payments
fee_optionNooriginator, shared, receiverOnly for Swift payments
origin_holder_nameConditionalStringMandatory for indirect payments
origin_bank_accountConditionalIBAN or local account numberMandatory for indirect payments
origin_bank_codeConditionalSWIFT/BIC or local bank codeMandatory for indirect payments
origin_creditor_identifierConditionalSEPA creditor identifier / ICS / SUNMandatory for direct debit indirect payments
origin_holder_address.building_numberNoStringOptional for indirect payments
origin_holder_address.street_nameNoStringOptional for indirect payments
origin_holder_address.postal_codeNoStringOptional for indirect payments
origin_holder_address.cityNoStringRecommended for indirect payments
origin_holder_address.countryNoISO 3166 alpha-2, e.g. GB, FR, USRecommended for indirect payments
origin_holder_address.line_1NoStringOptional for indirect payments
origin_holder_address.line_2NoStringOptional for indirect payments
destination_holder_nameYesString
destination_bank_accountYesIBAN or local account number
destination_bank_codeYesSWIFT/BIC or local bank code
destination_holder_address.building_numberNoStringRecommended
destination_holder_address.street_nameNoStringRecommended
destination_holder_address.postal_codeNoStringRecommended
destination_holder_address.cityNoStringRecommended
destination_holder_address.countryNoISO 3166 alpha-2Recommended
destination_holder_address.line_1NoStringRecommended
destination_holder_address.line_2NoStringRecommended
sdd_mandate_sequenceConditionalone_off or recurringMandatory for direct debit payments
sdd_mandate_typeConditionalsepa_core, sepa_b2b, or bacs_debitMandatory for direct debit payments
sdd_mandate_signature_dateConditionalDate in YYYY-MM-DD, e.g. 2024-04-25Mandatory for direct debit payments
sdd_mandate_referenceConditionalStringMandatory for direct debit payments
bank_data.message_idNoStringHighly recommended
bank_data.end_to_end_idNoStringHighly recommended
bank_data.transaction_idNoStringHighly recommended
custom_fieldsNoString, `key=valkey2=val2`Custom data
metadataNoString, `key=valkey2=val2`Custom metadata

CSV Example

idconnected_account_iddirectionpayment_typeamountcurrencyvalue_datestatuspurposereferenceconfidentiality_optiontreasury_optionfee_optionorigin_holder_nameorigin_bank_accountorigin_bank_codeorigin_creditor_identifierorigin_holder_address.building_numberorigin_holder_address.street_nameorigin_holder_address.postal_codeorigin_holder_address.cityorigin_holder_address.countryorigin_holder_address.line_1origin_holder_address.line_2destination_holder_namedestination_bank_accountdestination_bank_codedestination_holder_address.building_numberdestination_holder_address.street_namedestination_holder_address.postal_codedestination_holder_address.citydestination_holder_address.countrydestination_holder_address.line_1destination_holder_address.line_2sdd_mandate_sequencesdd_mandate_typesdd_mandate_signature_datesdd_mandate_referencebank_data.message_idbank_data.end_to_end_idbank_data.transaction_idcustom_fieldsmetadata
ca928885-5734-4f45-8ade-6374cd9111fa2ba9ced1-7c8c-4d62-88cd-55b98f7c43eecreditsepa17067EUR2024-10-17executedInvoice 352635NaNNaNNaNNaNNaNNaN75002.03267362763777782372737827451245324345235customer_id=123|payment_id=37288738273foo=bar|baz=42
98651064-ba4d-4e70-851c-70d5fa1e004ee487f771-4b56-474a-8cf0-a13963ffb87ddebitsepa17067EUR2024-10-19receivedRepayment ; 24515213NaNNaNNaNNaNNaNNaNNaNrecurringsepa_core2024-06-28RUM-32563527832783235523654563463698938928934customerid=123|payment_id=

Incoming Payment

Columns

FieldMandatory?FormatNotes
idYesUUID / custom idUnique ID representing the entry
connected_account_idYesUUIDNumeral connected account UUID
typeYesSee payment type values
directionYes- credit (for credit transfer)
- debit (for direct debit)
amountYesInteger, expressed in minimal currency unit (e.g. EUR 10.00 = 1000)See data types
currencyYesISO 4217 currency codeSee currency codes
value_dateYesDate in YYYY-MM-DD, e.g. 2024-04-25Value date of the payment
requested_execution_dateConditionalDate in YYYY-MM-DD, e.g. 2024-04-25Mandatory for direct debit indirect payments
statusYes- received if the payment was successfully received
- rejected, if the payment was rejected
- pending_return, if an open return request awaits a response
referenceYesStringReference of the payment
origin_holder_nameConditionalStringMandatory for indirect payments
origin_bank_accountConditionalIBAN or local account number (UK, AU, etc.)Mandatory for indirect payments
origin_bank_codeConditionalSWIFT/BIC or local bank code (sort code, BSB, etc.)Mandatory for indirect payments
origin_creditor_identifierConditionalCreditor identifier (SEPA creditor identifier / ICS, or UK Service User Number / SUN)Mandatory for direct debit indirect payments
origin_holder_address.building_numberNoStringOptional for indirect payments
origin_holder_address.street_nameNoStringOptional for indirect payments
origin_holder_address.postal_codeNoStringOptional for indirect payments
origin_holder_address.cityNoStringRecommended for indirect payments
origin_holder_address.countryNoISO 3166 alpha-2 country code, e.g. GB, FR, or USRecommended for indirect payments
origin_holder_address.line_1NoStringOptional for indirect payments
origin_holder_address.line_2NoStringOptional for indirect payments
destination_holder_nameYesString
destination_bank_accountYesIBAN or local account number (UK, AU, etc.)
destination_bank_codeYesSWIFT/BIC or local bank code (Sort code, BSB, etc.)
destination_holder_address.building_numberNoStringRecommended
destination_holder_address.street_nameNoStringRecommended
destination_holder_address.postal_codeNoStringRecommended
destination_holder_address.cityNoStringRecommended
destination_holder_address.countryNoISO 3166 alpha-2 country code, e.g. GB, FR, or USRecommended
destination_holder_address.line_1NoStringRecommended
destination_holder_address.line_2NoStringRecommended
sdd_mandate_sequenceConditionalone_off or recurringMandatory for direct debit payments
sdd_mandate_typeConditionalsepa_core, sepa_b2b, or bacs_debitMandatory for direct debit payments
sdd_mandate_signature_dateConditionalDate in YYYY-MM-DD, e.g. 2024-04-25Mandatory for direct debit payments
sdd_mandate_referenceConditionalStringMandatory for direct debit payments
bank_data.message_idNoStringHighly recommended
bank_data.end_to_end_idNoStringHighly recommended
bank_data.transaction_idNoStringHighly recommended
metadataNoString, format is `key=valkey2=val2`key=val|key2=val2

CSV Example

idconnected_account_idtypedirectionamountcurrencyvalue_daterequested_execution_datestatusreferenceorigin_holder_nameorigin_bank_accountorigin_bank_codeorigin_creditor_identifierorigin_holder_address.building_numberorigin_holder_address.street_nameorigin_holder_address.postal_codeorigin_holder_address.cityorigin_holder_address.countryorigin_holder_address.line_1origin_holder_address.line_2destination_holder_namedestination_bank_accountdestination_bank_codedestination_holder_address.building_numberdestination_holder_address.street_namedestination_holder_address.postal_codedestination_holder_address.citydestination_holder_address.countrydestination_holder_address.line_1destination_holder_address.line_2sdd_mandate_sequencesdd_mandate_typesdd_mandate_signature_datesdd_mandate_referencebank_data.message_idbank_data.end_to_end_idbank_data.transaction_idmetadata
0218ea93-df86-4c08-8b53-2684d91f72a02ba9ced1-7c8c-4d62-88cd-55b98f7c43eesepacredit17067EUR17/10/2024receivedInvoice 352635Acme corpFR1730003000409633757835C70SOMEBIC0XXX12rue de Rivoli75001ParisFRSoftwareCoFR6610096000402172451384L74SOMEBIC0XXXMontpellierFR71 Boulevard Raspail7501432673627637.77782E+144.51245E+14customer_id=123|payment_id=37288738273
7fad61d4-9df9-4505-95ee-66681c63cddde487f771-4b56-474a-8cf0-a13963ffb87dsepadebit17067EUR19/10/202419/10/2024receivedRepayment ; 24515213Jake McGuinessFR1730003000409633757835C70SOMEBIC0XXXFR77AAA323672166Boulevard des Italiens75009ParisFRAcmeFR6610096000402172451384L74SOMEBIC0XXX14 bisrue Turbigo75002ParisFR3.62717E+128.98219E+112341556323customer_id=123|payment_id=67236732673
02cdd16c-951d-4e7c-b143-2a893689ed940910cd69-6fc8-43e5-afe1-3a3d61020cd4sepa_instantcredit60300EUR11/10/2024pending_returnInvoice 63727321PartnerCoFR1730003000409633757835C70SOMEBIC0XXXFR6610096000402172451384L74SOMEBIC0XXXMontpellierFR71 Boulevard Raspail7501432673627637.77782E+144.51245E+14customer_id=123|payment_id=37288738273

Return Request

Columns

FieldMandatory?FormatNotes
idYesUUID / custom idUnique ID representing the entry
connected_account_idYesUUIDNumeral connected account UUID
related_payment_idYesUUIDRelated imported payment order or incoming payment id column value
related_payment_natureYespayment_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_typeYessepa or sepa_instantDepending on the underlying payment’s type
return_reasonYesStringSEPA return reason (e.g. DUPL, TECH, FRAD, CUST, AM09, AC03)
value_dateYesDate in YYYY-MM-DD, e.g. 2024-04-25Value date of the payment
origin_holder_nameNoStringMandatory for indirect payments
origin_bank_accountNoIBAN or local account number (UK, AU, etc.)Mandatory for indirect payments
origin_bank_codeNoSWIFT/BIC or local bank code (Sort code, BSB, etc.)Mandatory for indirect payments
origin_holder_address.building_numberNoStringOptional for indirect payments
origin_holder_address.street_nameNoStringOptional for indirect payments
origin_holder_address.postal_codeNoStringOptional for indirect payments
origin_holder_address.cityNoStringRecommended for indirect payments
origin_holder_address.countryNoISO 3166 alpha-2 country code, e.g. GB, FR, or USRecommended for indirect payments
origin_holder_address.line_1NoStringOptional for indirect payments
origin_holder_address.line_2NoStringOptional for indirect payments
destination_holder_nameNoString
destination_bank_accountNoIBAN or local account number (UK, AU, etc.)
destination_bank_codeNoSWIFT/BIC or local bank code (Sort code, BSB, etc.)
destination_holder_address.building_numberNoStringRecommended
destination_holder_address.street_nameNoStringRecommended
destination_holder_address.postal_codeNoStringRecommended
destination_holder_address.cityNoStringRecommended
destination_holder_address.countryNoISO 3166 alpha-2 country code, e.g. GB, FR, or USRecommended
destination_holder_address.line_1NoStringRecommended
destination_holder_address.line_2NoStringRecommended
statusYes- 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_idYesStringAssignment ID / message ID of the return request
bank_data.cancellation_idYesStringCancellation ID / transaction ID of the return request
bank_data.original_message_idYesStringOriginal message ID of the underlying payment
bank_data.original_end_to_end_idYesStringOriginal end-to-end ID of the underlying payment
bank_data.original_transaction_idYesStringOriginal transaction ID of the underlying payment
bank_data.original_payment_value_dateNoStringRecommended
bank_data.original_payment_amountNoInteger (in minor units, e.g. EUR 10.00 = 1000)Recommended
bank_data.original_payment_currencyNoISO 4217 currency codeRecommended
metadataNoString, format is `key=valkey2=val2`key=val|key2=val2

CSV Example

idconnected_account_idrelated_payment_idrelated_payment_naturepayment_typestatusreturn_reasonvalue_dateorigin_holder_nameorigin_bank_accountorigin_bank_codeorigin_holder_address.building_numberorigin_holder_address.street_nameorigin_holder_address.postal_codeorigin_holder_address.cityorigin_holder_address.countryorigin_holder_address.line_1origin_holder_address.line_2destination_holder_namedestination_bank_accountdestination_bank_codedestination_holder_address.building_numberdestination_holder_address.street_namedestination_holder_address.postal_codedestination_holder_address.citydestination_holder_address.countrydestination_holder_address.line_1destination_holder_address.line_2bank_data.assignment_idbank_data.cancellation_idbank_data.original_message_idbank_data.original_end_to_end_idbank_data.original_transaction_idbank_data.original_payment_value_datebank_data.original_payment_amountbank_data.original_payment_currencymetadata
33aae6c2-eb19-4c6d-beaa-a601fb53d6a2c3ab7e0a-8f44-45ad-8c91-413776ed5aa92ba9ced1-7c8c-4d62-88cd-55b98f7c43eepayment_ordersepasentCUST2024-10-12Acme corpFR1730003000409633757835C70SOMEBIC0XXX12rue de Rivoli75001ParisFRSoftwareCoFR6610096000402172451384L74SOMEBIC0XXX43000MontpellierFR71 Boulevard Raspail7501444326565325632CxlId05165154O00001MSGIDORIGINEPassPRISmopFMOKTXIDORIGINE2024-10-215599EURcustomer_id=456|payment_id=78321783
e1aeea65-5cfe-4e95-930f-4c3d521b0e3c0218ea93-df86-4c08-8b53-2684d91f72a0d8704d50-45eb-4920-8991-502f782eafa2incoming_paymentsepa_instantreceivedAM092024-10-15Jake McGuinnessFR1730003000409633757835C70SOMEBIC0XXXLyonFR45 rue de la Bourse69000PartnerFR6610096000402172451384L74SOMEBIC0XXX125avenue Générale De Gaulle69000LyonFR903289183929382133231524513HHDZHGQDH23GH9989231832VV21H3H232132024-09-1414000EURcustomer_id=456|payment_id=78321783

Direct debit mandate

Columns

FieldMandatory?FormatNotes
idYesUUIDUnique UUID v4 representing the entry
connected_account_idYesUUIDNumeral connected account UUID
statusYes- active for active mandates
- blocked for temporarily blocked mandates
- disabled for permanently disabled mandates
directionYes- incoming (for incoming direct debits)
- outgoing (for outgoing direct debits)
typeYessepa_core, sepa_b2b, or bacs_debit
sequenceYesone_off or recurring
referenceYesStringUnique reference of the mandate
signature_dateConditionalDate in YYYY-MM-DD, e.g. 2024-04-25Mandatory for SEPA direct debit payments
creditor_holder_nameConditionalStringMandatory for indirect payments
creditor_bank_accountConditionalIBAN or local account number (UK, AU, etc.)Mandatory for indirect payments
creditor_bank_codeConditionalSWIFT/BIC or local bank code (Sort code, BSB, etc.)Mandatory for indirect payments
creditor_creditor_identifierConditionalSEPA creditor identifier / ICS / SUNMandatory for direct debit indirect payments
creditor_holder_address.building_numberNoString
creditor_holder_address.street_nameNoString
creditor_holder_address.postal_codeNoString
creditor_holder_address.cityNoStringRecommended for indirect payments
creditor_holder_address.countryNoISO 3166 alpha-2 country code, e.g. GB, FR, or USRecommended for indirect payments
creditor_holder_address.line_1NoString
creditor_holder_address.line_2NoString
debtor_holder_nameYesString
debtor_bank_accountYesIBAN or local account number (UK, AU, etc.)
debtor_bank_codeYesSWIFT/BIC or local bank code (Sort code, BSB, etc.)
debtor_holder_address.building_numberNoStringRecommended
debtor_holder_address.street_nameNoStringRecommended
debtor_holder_address.postal_codeNoStringRecommended
debtor_holder_address.cityNoStringRecommended
debtor_holder_address.countryNoISO 3166 alpha-2 country code, e.g. GB, FR, or USRecommended
debtor_holder_address.line_1NoStringRecommended
debtor_holder_address.line_2NoStringRecommended
metadataNoString, format is `key=valkey2=val2`key=val|key2=val2

CSV Example

idconnected_account_idstatustypedirectionsequencereferencesignature_datecreditor_holder_namecreditor_bank_accountcreditor_bank_codecreditor_creditor_identifiercreditor_holder_address.building_numbercreditor_holder_address.street_namecreditor_holder_address.postal_codecreditor_holder_address.citycreditor_holder_address.countrycreditor_holder_address.line_1creditor_holder_address.line_2debtor_holder_namedebtor_bank_accountdebtor_bank_codedebtor_holder_address.building_numberdebtor_holder_address.street_namedebtor_holder_address.postal_codedebtor_holder_address.citydebtor_holder_address.countrydebtor_holder_address.line_1debtor_holder_address.line_2metadata
33aae6c2-eb19-4c6d-beaa-a601fb53d6a2c3ab7e0a-8f44-45ad-8c91-413776ed5aa9activesepa_coreoutgoingrecurringRUM-67321646732024-02-18Amazon PrimeFR0412739000305195464554M44SOMEBIC0XXXFR22ZZZ123456712rue de la Bourse75002ParisFRJohn DoeFR3114508000409641325438I80SOMEBIC1XXX8rue du Faubourg Poissonnière75010ParisFRfoo=bar|baz=323
2ffe2226-0d13-46d9-901a-29dfccdf6590c3ab7e0a-8f44-45ad-8c91-413776ed5aa9blockedsepa_b2bincomingone_off8GE67894H4A2024-12-06NetflixFR3114508000409641325438I80SOMEBICYXXXFR22ZZZ123905FR166 bis Rue Rivoli75001 ParisNetflix PLCFR0412739000305195464554M44SOMEBIC0XXX19rue de la Guillotière69000LyonFR
e1aeea65-5cfe-4e95-930f-4c3d521b0e3c0218ea93-df86-4c08-8b53-2684d91f72a0disabledbacs_debitincomingrecurring094867843873437824Spotify Ltd7810456350505089478410Downing Street0L W6 72LondonGBSpotify Ltd7847826460606033Cavendish SquareWU 0ZELondonGBcustomer_id=32323|invoice_id=3672376346736724

ℹ️

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