Payment Fields

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

Field Name	Description	Type	Format
customerId	Partner-defined ID used to uniquely identify a customer within the Partner's system	Required	string(38)
partnerReference	Optional data that can be associated with a payment. Not sent along with payment (see paymentReference)	Optional	string(50)
paymentMethod	One of the supported payment methods: Wire, ACH, SDA, Draft	Required	string(80)
id	Partner-defined payment ID used to uniquely identify a payment. Should be unique across customer ID	Required	string(38)
status	Convera-generated payment status returned when retrieving payment information or webhooks	System	string(100)
createdOn	Convera-generated timestamp when a payment is accepted in UTC time zone	System	timestamp
lastUpdatedOn	Convera-generated timestamp when a payment is changed in UTC time zone	System	timestamp
errorCode	Convera-defined error code. See Error Codes for detailed list	System	string
amount	Payment amount expressed in cents dependent on minor currency unit. A value of "100" would equal $1.00 USD. See ISO 4217 standard for details on each currency's minor unit value. Note: the following currencies are currently 2 decimals: BHD, KWD, JOD, OMR, TND, TWD	Required	integer
currencyCode	Payment's currency code in 3-character ISO 4217 standard e.g. USD	Required	string(3)
settlementAmount	Payment amount expressed in cents dependent on minor currency unit. A value of "100" would equal $1.00 USD. See ISO 4217 standard for details on each currency's minor unit value.	System	integer
settlementCurrencyCode	Currency code of a settlement used to fund this payment in 3-character ISO 4217 standard	Optional	string(3)
isFixedAmountInSettlementCurrency	Indicates if payment was submitted with settlement amount specified instead of trade currency. Converts amount field to be in settlement currency value	Optional	string, boolean
purposeOfPayment	Purpose of payment submitted by the customer. Some currencies require a standardized list of codes in addition to a description. Sample descriptions: Avertising Fees, Expense Reimbursement, Financial, Legal, Medical Reimbursement, Other, Payroll, Processing, Trade Related, Transaction between banks, Transportation Costs, Travel Related, VAT, VAT Exempt, VO Code (VOxxxxx)	Conditional	string(20)
purposeOfPaymentCode	Purpose of payment code submitted by the customer. Several currencies require a purpose of payment code. Refer to the Convera Payment Formatting Guide for a list of currencies that require POP Codes	Conditional	string(15)
instructionForBank	Instructions for bank usually provided by a beneficiary	Optional	string(200)
instructionCodeForBank	Instructions for bank usually provided by a beneficiary. Potential values: CHQB, HOLD, PHOB, TELB, URGP, OTHR. If other values included or blank, OTHR will be used	Optional	string(200)
paymentReference	For IAT and CCD payments, a message to the beneficiary about the payment. The recommended length of this field is 140 characters. If reference is too long, it may arrive incomplete	Optional	string(140)
uetr	For incoming Swift payments, the Unique End-to-end Transaction Reference will be displayed.	Optional	string(36)
remittanceType	Remittance type value: IAT, CCD, or CTX. Applicable for payments to business type beneficiaries. Determines which reference fields are passed with payment. Note: IAT requires full beneficiary address.	Optional	string(50)
remittanceData.ref	For CTX payments only. Remittance data to hold remittance details - supporting up to 9999 ref fields	Optional	string(140)
chargeType	Selectable charge type with options: 1. BEN - Beneficiary responsible for charges 2. SHA - Charges shared with customer and beneficiary 3. OUR - Convera responsible for charges	Optional	string(6)
valueDate	Scheduled date for credit to beneficiary bank account	Optional	string(20), YYYY-MM-DD
releaseDate	Scheduled date for payment release if valueDate is specified. Populated after successful sanction scan.	System	string(20), YYYY-MM-DD
isDoddFrank	Flag to force treatment of payment as Dodd-Frank. See Dodd-Frank Payments for more information	Optional	string, boolean
checkNumber	Check number for Draft payments	System	string
checkDate	Date draft was issued	System	string, YYYY-MM-DD

