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 theirrelated_payment_id
column must reference theid
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
Field | Mandatory? | Format | Notes | |
---|---|---|---|---|
id | Yes | UUID / custom id | Unique ID representing the entry | |
connected_account_id | Yes | UUID | 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 | Mandatory for indirect payments | |
origin_creditor_identifier | Conditional | SEPA creditor identifier / ICS / 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 | |
destination_holder_name | Yes | String | ||
destination_bank_account | Yes | IBAN or local account number | ||
destination_bank_code | Yes | SWIFT/BIC or local bank code | ||
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 | |
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, `key=val | key2=val2` | Custom data |
metadata | No | String, `key=val | key2=val2` | Custom metadata |
CSV Example
id | connected_account_id | direction | payment_type | amount | currency | value_date | status | purpose | reference | confidentiality_option | treasury_option | fee_option | origin_holder_name | origin_bank_account | origin_bank_code | origin_creditor_identifier | origin_holder_address.building_number | origin_holder_address.street_name | origin_holder_address.postal_code | origin_holder_address.city | origin_holder_address.country | origin_holder_address.line_1 | origin_holder_address.line_2 | destination_holder_name | destination_bank_account | destination_bank_code | destination_holder_address.building_number | destination_holder_address.street_name | destination_holder_address.postal_code | destination_holder_address.city | destination_holder_address.country | destination_holder_address.line_1 | destination_holder_address.line_2 | sdd_mandate_sequence | sdd_mandate_type | sdd_mandate_signature_date | sdd_mandate_reference | bank_data.message_id | bank_data.end_to_end_id | bank_data.transaction_id | custom_fields | metadata |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ca928885-5734-4f45-8ade-6374cd9111fa | 2ba9ced1-7c8c-4d62-88cd-55b98f7c43ee | credit | sepa | 17067 | EUR | 2024-10-17 | executed | Invoice 352635 | NaN | NaN | NaN | NaN | NaN | NaN | 75002.0 | 3267362763 | 777782372737827 | 451245324345235 | customer_id=123|payment_id=37288738273 | foo=bar|baz=42 | ||||||||||||||||||||||
98651064-ba4d-4e70-851c-70d5fa1e004e | e487f771-4b56-474a-8cf0-a13963ffb87d | debit | sepa | 17067 | EUR | 2024-10-19 | received | Repayment ; 24515213 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | recurring | sepa_core | 2024-06-28 | RUM-3256352 | 783278323 | 55236545634636 | 98938928934 | customerid=123|payment_id= |
Incoming Payment
Columns
Field | Mandatory? | Format | Notes | |
---|---|---|---|---|
id | Yes | UUID / custom id | Unique ID representing the entry | |
connected_account_id | Yes | UUID | Numeral connected account UUID | |
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 Service User Number / 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 | |
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 | |
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 |
CSV Example
id | connected_account_id | type | direction | amount | currency | value_date | requested_execution_date | status | reference | origin_holder_name | origin_bank_account | origin_bank_code | origin_creditor_identifier | origin_holder_address.building_number | origin_holder_address.street_name | origin_holder_address.postal_code | origin_holder_address.city | origin_holder_address.country | origin_holder_address.line_1 | origin_holder_address.line_2 | destination_holder_name | destination_bank_account | destination_bank_code | destination_holder_address.building_number | destination_holder_address.street_name | destination_holder_address.postal_code | destination_holder_address.city | destination_holder_address.country | destination_holder_address.line_1 | destination_holder_address.line_2 | sdd_mandate_sequence | sdd_mandate_type | sdd_mandate_signature_date | sdd_mandate_reference | bank_data.message_id | bank_data.end_to_end_id | bank_data.transaction_id | metadata |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0218ea93-df86-4c08-8b53-2684d91f72a0 | 2ba9ced1-7c8c-4d62-88cd-55b98f7c43ee | sepa | credit | 17067 | EUR | 17/10/2024 | received | Invoice 352635 | Acme corp | FR1730003000409633757835C70 | SOMEBIC0XXX | 12 | rue de Rivoli | 75001 | Paris | FR | SoftwareCo | FR6610096000402172451384L74 | SOMEBIC0XXX | Montpellier | FR | 71 Boulevard Raspail | 75014 | 3267362763 | 7.77782E+14 | 4.51245E+14 | customer_id=123|payment_id=37288738273 | |||||||||||
7fad61d4-9df9-4505-95ee-66681c63cddd | e487f771-4b56-474a-8cf0-a13963ffb87d | sepa | debit | 17067 | EUR | 19/10/2024 | 19/10/2024 | received | Repayment ; 24515213 | Jake McGuiness | FR1730003000409633757835C70 | SOMEBIC0XXX | FR77AAA323672 | 166 | Boulevard des Italiens | 75009 | Paris | FR | Acme | FR6610096000402172451384L74 | SOMEBIC0XXX | 14 bis | rue Turbigo | 75002 | Paris | FR | 3.62717E+12 | 8.98219E+11 | 2341556323 | customer_id=123|payment_id=67236732673 | ||||||||
02cdd16c-951d-4e7c-b143-2a893689ed94 | 0910cd69-6fc8-43e5-afe1-3a3d61020cd4 | sepa_instant | credit | 60300 | EUR | 11/10/2024 | pending_return | Invoice 63727321 | PartnerCo | FR1730003000409633757835C70 | SOMEBIC0XXX | FR6610096000402172451384L74 | SOMEBIC0XXX | Montpellier | FR | 71 Boulevard Raspail | 75014 | 3267362763 | 7.77782E+14 | 4.51245E+14 | customer_id=123|payment_id=37288738273 |
Return Request
Columns
Field | Mandatory? | Format | Notes | |
---|---|---|---|---|
id | Yes | UUID / custom id | Unique ID representing the entry | |
connected_account_id | Yes | UUID | 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 | |
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 | |
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 |
CSV Example
id | connected_account_id | related_payment_id | related_payment_nature | payment_type | status | return_reason | value_date | origin_holder_name | origin_bank_account | origin_bank_code | origin_holder_address.building_number | origin_holder_address.street_name | origin_holder_address.postal_code | origin_holder_address.city | origin_holder_address.country | origin_holder_address.line_1 | origin_holder_address.line_2 | destination_holder_name | destination_bank_account | destination_bank_code | destination_holder_address.building_number | destination_holder_address.street_name | destination_holder_address.postal_code | destination_holder_address.city | destination_holder_address.country | destination_holder_address.line_1 | destination_holder_address.line_2 | bank_data.assignment_id | bank_data.cancellation_id | bank_data.original_message_id | bank_data.original_end_to_end_id | bank_data.original_transaction_id | bank_data.original_payment_value_date | bank_data.original_payment_amount | bank_data.original_payment_currency | metadata |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
33aae6c2-eb19-4c6d-beaa-a601fb53d6a2 | c3ab7e0a-8f44-45ad-8c91-413776ed5aa9 | 2ba9ced1-7c8c-4d62-88cd-55b98f7c43ee | payment_order | sepa | sent | CUST | 2024-10-12 | Acme corp | FR1730003000409633757835C70 | SOMEBIC0XXX | 12 | rue de Rivoli | 75001 | Paris | FR | SoftwareCo | FR6610096000402172451384L74 | SOMEBIC0XXX | 43000 | Montpellier | FR | 71 Boulevard Raspail | 75014 | 44326565325632 | CxlId05165154O00001 | MSGIDORIGINE | PassPRISmopFMOK | TXIDORIGINE | 2024-10-21 | 5599 | EUR | customer_id=456|payment_id=78321783 | ||||
e1aeea65-5cfe-4e95-930f-4c3d521b0e3c | 0218ea93-df86-4c08-8b53-2684d91f72a0 | d8704d50-45eb-4920-8991-502f782eafa2 | incoming_payment | sepa_instant | received | AM09 | 2024-10-15 | Jake McGuinness | FR1730003000409633757835C70 | SOMEBIC0XXX | Lyon | FR | 45 rue de la Bourse | 69000 | Partner | FR6610096000402172451384L74 | SOMEBIC0XXX | 125 | avenue Générale De Gaulle | 69000 | Lyon | FR | 9032891839293821 | 33231524513 | HHDZHGQDH23GH | 9989231832 | VV21H3H23213 | 2024-09-14 | 14000 | EUR | customer_id=456|payment_id=78321783 |
Direct debit mandate
Columns
Field | Mandatory? | Format | Notes | |
---|---|---|---|---|
id | Yes | UUID | Unique UUID v4 representing the entry | |
connected_account_id | Yes | UUID | 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 | SEPA creditor identifier / ICS / 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 |
CSV Example
id | connected_account_id | status | type | direction | sequence | reference | signature_date | creditor_holder_name | creditor_bank_account | creditor_bank_code | creditor_creditor_identifier | creditor_holder_address.building_number | creditor_holder_address.street_name | creditor_holder_address.postal_code | creditor_holder_address.city | creditor_holder_address.country | creditor_holder_address.line_1 | creditor_holder_address.line_2 | debtor_holder_name | debtor_bank_account | debtor_bank_code | debtor_holder_address.building_number | debtor_holder_address.street_name | debtor_holder_address.postal_code | debtor_holder_address.city | debtor_holder_address.country | debtor_holder_address.line_1 | debtor_holder_address.line_2 | metadata |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
33aae6c2-eb19-4c6d-beaa-a601fb53d6a2 | c3ab7e0a-8f44-45ad-8c91-413776ed5aa9 | active | sepa_core | outgoing | recurring | RUM-6732164673 | 2024-02-18 | Amazon Prime | FR0412739000305195464554M44 | SOMEBIC0XXX | FR22ZZZ1234567 | 12 | rue de la Bourse | 75002 | Paris | FR | John Doe | FR3114508000409641325438I80 | SOMEBIC1XXX | 8 | rue du Faubourg Poissonnière | 75010 | Paris | FR | foo=bar|baz=323 | ||||
2ffe2226-0d13-46d9-901a-29dfccdf6590 | c3ab7e0a-8f44-45ad-8c91-413776ed5aa9 | blocked | sepa_b2b | incoming | one_off | 8GE67894H4A | 2024-12-06 | Netflix | FR3114508000409641325438I80 | SOMEBICYXXX | FR22ZZZ123905 | FR | 166 bis Rue Rivoli | 75001 Paris | Netflix PLC | FR0412739000305195464554M44 | SOMEBIC0XXX | 19 | rue de la Guillotière | 69000 | Lyon | FR | |||||||
e1aeea65-5cfe-4e95-930f-4c3d521b0e3c | 0218ea93-df86-4c08-8b53-2684d91f72a0 | disabled | bacs_debit | incoming | recurring | 094867843873437824 | Spotify Ltd | 78104563 | 505050 | 894784 | 10 | Downing Street | 0L W6 72 | London | GB | Spotify Ltd | 78478264 | 606060 | 33 | Cavendish Square | WU 0ZE | London | GB | customer_id=32323|invoice_id=3672376346736724 |
Relationships between return requests and payment orders are preserved via
related_payment_id
andrelated_payment_type
fields.
Updated about 7 hours ago