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 NameDescriptionTypeFormat
customerIdPartner-defined ID used to uniquely identify a customer within the Partner's systemRequiredstring(38)
partnerReferenceOptional data that can be associated with a payment. Not sent along with payment (see paymentReference)Optionalstring(50)
paymentMethodOne of the supported payment methods: Wire, ACH, SDA, DraftRequiredstring(80)
idPartner-defined payment ID used to uniquely identify a payment. Should be unique across customer IDRequiredstring(38)
statusConvera-generated payment status returned when retrieving payment information or webhooksSystemstring(100)
createdOnConvera-generated timestamp when a payment is accepted in UTC time zoneSystemtimestamp
lastUpdatedOnConvera-generated timestamp when a payment is changed in UTC time zoneSystemtimestamp
errorCodeConvera-defined error code. See Error Codes for detailed listSystemstring
amountPayment 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, TWDRequiredinteger
currencyCodePayment's currency code in 3-character ISO 4217 standard e.g. USDRequiredstring(3)
settlementAmountPayment 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.Systeminteger
settlementCurrencyCodeCurrency code of a settlement used to fund this payment in 3-character ISO 4217 standardOptionalstring(3)
isFixedAmountInSettlementCurrencyIndicates if payment was submitted with settlement amount specified instead of trade currency. Converts amount field to be in settlement currency valueOptionalstring, boolean
purposeOfPaymentPurpose 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)
Conditionalstring(20)
purposeOfPaymentCodePurpose 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 CodesConditionalstring(15)
instructionForBankInstructions for bank usually provided by a beneficiaryOptionalstring(200)
instructionCodeForBankInstructions for bank usually provided by a beneficiary. Potential values: CHQB, HOLD, PHOB, TELB, URGP, OTHR. If other values included or blank, OTHR will be usedOptionalstring(200)
paymentReferenceFor 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 incompleteOptionalstring(140)
uetrFor incoming Swift payments, the Unique End-to-end Transaction Reference will be displayed.Optionalstring(36)
remittanceTypeRemittance 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.Optionalstring(50)
remittanceData.refFor CTX payments only. Remittance data to hold remittance details - supporting up to 9999 ref fieldsOptionalstring(140)
chargeTypeSelectable charge type with options:

1. BEN - Beneficiary responsible for charges
2. SHA - Charges shared with customer and beneficiary
3. OUR - Convera responsible for charges
Optionalstring(6)
valueDateScheduled date for credit to beneficiary bank accountOptionalstring(20), YYYY-MM-DD
releaseDateScheduled date for payment release if valueDate is specified. Populated after successful sanction scan.Systemstring(20), YYYY-MM-DD
isDoddFrankFlag to force treatment of payment as Dodd-Frank. See Dodd-Frank Payments for more informationOptionalstring, boolean

Beneficiary Entity

Field NameDescriptionTypeFormat
idPartner-defined ID to uniquely identify a beneficiary in the Partner systemRequiredstring(38)
versionedOnPartner provided timestamp field to indicate last update to beneficiary in UTCRequiredstring(50),timestamp
emailBeneficiary email address if providedOptionalstring(80)
typeOne of the supported beneficiary types:

1. individual
2. sole proprietor
3. business
Requiredstring(20)
taxIdRequired for payments in certain currenciesConditionalstring(35)
firstNameRequired for individual
beneficiaryType. Sole proprietor beneficiaryType requires full name (firstName and lastName) or businessName
Conditionalstring(70) for combination of firstName, middleName, lastName
middleNameOptional for individual typeOptionalstring(70) for combination of firstName, middleName, lastName
lastNameRequired for individual
beneficiaryType. Sole proprietor beneficiaryType requires full name (firstName and lastName) or businessName
Conditionalstring(70) for combination of firstName, middleName, lastName
phoneNumberMain phone number for a beneficiary (home or business)Optionalstring(20)
cellNumberMobile number for a beneficiaryOptionalstring(20)
dateOfBirthBeneficiary's date of birthOptionalstring(20), YYYY-MM-DD
genderBeneficiary's gender for individual typeOptionalstring(10)
occupationOccupation of the beneficiaryOptionalstring(35)
countryOfNationalityNationality of the beneficiary, 2-character ISO country codeOptionalstring(2)
identificationDocumentTypeBusiness identification document type e.g. passportOptionalstring(70)
identificationDocumentNumberBusiness identification document numberOptionalstring(50)
identificationDocumentCountryBusiness identification document country of originOptionalstring(70)
employerNameEmployer of beneficiaryOptionalstring(140)
aliasAlias of beneficiary or alternative nameOptionalstring(140)
authorizedUsers.user1
authorizedUsers.user2
authorizedUsers.user3
Users authorized to make transactions on a business's behalfOptionalstring(450)
businessNameRequired for individual
beneficiaryType. Sole proprietor beneficiaryType requires full name (firstName and lastName) or businessName
Conditionalstring(80)
businessRegistrationNumberCountry-specific registration numberOptionalstring(80)
businessRegistrationCountryCountry where beneficiary business is registeredOptionalstring
businessRegistrationStateProvCountry's province or state where beneficiary business is registeredOptionalstring(80)
industryBeneficiary business industry typeOptionalstring(80)
address.line1Street 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.Conditionalstring(35)
address.line2Street address line 2Optionalstring(35)
address.line3Street address line 3Optionalstring(35)
address.cityCity name. Mandatory if "full address" is required to process currencyConditionalstring(35)
address.stateOrProvState or province. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CAConditionalstring(35)
address.zipOrPostalZip or postal code. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CAConditionalstring(16)
address.countryCodeCountry code of the beneficiary location in 2-character ISO 3166 format e.g. GBRequiredstring(2)

