Payment Field Definitions and Types

Below are the definitions for the fields associated with a Payment object. To determine which beneficiary fields are required to submit a payment in a given currency, please refer to the Payment Validator Resource, or consult your Convera representative.

For examples of payment payloads, refer to the Add Payment to Batch sample requests.

Payment Entity

API Data Model Reference

This document defines the core entities used by the Convera API Suite.
All tables below are expressed in Markdown pipe-table format and intentionally wrapped in code blocks for reuse in documentation pipelines, linting, and schema generation.

Payment Entity

Field Name	Description	Type	Format
`customerId`	Partner-defined ID used to uniquely identify a customer	Required	string(38)
`partnerReference`	Optional reference associated with a payment	Optional	string(50)
`paymentMethod`	Supported methods: Wire, ACH, SDA, Draft	Required	string(80)
`id`	Partner-defined payment ID, unique per customer	Required	string(38)
`status`	Convera-generated payment status	System	string(100)
`createdOn`	Timestamp when payment was accepted (UTC)	System	timestamp
`lastUpdatedOn`	Timestamp when payment was updated (UTC)	System	timestamp
`errorCode`	Convera-defined error code	System	string
`amount`	Amount expressed in minor currency units	Required	integer
`currencyCode`	ISO 4217 currency code (e.g. USD)	Required	string(3)
`settlementAmount`	Settlement amount expressed in minor units	System	integer
`settlementCurrencyCode`	Settlement currency code	Optional	string(3)
`isFixedAmountInSettlementCurrency`	Settlement currency amount fixed flag	Optional	boolean
`purposeOfPayment`	Payment description or purpose	Conditional	string(20)
`purposeOfPaymentCode`	Standard purpose of payment code	Conditional	string(15)
`instructionForBank`	Free-form instructions for bank	Optional	string(200)
`instructionCodeForBank`	Coded bank instruction	Optional	string(200)
`paymentReference`	Beneficiary message (IAT/CCD only)	Optional	string(140)
`IBAN`	Beneficiary IBAN (EU VOP only)	Conditional	string(34)
`uetr`	Unique End-to-End Transaction Reference	Optional	string(36)
`remittanceType`	Remittance type (IAT, CCD, CTX)	Optional	string(50)
`remittanceData.ref`	CTX remittance reference fields	Optional	string(140)
`chargeType`	BEN, SHA, or OUR	Optional	string(6)
`valueDate`	Scheduled credit date	Optional	YYYY-MM-DD
`releaseDate`	Scheduled payment release date	System	YYYY-MM-DD
`isDoddFrank`	Indicates Dodd-Frank treatment	Optional	boolean
`checkNumber`	Draft check number	System	string
`checkDate`	Date draft was issued	System	YYYY-MM-DD

Beneficiary Entity

Field Name	Description	Type	Format
`id`	Partner-defined beneficiary ID	Required	string(38)
`versionedOn`	Last update timestamp (UTC)	Required	string(50), timestamp
`email`	Beneficiary email address	Optional	string(80)
`type`	individual, sole proprietor, business	Required	string(20)
`taxId`	Tax identification number	Conditional	string(35)
`firstName`	First name for individuals	Conditional	string(70)
`middleName`	Middle name	Optional	string(70)
`lastName`	Last name for individuals	Conditional	string(70)
`phoneNumber`	Primary phone number	Optional	string(20)
`cellNumber`	Mobile phone number	Optional	string(20)
`dateOfBirth`	Date of birth	Optional	YYYY-MM-DD
`gender`	Gender (individual only)	Optional	string(10)
`occupation`	Beneficiary occupation	Optional	string(35)
`countryOfNationality`	ISO nationality country code	Optional	string(2)
`identificationDocumentType`	Identification document type	Optional	string(70)
`identificationDocumentNumber`	Identification document number	Optional	string(50)
`identificationDocumentCountry`	Issuing country	Optional	string(70)
`employerName`	Employer name	Optional	string(140)
`alias`	Alternate or alias name	Optional	string(140)
`authorizedUsers.user1-3`	Authorized business users	Optional	string(450)
`businessName`	Registered business name	Conditional	string(80)
`businessRegistrationNumber`	Business registration number	Optional	string(80)
`businessRegistrationCountry`	Registration country	Optional	string
`businessRegistrationStateProv`	Registration state or province	Optional	string(80)
`industry`	Industry classification	Optional	string(80)
`address.line1`	Street address line 1	Conditional	string(35)
`address.line2`	Street address line 2	Optional	string(35)
`address.line3`	Street address line 3	Optional	string(35)
`address.city`	City	Conditional	string(35)
`address.stateOrProv`	State or province	Conditional	string(35)
`address.zipOrPostal`	Postal code	Conditional	string(16)
`address.countryCode`	ISO 3166 country code	Required	string(2)

