# Payment File Schema

Use the schema to build valid payment files.

The Payment File Schema defines the fields supported in Payment Network payment files.

Each field includes information about its purpose, applicability, and requirements. Fields marked as **Conditional** are required only when specific criteria are met.

Use this reference together with [File Definitions](/products/deluxe-payment-network/developer-resources/file-definitions) to understand validation rules, formatting requirements, and processing constraints.

### Core Fields

| Field Name | Required | Applies To | Description |
|  --- | --- | --- | --- |
| `recordIdentifier` | Yes | Both | Unique identifier for the payment record. Must be unique within the file. |
| `paymentDate` | Yes | Both | Date associated with the payment. |
| `paymentCheckNumber` | Conditional | Both | Required when a payment amount is provided. |
| `paymentAmountInUsDollar` | Conditional | Both | Payment amount. Must contain exactly two decimal places when supplied. |
| `paymentMemo` | No | Both | Optional memo printed on the payment. |
| `paymentRecipientName` | Yes | Both | Name of the payment recipient. |


### Recipient Address Fields

| Field Name | Required | Applies To |
|  --- | --- | --- |
| `envelopePostalAddressLine1` | Yes | Both |
| `envelopePostalAddressLine2` | No | Both |
| `envelopePostalMailStop` | No | Both |
| `envelopePostalCity` | Yes | Both |
| `envelopePostalState` | Yes | Both |
| `envelopePostalZip` | Yes | Both |


These fields determine where payment materials are delivered.

### Banking & Payor Fields

| Field Name | Required | Applies To |
|  --- | --- | --- |
| `payorAccountNumber` | Conditional | Both |
| `payorRoutingNumber` | Conditional | Both |
| `payorBankName` | Conditional | Both |
| `payorOnBehalfOf` | No | Both |
| `payorSignatureUrl` | Conditional | Both |
| `payor` | Conditional | Both |
| `payorLine2` | No | Both |
| `payorAddressLine1` | Conditional | Both |
| `payorAddressLine2` | No | Both |
| `payorCity` | Conditional | Both |
| `payorState` | Conditional | Both |
| `payorZip` | Conditional | Both |
| `payorPhone` | No | Both |


These fields are used to generate and fulfill payment artifacts.

### Print + Scan Fields

The following fields apply only to Print + Scan workflows.

| Field Name | Required | Description |
|  --- | --- | --- |
| `lockbox_id` | Conditional | Lockbox identifier used to improve routing accuracy. |
| `paymentAttachmentUrl` | Conditional | Reference to an associated payment document such as an EOP. |
| `envelopeEmailAddress` | No | Recipient email address. |
| `envelopeRecipientIdentifier` | No | Recipient reference identifier. |
| `payorBankTextsLine1` | Yes | Bank display text line 1. |
| `payorBankTextsLine2` | Yes | Bank display text line 2. |
| `payorBankTextsLine3` | Yes | Bank display text line 3. |
| `payorBankTextsLine4` | Yes | Bank display text line 4. |
| `payorPaymentAmountDue` | No | Optional payment amount due. |
| `payorInvoiceNumber` | No | Optional invoice number. |


### Field Notes

#### Conditional Fields

Conditional fields are required only when certain criteria are met.

Examples include:

- Banking and payor fields when a payment amount is provided.
- `paymentAttachmentUrl` when a Print + Scan payment is submitted without a payment amount.
- Print + Scan-specific fields when using the Print + Scan workflow.


#### Print + Mail vs. Print + Scan

Some fields apply only to Print + Scan workflows. When generating payment files, include only the fields required for the workflow being used.

#### Field Formatting Requirements

Additional requirements such as field length limits, date formats, attachment requirements, routing number validation, and document specifications are enforced during processing.

See [**File Definitions**](/products/deluxe-payment-network/developer-resources/file-definitions) for complete validation requirements.