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.

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.
• Only a single regulatoryReporting can be specified in the CSV format, while the API JSON format accepts an array.

Batch treatment type

When creating a payments batch you can specify batch treatment which can be either INDIVIDUAL_PAYMENTS or BATCH. The difference between the two is how payment approvals are handled. When treatment is INDIVIDUAL_PAYMENTS, approvals and rejections are managed on per payment basis just as if the payment was created as a single payment (i.e. not part a batch). If treatment is BATCH, approvals and rejections are managed on the batch level.

Note that if treatment is BATCH, payments can only be approved on batch level and cannot be approved or rejected on an individual basis. Vice versa also applies for treatment INDIVIDUAL_PAYMENTS, that payments cannot be approved or rejected on batch level but only on an individual basis.