Beneficiary Entity

Field Name	Description	Type	Format
id	Partner-defined ID to uniquely identify a beneficiary in the Partner system	Required	string(38)
versionedOn	Partner provided timestamp field to indicate last update to beneficiary in UTC	Required	string(50),timestamp
email	Beneficiary email address if provided	Optional	string(80)
type	One of the supported beneficiary types: 1. individual 2. sole proprietor 3. business	Required	string(20)
taxId	Required for payments in certain currencies	Conditional	string(35)
firstName	Required for individual beneficiaryType. Sole proprietor beneficiaryType requires full name (firstName and lastName) or businessName	Conditional	string(70) for combination of firstName, middleName, lastName
middleName	Optional for individual type	Optional	string(70) for combination of firstName, middleName, lastName
lastName	Required for individual beneficiaryType. Sole proprietor beneficiaryType requires full name (firstName and lastName) or businessName	Conditional	string(70) for combination of firstName, middleName, lastName
phoneNumber	Main phone number for a beneficiary (home or business)	Optional	string(20)
cellNumber	Mobile number for a beneficiary	Optional	string(20)
dateOfBirth	Beneficiary's date of birth	Optional	string(20), YYYY-MM-DD
gender	Beneficiary's gender for individual type	Optional	string(10)
occupation	Occupation of the beneficiary	Optional	string(35)
countryOfNationality	Nationality of the beneficiary, 2-character ISO country code	Optional	string(2)
identificationDocumentType	Business identification document type e.g. passport	Optional	string(70)
identificationDocumentNumber	Business identification document number	Optional	string(50)
identificationDocumentCountry	Business identification document country of origin	Optional	string(70)
employerName	Employer of beneficiary	Optional	string(140)
alias	Alias of beneficiary or alternative name	Optional	string(140)
authorizedUsers.user1 authorizedUsers.user2 authorizedUsers.user3	Users authorized to make transactions on a business's behalf	Optional	string(450)
businessName	Required for business beneficiaryType. Sole proprietor beneficiaryType requires full name (firstName and lastName) or businessName	Conditional	string(80)
businessRegistrationNumber	Country-specific registration number	Optional	string(80)
businessRegistrationCountry	Country where beneficiary business is registered	Optional	string
businessRegistrationStateProv	Country's province or state where beneficiary business is registered	Optional	string(80)
industry	Beneficiary business industry type	Optional	string(80)
address.line1	Street address line 1. Required if "full address" is mandated to process currency. For drafts, combination of line1 and line2 cannot be more than 50 characters.	Conditional	string(35)
address.line2	Street address line 2	Optional	string(35)
address.line3	Street address line 3	Optional	string(35)
address.city	City name. Mandatory if "full address" is required to process currency	Conditional	string(35)
address.stateOrProv	State or province. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CA	Conditional	string(35)
address.zipOrPostal	Zip or postal code. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CA	Conditional	string(16)
address.countryCode	Country code of the beneficiary location in 2-character ISO 3166 format e.g. GB	Required	string(2)

Bank Account Entity