Bank Account Entity

Field Name	Description	Type	Format
`id`	Partner-defined bank account ID	Required	string(38)
`versionedOn`	Last update timestamp (UTC)	Required	string(50), timestamp
`accountNumber`	IBAN or account number	Required	string(34)
`accountType`	checking or savings	Conditional	string(20)
`bankName`	Bank name	Required	string(80)
`bankBranchName`	Bank branch name	Conditional	string(80)
`bankCode`	SWIFT or BIC	Conditional	string (8 or 11)
`bankBranchCode`	Routing or transit code	Conditional	string(50)
`address.line1`	Bank address line 1	Conditional	string(35)
`address.line2`	Bank address line 2	Optional	string(35)
`address.line3`	Bank address line 3	Optional	string(35)
`address.city`	City	Conditional	string(35)
`address.stateOrProv`	State or province	Conditional	string(35)
`address.zipOrPostal`	Postal code	Conditional	string(16)
`address.countryCode`	ISO 3166 country code	Required	string(2)
`intermediaryBank`	Intermediary bank object	Optional	object

Third-Party Remitter Entity

Field Name	Description	Type	Format
`id`	Partner-defined remitter ID	Required	string(35)
`versionedOn`	Last update timestamp (UTC)	Required	string(50), timestamp
`type`	Partnership, Corporation, Individual, Sole Proprietor	Required	string(50)
`businessName`	Name of remitting entity	Conditional	string(50)
`address.line1`	Street address line 1	Required	string(35)
`address.line2`	Street address line 2	Optional	string(35)
`address.city`	City	Required	string(35)
`address.stateOrProv`	State or province	Conditional	string(35)
`address.zipOrPostal`	Postal code	Conditional	string(16)
`address.countryCode`	ISO 3166 country code	Required	string(2)
`email`	Email address	Optional	string(80)
`phoneNumber`	Phone number	Optional	string(20)
`countryOfNationality`	ISO nationality country code	Optional	string(2)
`identificationType`	Identification type	Optional	string(50)
`identification`	Identification number	Optional	string(50)
`industry`	Industry	Optional	string(50)
`bankAccount.accountNumber`	Bank account number	Conditional	string(50)
`bankAccount.accountCurrency`	Bank account currency	Optional	string(3)
`bankAccount.bankCode`	SWIFT or BIC	Conditional	string (8 or 11)
`bankAccount.bankRoutingCode`	Routing or transit code	Conditional	string(50)

Originating FI Entity

Field Name	Description	Type	Format
`id`	Partner-defined originating FI ID	Required	string(38)
`versionedOn`	Last update timestamp (UTC)	Required	string(50), timestamp
`accountNumber`	IBAN or account number	Required	string(34)
`accountType`	checking or savings	Optional	string(20)
`bankName`	Originating FI name	Required	string(80)
`accountCurrency`	Account currency	Conditional	string(3)
`bankCode`	SWIFT or BIC	Conditional	string (8 or 11)
`bankRoutingCode`	Routing or transit code	Conditional	string(50)
`address.line1`	Street address line 1	Required	string(35)
`address.line2`	Street address line 2	Optional	string(35)
`address.line3`	Street address line 3	Optional	string(35)
`address.city`	City	Required	string(35)
`address.stateOrProv`	State or province	Required	string(35)
`address.zipOrPostal`	Postal code	Required	string(35)
`address.countryCode`	ISO 3166 country code	Required	string(2)