If you’ve ever tried to submit CPF contributions manually, you already know the moment of dread: the CPF EZPay portal doesn’t accept Excel files. It accepts one specific file format, a 150-byte-per-line fixed-width DTL file, named using an arcane convention that includes your UEN, advice code, and a three-letter month abbreviation. Get one byte wrong and the upload fails.

The good news is you don’t have to hand-craft that DTL file. The standard workflow is: build a structured spreadsheet, then feed it into a tool (like ours) that generates the DTL file for you. The bad news is that the spreadsheet itself has its own strict format requirements, and getting those wrong is what causes most rejected submissions.

This article walks through the spreadsheet format we recommend for CPF EZPay submission, including every required field, the validation rules that catch people out, and the easiest way to produce a compliant spreadsheet without reading a spec document.

Skip the spec, build your CPF-ready spreadsheet free →

The 4-Sheet Structure Your Spreadsheet Needs

A CPF-ready payroll spreadsheet needs four sheets, each serving a distinct purpose. The naming matters. Tools that parse the spreadsheet (including ours) look for these exact sheet names.

Sheet 1: params (global parameters)

This sheet holds the run-level parameters that apply to the whole submission. It’s a simple two-column key-value layout.

Key Example Notes
bank_file_code SG_DBS_IDEAL Identifies which bank file format to generate alongside CPF
country_code SG ISO country code
month 2 The CPF “relevant month”, the month the wages relate to
year 2026 Year of the relevant month

The month and year fields matter because CPF EZPay’s filename includes the month abbreviation (FEB23, MAR26). These come from params.month and params.year.

Sheet 2: metadata (payment dates)

Key Example Notes
pay_date 2026-02-25 When the bank should execute the salary payment (ISO format)
value_date 2026-02-23 When funds become available to the recipient

CPF EZPay itself doesn’t use these dates. It derives its dates from params.month/year and applies its own on receipt. But if you’re generating a bank file alongside your CPF file (which most employers are), both fields are required.

Sheet 3: company (employer details)

This sheet contains your company’s CPF-relevant information.

Key Required for CPF? Notes
name Yes Company name
uen Yes 10-character UEN. CPF rejects submissions with wrong-length UENs.
payment_type Yes (default PTE) PTE, AMS, or VCT. Most private employers use PTE.
sno Yes (default 01) Must be exactly 2 characters, e.g. "01" not "1". This is the most common formatting mistake.
dbs_id No (bank-only) Only used for DBS IDEAL bank file, not CPF
bank_account_* No (bank-only) Used for bank file, ignored by CPF

The two CPF-critical fields are uen (must be 10 chars) and sno (must be 2 chars). These combine with the advice code to form your CSN (Contribution Submission Number), which CPF uses to identify every submission you make.

Sheet 4: employees (one row per employee)

This is the meat of the spreadsheet. Each row is one employee’s CPF contribution for the month.

Required columns (header row, exact names):

Column Why it’s needed
name Display name on CPF records
nric 9-character NRIC/FIN with valid check digit
birthdate YYYY-MM-DD. Drives age bracket for CPF rate.
immigration_status One of SC (Singapore Citizen), SPR1, SPR2, SPR3 (SPR years 1/2/3+)
gross_salary Ordinary Wages for the month
employee_contribution CPF deducted from employee’s pay
employer_contribution CPF paid on top by employer
additional_wages Bonuses, AWS for the month (default 0)
ytd_ow_paid YTD Ordinary Wages before this run (for AW cap)
ytd_aw_paid YTD Additional Wages before this run (for AW cap)
employment_status E (existing), L (leaver), N (new), O (joined+left same month)
shg_type Optional: CDAC, MBMF, SINDA, ECF

The four strictly-required rows above (birthdate, immigration_status, ytd_ow_paid, ytd_aw_paid) will hard-fail the upload if blank. This catches people out because older CPF spreadsheets didn’t track YTD values. They’re now mandatory because the CPF AW annual cap ($102,000) can’t be applied correctly without them.

Common Spreadsheet Format Mistakes

Mistake 1: NRIC without a valid check digit

NRICs aren’t just “S” + 7 digits + letter. The final letter is a check digit calculated from the digits using a published algorithm. CPF EZPay validates this and rejects rows where the check digit doesn’t match.

