Credit Transfer Batches

Credit transfer batches can be created by uploading a CSV file via https://app.atlar.com/credit-transfers-batches or as a JSON payload using API endpoint https://api.atlar.com/payments/v2beta/credit-transfer-batches.

CSV format

The CSV content must include a header line (first row). Some field names are required in the header line while some are optional. Header field names are one-to-one mapped to JSON property names in our API (except for the simplifications mentioned below: CSV format differences to JSON API formats.

Minimal example

amount.currency,amount.stringValue,date,scheme,reference,source.type,source.id,destination.type,destination.id
EUR,2.00,2024-02-20,SCT,invoice-no.121,ACCOUNT,a422e2ae-5fc4-4463-8cda-24aaa779ed5f,EXTERNAL_ACCOUNT,31380a97-f54b-4ae3-8f7e-3541c2914db6

Fields

The table below lists all supported fields and whether they are required or optional. Note that some fields are conditionally required based on values of other fields. If any record line in the file meets the conditions for whether a field is required or not that also implies that the field must be specified in the header line. E.g. if any record line specifies the value INLINE for the field destination.type that also means destination.market, destination.holder.legalName and destination.identifier.{type,market,number} are required in the header line.

Also see the API reference docs for more details on the fields and valid values.

Field	Required	Format
`amount.currency`	Required	3-letter code
`amount.stringValue`	Required	Must have same number of decimals as currency. Use period `.` as decimal point.
`date`	Required	`yyyy-mm-dd`
`scheme`	Required	See create credit-transfer
`reference`	Required
`source.type`	Required	`ACCOUNT`
`source.id`	Required	The Atlar identifier of the source account. Find it in the Atlar dashboard.
`destination.type`	Required	`ACCOUNT` for internal transfers of own Accounts, `EXTERNAL_ACCOUNT` for already created ExternalAccount, or `INLINE`
`destination.id`	Required when `destination.type` is `EXTERNAL_ACCOUNT` or `ACCOUNT`	The Atlar identifier of the destination account. Find it in the Atlar dashboard.
`destination.market`	Required when `destination.type` is `INLINE`	2-letter code
`destination.holder.legalName`	Required when `destination.type` is `INLINE`
`destination.identifier.type`	Required when `destination.type` is `INLINE`	One of: `NUMBER`, `IBAN`, `SE_BANKGIRO`, `SE_PLUSGIRO`
`destination.identifier.market`	Required when `destination.type` is `INLINE`	2-letter code
`destination.identifier.number`	Required when `destination.type` is `INLINE`	No formatting like spaces or dashes
`destination.bic`	Optional	8, or 11 characters
`destination.routing.type`	Optional	See create credit-transfer
`destination.routing.number`	Optional	No formatting like spaces or dashes
`externalId`	Optional	Must be unique across all your payments. See External IDs.
`metadata.<key>`	Optional. Multiple fields with different `<key>` values are allowed.

Inlining destination account

As an alternative to referencing pre-existing External Accounts and Counterparties (by IDs) the destination account information can be inlined in the CSV file. This is done by specifying the value INLINE as destination.type and including additional fields destination.market, destination.holder.legalName etc.

Inline data example:

amount.currency,amount.stringValue,date,scheme,reference,source.type,source.id,destination.type,destination.market,destination.holder.legalName,destination.identifier.type,destination.identifier.market,destination.identifier.number,destination.bic
USD,123.45,2024-01-23,CROSS_BORDER,invoice-no.205,ACCOUNT,d89b7f42-62b9-47d2-8969-0743f32ebc0d,INLINE,US,John Smith,NUMBER,US,123456789012,CHASUS33XXX

When a payments batch with INLINE content is processed, corresponding external accounts and counterparties will automatically be created. If the destination fields can be matched to an existing counterparty and external account then the existing counterparty and account will be used and no new will be created. Note that for a record line to be considered matching an existing API resources it must be an exact match in terms of:

destination.holder.legalName matching the Counterparty.legalName
destination account number and routing information must be an exact match.

Metadata fields

Creating payments with multiple metadata keys are supported by specifying multiple header fields on the form metadata.<your metadata key>.

Example:

...,metadata.comment,metadata.my-id
...,"My comment #1",my-id-123
...,"My comment #2",my-id-456

Examples

The following example shows a mix of all the functionality described above:

Inline destination account information.
Referencing existing destination account API resources.
Specifying destination routing information (GB sort code, BIC, US ABA routing number).
Optional fields like externalId and metadata.<key>.

amount.currency,amount.stringValue,date,scheme,reference,externalId,source.type,source.id,destination.type,destination.id,destination.market,destination.holder.legalName,destination.identifier.type,destination.identifier.market,destination.identifier.number,destination.bic,destination.routing.type,destination.routing.number,metadata.comment,metadata.my-id
SEK,12.34,2024-02-20,SE_GIRO,invoice-no.119,,ACCOUNT,d73067c3-5427-40b5-b63b-76f89acb5a72,INLINE,,SE,anders andersson,SE_BANKGIRO,SE,12345678,,,,,
DKK,51.35,2024-02-20,DK_A2A,invoice-no.120,,ACCOUNT,57f6dcce-a4f9-4fc7-b496-182c4df0a60c,ACCOUNT,eb2ba9c1-ec7d-43e2-8724-9c85af870308,,,,,,,,,,
EUR,2.00,2024-02-20,SCT,invoice-no.121,,ACCOUNT,d89b7f42-62b9-47d2-8969-0743f32ebc0d,EXTERNAL_ACCOUNT,31380a97-f54b-4ae3-8f7e-3541c2914db6,,,,,,,,,,
GBP,531.42,2024-02-20,GB_CT_FPS,invoice-no.122,,ACCOUNT,5755d02f-0937-492b-adf3-c045cc4e0fa9,INLINE,,GB,John Doe,NUMBER,GB,12345678,,GB_DSC,123456,this is the payment for xyz,21743612948719284
USD,123.45,2024-02-20,CROSS_BORDER,invoice-no.123,,ACCOUNT,5755d02f-0937-492b-adf3-c045cc4e0fa9,INLINE,,US,John Smith,NUMBER,US,123456789012,BOFAUS3NXXX,US_ABA,123456789,"use the metadata fields, to set anything you would like",129572198421

CSV format differences to JSON API formats

destination.bic is shorthand for adding a routing identifier (destination.routing) of type BIC.
destination.identifier and destination.routing can in the CSV format only represent a single account identifier and routing identifier in contrast to the API JSON format where destination.identifiers and destination.routing are array types.