Overview Atlar supports two types of payment batches: Credit Transfer Batches and Direct Debit Batches. They can be created by uploading a CSV file via Atlar Dashboard or by sending a CSV or JSON payload using the API endpoint POST /payments/v2beta/credit-transfer-batches or POST /payments/v2beta/direct-debit-batches.

Both credit transfer and direct debit batches support CSV upload with a header line (first row) containing field names. Header field names are one-to-one mapped to JSON property names in our API (except for the simplifications mentioned here: CSV format differences to JSON API formats).

Some field names are required while others are optional. Some fields are conditionally required depending on the values of other fields. If any record line in the file meets the conditions for a required field, that field must also be included in the header line.

Credit Transfer Batch

Fields

The table below lists all supported fields for credit transfer batches and whether they are required or optional.

For example: If any record line specifies the value INLINE for the field destination.type, then the fields destination.market, destination.holder.legalName, and destination.identifier.{type,market,number} must also be present in the header line.

For detailed definitions and valid values, see the API reference documentation.

Inlining destination account

As an alternative to referencing pre-existing External Accounts or Counterparties by their IDs, the destination account information can instead be inlined in the CSV file. This is done by setting destination.type to INLINE and including the additional required fields such as destination.market, destination.holder.legalName, and other related details.

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, the corresponding External Accounts and Counterparties are automatically created. If the destination fields match an existing counterparty and external account, the existing resources will be reused and no new records will be created.

For a record line to be considered a match with existing API resources, the following must be exact matches:

• destination.holder.legalName must exactly match the Counterparty.legalName.
• destination account number and routing information must match exactly (no differences in formatting, spacing, or case).

Example scenarios with inlined destination account

The tables below illustrate which optional fields must be populated for certain schemes in different scenarios when inlined destination account information is used. These tables focus only on fields that are marked as optional in the credit transfer fields table; all other required fields remain mandatory.

Note: Direct debit batches do not support inlining destination account information. All direct debit batches must reference existing accounts as it requires an active mandate.

Cross-border payment to GB

A cross-border payment to GB when you have the IBAN of the destination account.

UK account to account Faster Payments (FPS)

When making a domestic payment over Faster Payments and you have the destination account number and sort code.

Cross border payment to the US

When making a cross-border payment to the US, an account number and an ABA routing number are required.

Cross border payment to India

When making a cross-border payment to India, note that regulatory reporting is required.

SEPA Credit Transfer

SEPA is a Single Euro Payments Area that uses the euro (EUR) as its currency. Only payments sent and received in euro can be made as SEPA payments. Both the sending and receiving bank accounts must be domiciled within the SEPA zone.

Examples

The following example demonstrates a mix of the functionality described above:

• Inline destination account information.
• Referencing existing destination account API resources.
• Specifying destination routing information (e.g., GB Sort Code, BIC, US ABA routing number).
• Using 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 only represent a single account identifier and routing identifier in the CSV format. In contrast, the API JSON format allows arrays for destination.identifiers and destination.routing.
• Only a single regulatoryReporting entry can be specified in the CSV format, while the API JSON format accepts an array.

Direct Debit Batch

Fields

The table below lists all supported fields for direct debit batches and whether they are required or optional.

For detailed definitions and valid values, see the API reference documentation.

Examples

The following example shows direct debit batch CSV format:

amount.currency,amount.stringValue,date,scheme,reference,externalId,source.type,source.id,destination.type,destination.id,categoryPurpose,chargeBearer,metadata.comment,metadata.batch-id
EUR,100.00,2025-01-01,SDD_CORE,Minimal SDD CORE request,,EXTERNAL_ACCOUNT,f3da4d77-af13-4e2d-8c33-34440f1580bc,ACCOUNT,d1753050-ee88-44b0-9452-770fc4ae3991,,,Monthly subscription payment,batch-2025-01
SEK,250.50,2025-01-15,AUTOGIRO,Invoice payment 123,,EXTERNAL_ACCOUNT,ca3e14a4-88d1-4df5-a4d8-e6193075d8bc,ACCOUNT,1f28296b-5b83-4be7-a91a-35885b6e4863,,,Recurring payment,batch-2025-01

Metadata fields

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

Example:

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

Sending a CSV over API

Both credit transfer and direct debit batch APIs accept JSON and CSV formats. To upload a CSV file, use multipart/form-data format with the appropriate content type.

Credit Transfer Batches

curl --location 'https://api.atlar.com/payments/v2beta/credit-transfer-batches' \
    --header 'Authorization: Bearer ***' \
    --form 'fileContentType="application/vnd.atlar.payments.v2.credit-transfer.batch+csv"' \
    --form 'file=@"/path-to-your-batch/credit-transfer-batch.csv"' \
    --form 'skipValidationErrors="false"' \
    --form 'treatment="INDIVIDUAL_PAYMENTS"'

Direct Debit Batches

curl --location 'https://api.atlar.com/payments/v2beta/direct-debit-batches' \
    --header 'Authorization: Bearer ***' \
    --form 'fileContentType="application/vnd.atlar.payments.v2.direct-debit.batch+csv"' \
    --form 'file=@"/path-to-your-batch/direct-debit-batch.csv"' \
    --form 'skipValidationErrors="false"' \
    --form 'treatment="INDIVIDUAL_PAYMENTS"'