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)`
`instructionsForBank`	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`

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 `individual` `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`	Optional	`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`	Account currency. Required to process certain payments, such as payments into or out of Canada	Conditional	`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)`