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

Process

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, 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

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

ℹ️
Import CSV templates can be downloaded here.

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 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
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 / 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, 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 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

Return requests

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

ℹ️
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 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

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