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(70)

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

Convera Logo

© 2022 All Rights Reserved