Sign in

v1

latestOpenAPI 3.1.0© Modulr Finance2026-08-04207430590.4 KB
Payments

Make a batch payment

As well as supporting individual payment requests, the Modulr payment platform can also handle multiple payment objects in the same request. This endpoint allows you to make a new batch payment.

post/batchpayments

Request body

externalReferencestring

Your reference for this Batch of payments

strictProcessingboolean

Flag to control if the entire batch fails for any individual payment validation failure

submissionType'BATCH' | 'BULK'

BATCH restricts operations to batch level. BULK (default) allows payment level operations such as approval

Example request

{
  "externalReference": "aReference_00001",
  "payments": [
    {
      "destination": {
        "type": "SCAN",
        "iban": "GB20MODR00000000000001",
        "accountNumber": "12345678",
        "sortCode": "000000",
        "name": "Test",
        "birthdate": "2000-01-01",
        "countrySpecificDetails": {
          "bankName": "Apple Bank",
          "bankAddress": "2100 Broadway",
          "bankCity": "New York City",
          "bankBranchName": "New York",
          "bankBranchCode": "44-04",
          "chineseId": "01101201901018889",
          "province": "Zhejiang",
          "abaRoutingNumber": "123456789",
          "business": true,
          "bankCodeType": "ABA",
          "bankCountry": "US"
        }
      },
      "reference": "Salary",
      "externalReference": "aReference_00001",
      "endToEndReference": "aReference_00001",
      "regulatoryReporting": {
        "type": "CRED",
        "regulatoryAuthority": {
          "authorityName": "Financial Conduct Authority",
          "authorityCountry": "GB"
        }
      },
      "paymentDate": "2017-01-28",
      "overseasPaymentDetail": {
        "ultimatePayer": {
          "address": {
            "addressLine1": "2nd Floor",
            "addressLine2": "123 High Street",
            "postTown": "Edinburgh",
            "postCode": "AB12 3XX",
            "country": "GB"
          },
          "birthDetails": {
            "dateOfBirth": "1978-01-01",
            "cityOfBirth": "Edinburgh",
            "countryOfBirth": "GB"
          },
          "officialIdentification": {
            "drivingLicenceNumber": "JONES849339TS8AD",
            "customerNumber": "23547326547632",
            "socialSecurityNumber": "1110000000022AB",
            "passportNumber": "123456789",
            "idCardNumber": "123456789",
            "otherIdNumber": "123456789"
          },
          "officialIdDetailOrgs": {
            "bankPartyIdentification": "12345",
            "centralBankIdNumber": "678910",
            "clearingIdNumber": "xx15402",
            "certificateOfIncorporationNumber": "1100010",
            "countryIdCode": "111111",
            "customerNumber": "00221133",
            "dataUniversalNumberingSystem": "002211330",
            "employerIdNumber": "00221133",
            "gs1glnIdentifier": "00221133",
            "sirenCode": "00221133",
            "siretCode": "00221133",
            "taxIdNumber": "00221133",
            "bicIdentifier": "MGALODJAO7A",
            "ibeiIdentifier": "HIZFTMTT59",
            "beiIdentifier": "MHIHISVZUMH",
            "eanglnIdentifier": "7516164953429",
            "chipsUniversalIdentifier": "CH157373",
            "genericIdentification3": "123456788",
            "genericIdentificationIssr": "13143225"
          },
          "overseasAccountIdentifier": {
            "iban": "GB20MODR00000000000001",
            "bban": "NWBK60161331926819",
            "upic": "987654321",
            "otherAccountNumber": "987654321"
          },
          "bic": "MODRDEFF123"
        },
        "chargeDetails": {
          "bearer": "CRED",
          "currency": "GBP"
        }
      },
      "nameCheck": {
        "id": "PAV2322342",
        "source": "MODULR"
      }
    }
  ]
}

Response

BatchPaymentReference

idstring

Unique id for the Batch Payment. 10 characters long

externalReferencestring

External reference, if provided

status'ACCEPTED' | 'REJECTED' | 'SUBMITTED' | 'CANCELLED'

Current status of batch.

totalPaymentsinteger

Total count of payments in this batch

currentUserCanApproveboolean

Whether the user is allowed to approve this batch, based on their approval limits, and applicable configuration

paymentDetailsobject

Summary of payments and approvals, per currency (as a 3-alpha currency code)

currentUserCanCancelboolean

Whether the user is allowed and currently able to cancel at least one of the payments in this batch

createdDatestring date-time

Datetime when the batch payment was created. Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000

createdBystring

ID of the user that created the payment

processingDateFromstring date

Earliest processing date in the batch file or the batch creation date if the file does not have any dates. Date format 'yyyy-MM-dd'

processingDateTostring date

Last processing date in the batch file or empty if the file does not have any dates. Date format 'Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000'

earliestScheduledPaymentDatestring date

Earliest processing date in the batch file or empty if the file does not have any dates. Date format 'Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000'

requiredApprovalCountinteger

The number of required approvals for the batch. Applicable to batch payments of submissionType BATCH

strictboolean

Strict processing flag. Whether the entire batch should fail on any individual payment validation failure

Example response

{
  "id": "D920000001",
  "externalReference": "aReference_00001",
  "status": "ACCEPTED",
  "totalPayments": 9123,
  "currentUserCanApprove": true,
  "approvals": [
    {
      "approvedBy": "U2100021",
      "approvedOn": "2022-06-25"
    }
  ],
  "createdDate": "2017-01-28T01:01:01+0000",
  "processingDateFrom": "2017-01-28",
  "processingDateTo": "2017-01-28",
  "earliestScheduledPaymentDate": "2017-01-28"
}