Field Mapping Payload Reference

Complete field mapping reference for all Unify API v3 payload fields organized by country. Last Updated: 2026 · Scope: SA · MY · BE · DE · AE

Overview

This page is the entry point for country-specific field mappings.

Each country page contains:

Complete sample payload at the top — copy-paste ready JSON showing all fields in one example
JSON field paths in SDK payload format (flat snake_case) — exactly what you send in API requests
Field mapping tables with Type, Required, Description, and Example columns
Country-specific extension fields merged from GETS Country Extensions
Data formatting and implementation notes for production use

SDK Payload Format

All field paths documented here use the SDK payload format — a flat snake_case structure that maps directly to the JSON you send in API requests:

{
  "invoice_data": { "document_number": "INV-001", ... },
  "seller_info": { "seller_name": "...", ... },
  "buyer_info": { "buyer_name": "...", ... },
  "line_items": [ { "item_name": "...", ... } ],
  "payment_info": { "payment_means_code": "...", ... }
}

This differs from the GETS canonical format (nested camelCase like header.documentNumber, parties.seller.name) which is used internally but not documented here.

Country Extensions Overview

Country extension fields are additional fields applied on top of the base mapping for regulatory or network-specific requirements.

Requirement levels

Code	Meaning
`M`	Mandatory
`CM`	Conditionally mandatory
`O`	Optional

Country extension coverage summary

Country	Extension status	Notes
Saudi Arabia (SA)	Active	`sa_prepayment` extension is used for prepayment and adjustment scenarios.
Malaysia (MY)	Base model only	Uses standard GETS payload without a separate extension block.
United Arab Emirates (AE)	Active	UAE-specific extension fields for authority, customs, process, and tax-currency details.
Belgium (BE)	Active	VAT and digital timestamp extension fields are supported.
Germany (DE)	Active	XRechnung-related extension fields are supported, including preceding invoice date behavior.

Country Pages

Country	Code	Coverage	Page
Saudi Arabia	SA	ZATCA field mapping + SA prepayment extensions	Open Saudi Arabia Field Mapping
Malaysia	MY	LHDN field mapping + Malaysia extension notes	Open Malaysia Field Mapping
Belgium	BE	Peppol BIS mapping + BE VAT/digital extensions	Open Belgium Field Mapping
Germany	DE	XRechnung mapping + DE extension fields	Open Germany Field Mapping
United Arab Emirates	AE	PINT AE mapping + AE extension fields	Open UAE Field Mapping

How To Use This Reference

Open your country page from the table above.
Copy the Complete Sample Payload at the top as a starting template for your integration.
Use the JSON Field Path column in each table to know the exact field names to use in your API requests.
Follow the sections in order: Document Header → Seller → Buyer → Payment → Line Items → Totals.
Review the Country Extensions section to include country-specific fields.
Keep the field semantics exactly as documented in the table columns.

Data Formatting Guidelines

Dates: All dates must be in YYYY-MM-DD format (e.g., 2024-01-15)
Times: All times must be in HH:MM:SS or HH:MM:SSZ format (e.g., 14:30:00)
Decimal Amounts: Use . as decimal separator (e.g., 1000.00)
Currency Codes: Follow ISO 4217 standard (e.g., SAR, MYR, EUR, AED)
Country Codes: Follow ISO 3166-1 alpha-2 standard (e.g., SA, MY, BE, DE, AE)
Phone Numbers: Include country code (e.g., +966501234567)
Amounts: Always include two decimal places (e.g., 1234.56)