Bank Account Entity

Field NameDescriptionTypeFormat
idPartner-defined ID to uniquely identify a beneficiary bank in the Partner systemRequiredstring(38)
versionedOnPartner provided timestamp field to indicate last update to beneficiary bank in UTCRequiredstring(50),timestamp
accountNumberIBAN or account numberRequiredstring(34)
accountTypeOne of the supported types: checking or savingsConditionalstring(20)
bankNameName of beneficiary's bankRequiredstring(80)
bankBranchNameBeneficiary bank branch name. Required to process certain currenciesConditionalstring(80)
bankCodeBank's SWIFT code or BIC. Typically required to process wire payments, but varies with currencyConditionalstring, valid SWIFT codes only <8 or 11 characters alphanumeric>
bankBranchCodeBank routing or transit code. Typically required to process ACH payments, but varies with currencyConditionalstring(50)
address.line1Street address line 1. Required if "full bank address" is mandated to process currency.Conditionalstring(35)
address.line2Street address line 2Optionalstring(35)
address.line3Street address line 3Optionalstring(35)
address.cityCity name. Required if "full bank address" is mandated to process currency.Conditionalstring(35)
address.stateOrProvState or province. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CAConditionalstring(35)
address.zipOrPostalZip or postal code. Mandatory to meet "full address" requirements for certain countries such as US, GB, and CAConditionalstring(16)
address.countryCodeCountry code of the beneficiary bank in 2-character ISO 3166 format e.g. GBRequiredstring(2)
intermediaryBank objectIntermediary bank object, optional for all payments. See Payment Resource for object structureOptionalstring

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 NameDescriptionTypeFormat
idPartner-defined ID to uniquely identify a third-party remitter in the Partner systemRequiredstring(35)
versionedOnPartner provided timestamp field to indicate last update to third-party remitter in UTCRequiredstring(50),timestamp
typeOne of the third-party remitter supported types:

1. Partnership
2. Corporation
3. Individual
4. Sole Proprietor
Requiredstring(50)
businessNameName of remitting business or individualConditionalstring(50)
address.line1Street address line 1Requiredstring(35)
address.line2Street address line 2Optionalstring(35)
address.cityCity nameRequiredstring(35)
address.stateOrProvState or provinceConditionalstring(35)
address.zipOrPostalZip or postal codeConditionalstring(16)
address.countryCodeCountry code of the remitter in 2-character ISO 3166 format e.g. GBRequiredstring(2)
emailThird-party remitter email addressOptionalstring(80)
phoneNumberThird-party remitter phone numberOptionalstring(20)
countryOfNationalityNationality of the beneficiary, 2-character ISO country codeOptionalstring(2)
identificationTypeIdentification type, such as a business registrationOptionalstring(50)
identificationIdentification number, such as a business registration numberOptionalstring(50)
industryIndustry of third-party remitterOptionalstring(50)
bankAccount.accountNumberAccount number of third-party remitter. Required to process certain payments, such as payments into or out of CanadaConditionalstring(50)
bankAccount.accountCurrencyAccount currency. Required to process certain payments, such as payments into or out of CanadaConditionalstring(3)
bankAccount.bankCodeBank SWIFT code or BIC. Required to process certain payments, such as payments into or out of CanadaConditionalstring, valid SWIFT codes only <8 or 11 characters alphanumeric>
bankAccount.bankRoutingCodeBank routing or transit code. Required to process certain payments, such as payments into or out of CanadaConditionalstring(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 NameDescriptionTypeFormat
idPartner-defined ID used to uniquely identify an Originating FI within the partner systemRequiredstring(38)
versionedOnPartner provided timestamp field to indicate last update to originating FI in UTCRequiredstring(50),timestamp
accountNumberIBAN or account numberRequiredstring(34)
accountTypeOne of the supported types: checking or savingsOptionalstring(20)
bankNameName of originating FIRequiredstring(80)
accountCurrencyCurrency of accountConditionalstring(3)
bankCodeSWIFT code or BIC for originating FI. Either SWIFT or routing code is required.Conditionalstring, valid SWIFT codes only <8 or 11 characters alphanumeric>
bankRoutingCodeRouting or transit code for originating FI. Either SWIFT or routing code is required.Conditionalstring(50)
address.line1Street address line 1Requiredstring(35)
address.line2Street address line 2Optionalstring(35)
address.line3Street address line 3Optionalstring(35)
address.cityCity nameRequiredstring(35)
address.stateOrProvState or provinceRequiredstring(35)
address.zipOrPostalZip or postal codeRequiredstring(35)
address.countryCodeCountry code of the originating FI in 2-character ISO 3166 format e.g. GBRequiredstring(2)