The fix: either implement the algorithm in your spreadsheet (one Excel formula does it), or use our free /build tool which validates as you type.

Mistake 2: sno as a number instead of text

If you type 1 in a cell, Excel often stores it as a number. CPF EZPay expects "01" as text. Same for payment_type: use PTE not pte. The safest approach is to format these cells as Text before typing.

Mistake 3: Missing birthdate or immigration_status

Older CPF spreadsheets didn’t need these because the employer hand-calculated CPF contributions and just entered the dollar amounts. The current format requires them because the rate engine uses them to validate your numbers. If you say an employee owes $1,200 in employee CPF but their birthdate + immigration status + gross salary should produce $1,150, the system flags it.

Mistake 4: YTD columns blank

The CPF Additional Wage annual cap is $102,000. Once an employee’s combined OW + AW for the year hits $102,000, no more CPF is due on additional wages. To apply this cap correctly every month, the system needs to know YTD figures. Set to 0 if it’s the first run of the year. Don’t leave blank.

Mistake 5: Renamed sheet tabs

The four sheets must be named exactly params, metadata, company, employees (lowercase). Tools that parse the spreadsheet look for these names. “Company Info” or “Params Sheet” won’t be found.

What CPF EZPay Actually Does With Your Data

Once your spreadsheet produces a DTL file (or once our tool does it for you), CPF EZPay expects:

  • Filename: {CSN}{AdviceCode}{MONTH}{YY}.DTL. Example: 201405871RPTE0101FEB26.DTL
  • Each line exactly 150 bytes, fixed-width, no delimiters
  • Record types: Header, Summary (one per payment code), Detail (one per employee per code), Trailer

Where CSN = UEN + PaymentType + Sno. Example: 201405871R + PTE + 01 = 201405871RPTE01.

You don’t need to memorise this, but it’s useful context for why the spreadsheet fields exist and why getting them wrong cascades into a broken submission.

The Easy Path: Use Our Free Spreadsheet Builder

Our /build tool is the simplest way to produce a CPF-ready spreadsheet. You fill in a form, the tool generates a properly-formatted .xlsx with all four sheets, all required columns, all validation already applied. CPF contributions auto-calculate from birthdate + immigration status + wages using 2026 rates.

The form:

  • Validates NRIC check digits as you type
  • Enforces sno and payment_type formats
  • Calculates CPF using the current rate engine
  • Lets you override per-row for edge cases (prorated months, prior adjustments)
  • Outputs a .xlsx you can either upload to PayGoSG for DTL generation, or keep as your monthly payroll record

No spec document to read. No formulas to debug. Free, no login required.

Build your CPF-ready spreadsheet free →

Frequently Asked Questions

Does CPF EZPay accept Excel files directly? No. CPF EZPay accepts only the fixed-width DTL file format. The spreadsheet is the intermediate format you author; a tool (like ours) generates the DTL file from it.

What if I have an existing spreadsheet from another payroll system? Most likely it’ll need column renaming and possibly adding the YTD columns. The format described above is what produces a clean CPF EZPay DTL file via our pipeline.

Why do I need birthdate if I’m providing employee_contribution directly? The CPF rate engine cross-checks your submitted contribution against what should be owed given the employee’s age, immigration status, and wages. This catches typos and out-of-date rates before they reach CPF Board.

What’s the difference between gross_salary (OW) and additional_wages (AW)? Ordinary Wages are the standard monthly salary. Additional Wages are bonuses, AWS, commissions. Anything outside the regular monthly amount. CPF treats them differently for the annual cap calculation.

Where can I find current CPF rates? See our complete CPF contribution rates guide for the 2025/2026 rate tables, age brackets, and immigration status rules.

Stop Wrestling With CPF EZPay Formatting

The CPF EZPay DTL format is unforgiving: 150 bytes per line, strict filename convention, validation on every field. But the DTL file itself is generated from your spreadsheet, so the real bottleneck is the spreadsheet format.

Get the four sheets right, validate your NRICs, set sno and payment_type correctly, fill in the YTD columns, and your CPF submission will sail through. Or skip all of that and build your spreadsheet free with /build.

Build your CPF-ready spreadsheet free →

This article was written by Sarah Tan, Communications Specialist at PayGoSG. Visit paygosg.com to learn more about our simple payroll solutions for Singapore businesses.