Configure file batching

Where the settings live

File batching is configured in your module's .root-config.json, under settings >
billingSettings. batching decides when payments are collected and how many go into each file.fileConfig sits inside batching, and switches your module from API mode to file mode.

{
  "settings": {
    "billingSettings": {
      "batching": {
        "enabled": true,
        "submitPaymentsFunction": "submitPayments",
        "submitBatchSize": 100,
        "scheduleTimeUtc": "05:00",
        "latestSubmissionTimeUtc": "20:00",
        "submissionLeadTime": 2,
        "fileConfig": {
          "naming": {
            "prefix": "ACMEPAY",
            "dateToken": "ccyymmdd",
            "sequenceSource": "batch_id",
            "maxLength": 40
          },
          "transport": {
            "type": "https",
            "deliveryMethodRef": "0b1c0d2e-3f40-4a51-8b62-7c83d94e05f6"
          },
          "handleResponseFunction": "handleResponseFile",
          "responseVia": "webhook"
        }
      }
    }
  }
}

The batching block

submitBatchSize sets the size of your file as much as the size of the batch, because the platform
calls your hook once per batch and every call produces one file. A partner with a line limit on the
file is really giving you this number.

The submission window

The platform looks for due payments on an hourly tick. A payment is picked up on the first tick where all of the following is true:

• The payment is pending, and not already in a batch.
• It sits on a payment method backed by your collection module.
• Its action date has passed, or falls within submissionLeadTime days.
• The time is at or after scheduleTimeUtc, and before latestSubmissionTimeUtc.

Anything still pending when the window closes waits for tomorrow. Running hourly rather than once a day is deliberate: a tick missed during a deploy is recovered an hour later, not a day later.

Set latestSubmissionTimeUtc well before your partner's real cutoff. The gap between the two is the room the platform has to submit, retry and drain its queues before the partner stops accepting files.

⚠️

Set scheduleTimeUtc and latestSubmissionTimeUtc explicitly, and make the cutoff later than the
start time. The platform compares these two values exactly as they are stored, so a missing value
matches nothing and your payments are never collected. Avoid 00:00 as a cutoff. It reads as the
start of the day rather than the end of it, which stops submission just as completely.

The fileConfig block

http_response means your module captures the reply from the partner's answer to its own delivery request. webhook means the partner posts the reply to the platform later. Handle response files covers both.

File naming

sequenceSource is required because it is the only part of the name that varies. A name built from a prefix and a date alone repeats for every batch on the same day, so the second file would overwrite the first one's stored copy: the record of what you actually sent your partner.

ℹ️

naming records the convention. The name a file is stored under is the file_name you return in
move_to_outbox, so the two match only if you build the name the way you declared it here.

Transport

Your module makes its own HTTPS request to the partner from inside your submission hook. The
platform never delivers the file for you, so neither of these fields is used to reach anyone.

What the platform checks when you publish

Publishing validates the shape of these settings, and rejects the module when anything is wrong. Three checks beyond the field rules above are worth knowing:

• The platform checks submitPaymentsFunction and handleResponseFunction against the functions your module actually exports. A name that does not resolve fails the publish, and the error lists the functions it did find.
• Both names are only checked while enabled is true. A module that is not batching is never blocked over a function it will never call.
• The platform rejects fileConfig outright when enabled is false. File submission runs on the batching path, so there would be nothing to build.

Publishing checks nothing about the file itself. Its content, its layout and your partner's rules for it are your module's business.

Next step

Build and submit the batch file covers the hook the platform calls, and the actions you return to report what you sent.