Field Name	Description	Type	Format
id	Partner-defined ID to uniquely identify a beneficiary bank in the Partner system	Required	string(38)
versionedOn	Partner provided timestamp field to indicate last update to beneficiary bank in UTC	Required	string(50),timestamp
accountNumber	IBAN or account number	Required	string(34)
accountType	One of the supported types: checking or savings	Conditional	string(20)
bankName	Name of beneficiary's bank	Required	string(80)
bankBranchName	Beneficiary bank branch name. Required to process certain currencies	Conditional	string(80)
bankCode	Bank's SWIFT code or BIC. Typically required to process wire payments, but varies with currency	Conditional	string, valid SWIFT codes only <8 or 11 characters alphanumeric>
bankBranchCode	Bank routing or transit code. Typically required to process ACH payments, but varies with currency	Conditional	string(50)
address.line1	Street address line 1. Required if "full bank address" is mandated to process currency.	Conditional	string(35)
address.line2	Street address line 2	Optional	string(35)
address.line3	Street address line 3	Optional	string(35)
address.city	City name. Required if "full bank address" is mandated to process currency.	Conditional	string(35)
address.stateOrProv	State or province. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CA	Conditional	string(35)
address.zipOrPostal	Zip or postal code. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CA	Conditional	string(16)
address.countryCode	Country code of the beneficiary bank in 2-character ISO 3166 format e.g. GB	Required	string(2)
intermediaryBank object	Intermediary bank object, optional for all payments. See Payment Resource for object structure	Optional	string

Third-Party Remitter Entity

The Convera API Suite supports payments for third-party remitters if Partner is licensed to process them. Access to these fields is configured at the Partner level and can be turned on if applicable.

Field Name	Description	Type	Format
id	Partner-defined ID to uniquely identify a third-party remitter in the Partner system	Required	string(35)
versionedOn	Partner provided timestamp field to indicate last update to third-party remitter in UTC	Required	string(50),timestamp
type	One of the third-party remitter supported types: 1. Partnership 2. Corporation 3. Individual 4. Sole Proprietor	Required	string(50)
businessName	Name of remitting business or individual	Conditional	string(50)
address.line1	Street address line 1	Required	string(35)
address.line2	Street address line 2	Optional	string(35)
address.city	City name	Required	string(35)
address.stateOrProv	State or province	Conditional	string(35)
address.zipOrPostal	Zip or postal code	Conditional	string(16)
address.countryCode	Country code of the remitter in 2-character ISO 3166 format e.g. GB	Required	string(2)
email	Third-party remitter email address	Optional	string(80)
phoneNumber	Third-party remitter phone number	Optional	string(20)
countryOfNationality	Nationality of the beneficiary, 2-character ISO country code	Optional	string(2)
identificationType	Identification type, such as a business registration	Optional	string(50)
identification	Identification number, such as a business registration number	Optional	string(50)
industry	Industry of third-party remitter	Optional	string(50)
bankAccount.accountNumber	Account number of third-party remitter. Required to process certain payments, such as payments into or out of Canada	Conditional	string(50)
bankAccount.accountCurrency	Currency of the bank account for the remitter	Optional	string(3)
bankAccount.bankCode	Bank SWIFT code or BIC. Required to process certain payments, such as payments into or out of Canada	Conditional	string, valid SWIFT codes only <8 or 11 characters alphanumeric>
bankAccount.bankRoutingCode	Bank routing or transit code. Required to process certain payments, such as payments into or out of Canada	Conditional	string(50)

Originating FI Entity

For Partners that are licensed to offer the API solution to their FI customers, we offer the ability to facilitate these payments through API. Contact the Convera onboarding team for more information.

Field Name	Description	Type	Format
id	Partner-defined ID used to uniquely identify an Originating FI within the partner system	Required	string(38)
versionedOn	Partner provided timestamp field to indicate last update to originating FI in UTC	Required	string(50),timestamp
accountNumber	IBAN or account number	Required	string(34)
accountType	One of the supported types: checking or savings	Optional	string(20)
bankName	Name of originating FI	Required	string(80)
accountCurrency	Currency of account	Conditional	string(3)
bankCode	SWIFT code or BIC for originating FI. Either SWIFT or routing code is required.	Conditional	string, valid SWIFT codes only <8 or 11 characters alphanumeric>
bankRoutingCode	Routing or transit code for originating FI. Either SWIFT or routing code is required.	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 name	Required	string(35)
address.stateOrProv	State or province	Required	string(35)
address.zipOrPostal	Zip or postal code	Required	string(35)
address.countryCode	Country code of the originating FI in 2-character ISO 3166 format e.g. GB	Required	string(2)