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

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

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.

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, <code, description>

instructionsForBank

Instructions for bank usually provided by a beneficiary

Optional

string

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

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

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

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

valueDate

Scheduled date for credit to beneficiary bank account

Optional

string, YYYY-MM-DD

releaseDate

Scheduled date for payment release if valueDate is specified. Populated after successful sanction scan.

System

string, 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

timestamp

email

Beneficiary email address if provided

Optional

string

type

One of the supported beneficiary types:

  1. individual
  2. sole proprietor
  3. business

Required

string

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

cellNumber

Mobile number for a beneficiary

Optional

string

dateOfBirth

Beneficiary's date of birth

Optional

string, YYYY-MM-DD

gender

Beneficiary's gender for individual type

Optional

string

occupation

Occupation of the beneficiary

Optional

string(35)

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

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

industry

Beneficiary business industry type

Optional

string

address.line1

Street address line 1. Required if "full address" is mandated to process currency.

Conditional

string(35)

address.line2

Street address line 2

Optional

string

address.line3

Street address line 3

Optional

string

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

timestamp

accountNumber

IBAN or account number

Required

string(34)

accountType

One of the supported types: checking or savings

Optional

string

bankName

Name of beneficiary's bank

Required

string(80)

bankBranchName

Beneficiary bank branch name. Required to process certain currencies

Conditional

string

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

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

address.line3

Street address line 3

Optional

string

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

timestamp

type

One of the third-party remitter supported types:

  1. Partnership
  2. Corporation
  3. Individual
  4. Sole Proprietor

Required

businessName

Third-party remitter business name

Conditional

string

address.line1

Street address line 1

Required

string

address.line2

Street address line 2

Optional

string

address.city

City name

Conditional

string(35)

address.stateOrProv

State or province

Required

string(35)

address.zipOrPostal

Zip or postal code

Required

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

phoneNumber

Third-party remitter phone number

Optional

string

identificationType

Identification type, such as a business registration

Optional

string

identification

Identification number, such as a business registration number

Optional

string

industry

Industry of third-party remitter

Optional

string

bankAccount.accountNumber

Account number of third-party remitter. Required to process certain payments, such as payments into or out of Canada

Conditional

string

bankAccount.accountCurrency

Account currency. Required to process certain payments, such as payments into or out of Canada

Conditional

string

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

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

versionedOn

Partner provided timestamp field to indicate last update to originating FI in UTC

Required

timestamp

accountNumber

IBAN or account number

Required

string(34)

accountType

One of the supported types: checking or savings

Optional

string

bankName

Name of originating FI

Required

string(140)

accountCurrency

Currency of account

Conditional

string

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

address.line1

Street address line 1

Required

string(35)

address.line2

Street address line 2

Optional

string

address.line3

Street address line 3

Optional

string

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)