Overview

A user can schedule a transaction to pull or push funds across Ahrvo. The Transaction API supports the following fund-movement scenarios:

• Pull funds from an External Account (bank account or card) into a Ahrvo Account
• Push funds from a Ahrvo Account to an External Account (bank account via ACH/Wire, or mailing address via Check)
• Book transfers between any two Ahrvo Accounts
• Refund a transaction that originally pulled funds from an External Account (bank account or card)
• Share Virtual Card to make payments from a Ahrvo Account
• Push funds from a Ahrvo Account to an International External Account via Wire

Third-party bank, card, or address details can be either:

• Pre-existing – already stored in the system as External Account, Card, or Mailing Address entities.
• One-time – passed inline for a single use; not stored.

---

11.2 Attributes

11.2.1 CARD Transaction Attributes

Field	Type	Mandatory / Optional	Can be updated?	Description
resourceName	Enum	—	No	Name of the resource. Always transaction.
url	Object	—	No	System-generated endpoint used to fetch the transaction.
id	Integer	—	No	Unique identifier assigned by Ahrvo.
externalId	String (max 45)	Optional	No	Reference ID assigned by program manager.
method	String	Mandatory	No	Method of payment. For this table the value is CARD.
type	String	Optional	No	Type of transaction. Possible Values: - REGULAR: Initiated by customer to make payments. - REFUND: Initiated by customer against a collect transaction. - REVERSAL: Initiated by Priority team or customer request against a Regular ACH transaction.
isAutoCapture	Boolean	Optional	No	Auto-capture flag. Possible Values: - true: Create a direct SALE transaction. - false: Create an authorization transaction.
transactionClass	Enum	—	No	Class displayed in Retrieve response. Possible Values: - SYSTEM_FEE: Transaction to charge fees. - COLLECT: Move funds from external account to Ahrvo account.
purpose	String (max 128)	Optional	No	Purpose of the transaction. All characters allowed.
amount	Big Decimal	Optional	No	Dollar value of the transaction. Must be > 0. Optional when method = CARD; user is recommended to pass amountDetails.originalAmount.
amountDetails	Object	Optional	No	Additional amount details.
amountDetails.tipAmount	Big Decimal	Optional	No	Tip amount.
amountDetails.surchargeAmount	Big Decimal	Conditional	No	Surcharge amount. Mandatory for surcharge-enabled merchants (configuration isSurchargeEnabled = TRUE).
amountDetails.originalAmount	Big Decimal	Optional	No	Original amount before tip / surcharge.
source	Object	Mandatory	No	Account or external account to be debited. Note: source need not be passed if type = REFUND.
source.card	Object	—	No	Card-specific details.
source.card.form	String	Optional	No	Card form/type. Possible Values: VIRTUAL, PLASTIC, MOBILE, TABLET
source.card.cardNumber	String	Mandatory	No	13–17-digit card number.
source.card.expiryMonth	Date	Optional	No	Month of expiry (01–12).
source.card.expiryYear	Date	Optional	No	4-digit year; cannot be in the past.
source.card.cvv	Integer	Optional	No	3–4-digit CVV.
source.card.accountType	String	Optional	No	Account type. Possible Values: Unspecified, Savings, Checking, CreditCard, Universal, CashBenefits, FoodStamps
source.card.eciIndicator	String	Optional	No	ECI indicator for CNP transactions (3-D Secure).
source.card.brand	String	Optional	No	Card brand returned in Retrieve response. Possible Values: MasterCard, Visa, Discover, AmericanExpress
source.card.avs	Object	—	No	Address Verification Service details.
source.card.avs.zip	String	Optional	No	5- or 9-digit US ZIP or Canadian postal code.
source.card.avs.addressLine1	String	Optional	No	Street address.
source.card.avs.firstName	String	Optional	No	First name.
source.card.avs.middleName	String	Optional	No	Middle name.
source.card.avs.lastName	String	Optional	No	Last name.
source.card.avs.phone	String	Optional	No	Phone number.
source.card.avs.email	String	Optional	No	Email address.
source.card.cardHolder	Object	—	No	Card-holder information.
source.card.cardHolder.name	String	Optional	No	Full name.
source.card.cardHolder.firstName	String	Optional	No	First name.
source.card.cardHolder.lastName	String	Optional	No	Last name.
source.card.cardHolder.ipAddress	String	Optional	No	IP address (max 15 chars).
source.card.cardHolder.hostName	String	Optional	No	Host name (max 60 chars).
source.card.cardHolder.browserType	String	Optional	No	Browser type (max 60 chars).
source.card.cardHolder.phone	String	Optional	No	Phone number.
source.card.cardHolder.email	String	Optional	No	Email address.
source.card.cardHolder.number	String	Optional	No	Card-holder number.
source.card.billingAddress	Object	Optional	No	Billing address details.
source.card.billingAddress.addressLine1	String	Optional	No	Line 1.
source.card.billingAddress.city	String	Optional	No	City.
source.card.billingAddress.state	String	Optional	No	State.
source.card.billingAddress.zip	String	Optional	No	5- or 9-digit US / CND code.
source.card.billingAddress.country	String	Optional	No	Country.
source.card.token	String	Optional	No	Card token.
source.contact	Object	Mandatory for customer’s Contact inside Ahrvo	No	Required to collect money from a Contact.
source.contact.id	Long	Mandatory	No	Ahrvo Contact ID.
source.card.id	Long	Mandatory when using stored Ahrvo card	No	Unique card ID.
processingDetail	Object	—	No	Processing details.
processingDetail.ecom	Boolean	Optional	No	true = e-commerce, false = card-present.
processingDetail.moto	Boolean	Optional	No	Mail/Phone order flag.
processingDetail.statementDescriptor	String	Optional	No	Extra descriptor.
processingDetail.businessApplication	String	Optional	No	Business application.
processingDetail.device	Object	—	No	Device information.
processingDetail.device.inputCapability	String	Optional	No	See full list under Device Input Capability.
processingDetail.device.posId	String	Optional	No	POS ID.
processingDetail.device.type	String	Optional	No	Device type.
processingDetail.device.accountCaptureMethod	String	Optional	No	UNKNOWN, MANUAL, SWIPE, CHIP, CONTACTLESS_SWIPE, CONTACTLESS_CHIP, FALLBACK, CONTACTLESS_MOBILE, ON_FILE
processingDetail.device.cardPresent	Boolean	Optional	No	Card present flag.
processingDetail.device.cardholderPresence	String	Optional	No	UNKNOWN, PRESENT, NOT_PRESENT, MAIL, PHONE, STANDING, RECURRING, ECOM
processingDetail.device.attendance	String	Optional	No	UNKNOWN, ATTENDED, HOME_PC, VOICE_ARU, RECURRING, SERVER, UNATTENDED
processingDetail.device.location	String	Optional	No	UNKNOWN, SERVER, ON_PREMISE, OFF_PREMISE, HOME_PC, VOICE_ARU, ON_PREMISE_HOME_PC, RECURRING
processingDetail.device.catLevel	String	Optional	No	UNKNOWN, NONE, ECOM, UNATTENDED
processingDetail.device.transactionSecurity	String	Optional	No	Transaction security.
processingDetail.device.transactionStatus	String	Optional	No	NORMAL, FRAUD_SUSPECTED, ID_VERIFIED, BIOMETRICS_VERIFIED
processingDetail.device.partialApprovalSupport	String	Optional	No	NOT_SUPPORTED, SUPPORTED, MERCHANDISE_ONLY, CASH_ONLY, EXCLUSIVE
processingDetail.merchant	Object	Mandatory	No	Merchant info.
processingDetail.merchant.id	Long	Mandatory	No	Merchant unique ID.
processingDetail.terminal.id	Long	Mandatory for card-present	No	Terminal ID.
processingDetail.order	Object	—	No	Order / invoice details (discount, tax, shipment, line items, lodging).
processingDetail.location	Object	Optional	Yes	Link a location to transaction.
processingDetail.location.id	Long	—	Yes	Location ID.
processingDetail.batch.id	Long	—	No	Batch ID.
funding	Object	Optional	No	Additional funding tags.
funding.tags[]	Array	Optional	No	{ "key":"type", "value":"Trust" }
reason	String	Optional (Refund)	No	ON_CUSTOMER_REQUEST, OTHERS (if OTHERS, comment is mandatory).
pendingCaptureAmount	Integer	—	No	Pending capture for an AUTH.
isFinalCapture	Boolean	—	No	If true, remaining auth is voided.

11.2.1 CARD Transaction Attributes (continued)

Field	Type	Mandatory / Optional	Can be updated?	Description
processingDetail.order.invoice	Object	Optional	No	Collection of invoices.
processingDetail.order.invoice.number	String ≤ 25	Optional	No	Invoice number.
processingDetail.order.invoice.discountRate	Number	Optional	No	Discount rate.
processingDetail.order.invoice.discountAmount	Number	Optional	No	Discount amount.
processingDetail.order.invoice.taxAmount	Number	Optional	No	Tax amount.
processingDetail.order.invoice.taxRate	Number	Optional	No	Tax rate.
processingDetail.order.invoice.taxExempt	Boolean	Optional	No	true or false.
processingDetail.order.invoice.shipmentDetail	Object	Optional	No	Shipment details.
processingDetail.order.invoice.shipmentDetail.freightTaxRate	Number	Optional	No	Freight-tax rate.
processingDetail.order.invoice.shipmentDetail.destinationPostalCode	String	Optional	No	5- or 9-digit US / CND code.
processingDetail.order.invoice.shipmentDetail.sourcePostalCode	String	Optional	No	5- or 9-digit US / CND code.
processingDetail.order.invoice.shipmentDetail.dutyAmount	Number	Optional	No	Duty amount.
processingDetail.order.invoice.shipmentDetail.freightAmount	Number	Optional	No	Freight amount.
processingDetail.order.invoice.shipmentDetail.freightTaxAmount	Number	Optional	No	Freight-tax amount.
processingDetail.order.invoice.shipmentDetail.address	Object	Optional	No	Shipment address.
processingDetail.order.invoice.lineItem	Object	Optional	No	Line-item details.
processingDetail.order.invoice.lineItem.commodityCode	String ≤ 16	Optional	No	Commodity code.
processingDetail.order.invoice.lineItem.description	String ≤ 68	Optional	No	Product description.
processingDetail.order.invoice.lineItem.productCode	String ≤ 20	Optional	No	Product code.
processingDetail.order.invoice.lineItem.unitOfMeasure	String ≤ 12	Optional	No	Unit of measure.
processingDetail.order.invoice.lineItem.quantity	Number	Optional	No	Quantity.
processingDetail.order.invoice.lineItem.unitCost	Number	Optional	No	Unit cost.
processingDetail.order.invoice.lineItem.discountRate	Number	Optional	No	Discount %.
processingDetail.order.invoice.lineItem.discountAmount	Number	Optional	No	Discount amount.
processingDetail.order.invoice.lineItem.taxRate	Number	Optional	No	Tax %.
processingDetail.order.invoice.lineItem.taxAmount	Number	Optional	No	Tax amount.
processingDetail.order.invoice.lineItem.dutyAmount	Number	Optional	No	Duty amount.
processingDetail.order.invoice.lineItem.extendedAmount	Number	Optional	No	Extended amount.
processingDetail.order.lodging	Object	Optional	No	Lodging details.
processingDetail.order.lodging.purchaseId	String	Optional	No	Purchase ID / folio.
processingDetail.order.lodging.rooms	Object	Optional	No	Room data (check-in, amount, duration).
pendingCaptureAmount	Integer	—	No	Remaining authorization amount.
isFinalCapture	Boolean	—	No	true → void remaining auth.

---

11.2.2 ACH Transaction Attributes

Field	Type	Mandatory / Optional	Can be updated?	Description
resourceName	Enum	—	No	Always transaction.
url	Object	—	No	Endpoint for this transaction.
id	Integer	—	No	Ahrvo‐assigned ID.
externalId	String ≤ 45	Optional	No	Program reference.
method	String	Mandatory	No	ACH.
type	String	Optional	No	REGULAR | REFUND.
source	Object	Mandatory	No	Debit account or external account. Not required if type = REFUND.
source.account.id	Long	Mandatory if debiting Ahrvo account	No	Ahrvo Account ID.
source.externalAccount.id	Long	Mandatory if debiting stored External Account	No	External Account ID.
source.externalAccount.holderName	String	Mandatory for one-time	No	Bank-record holder name.
source.externalAccount.accountNumber	Long	Mandatory for one-time	No	Bank account number.
source.externalAccount.routingNumber	Long	Mandatory for one-time	No	Routing number (digits).
source.externalAccount.type	Enum	Optional	No	SAVINGS | CHECKING.
source.externalAccount.holderType	Enum	Optional	No	CONSUMER | CORPORATE.
source.contact.id	Long	Mandatory if debiting a Contact	No	Ahrvo Contact ID.
destination	Object	Mandatory	No	Credit account or external account. Not required if type = REFUND.
destination.account.id	Long	Mandatory when crediting Ahrvo account	No	Ahrvo Account ID.
destination.externalAccount.id	Long	Mandatory when crediting stored External Account	No	External Account ID.
processingDetail	Object	Conditional	Yes	ACH processing info.
processingDetail.processingMode	Enum	Conditional	Yes	SAME_DAY | FORWARD (default).
processingDetail.companyName	String	Conditional	Yes	NACHA label; defaulted if absent.
processingDetail.companyDescription	String	Conditional	Yes	NACHA description.
processingDetail.authType	Enum	Conditional	Yes	WRITTEN, PHONE, ONLINE; mandatory if PM config = none.
processingDetail.addenda	String ≤ 80	Conditional	Yes	ACH addenda.
linkedDocument	Object	Optional	Yes	Authorization docs.
linkedDocument.id	String	—	No	Document ID (Retrieve).
linkedDocument.purpose	Enum	Conditional	Yes	AUTHORIZATION, CHECK_DEPOSIT, ESCALATION_IDENTIFICATION_PROOF.
linkedDocument.document	Object	Conditional	Yes	Document details.
linkedDocument.document.type	Enum	Conditional	Yes	SPAA, DMF, ATD, EFT, TEL_RECEIPT, WEB_RECEIPT, SEND_RECEIPT, SEND_PROOF, INVOICE, CHECK_IMAGE_BACK, CHECK_IMAGE_FRONT.
linkedDocument.document.name	String	Conditional	Yes	File name.
linkedDocument.document.base64encodedContent	String	Conditional	Yes	Base64 content.
processingDetail.location.id	Long	Optional	Yes	Location ID.
amount	Big Decimal	Mandatory	No	> 0.
purpose	String ≤ 128	Mandatory	Yes (ACH)	Purpose text.
allowDuplicate	Boolean	Optional (default false)	Yes	Allow duplicate schedule.
(Audit / status fields)	—	—	No	Same as common table.

11.2.2 ACH Transaction Attributes (continued)

Field	Type	M / O	Upd?	Description
processingDetail.order	Object	Optional	No	Order container for NACHA CCD/PPD detail.
processingDetail.order.invoice	Object	Optional	No	Invoice collection.
processingDetail.order.invoice.number	String ≤ 25	Optional	No	Invoice number.
processingDetail.order.invoice.discountRate	Number	Optional	No	% discount.
processingDetail.order.invoice.discountAmount	Number	Optional	No	Discount amount.
processingDetail.order.invoice.taxAmount	Number	Optional	No	Tax amount.
processingDetail.order.invoice.taxRate	Number	Optional	No	% tax.
processingDetail.order.invoice.taxExempt	Boolean	Optional	No	true / false.
processingDetail.order.invoice.shipmentDetail	Object	Optional	No	Freight / duty sub-object.
processingDetail.order.invoice.lineItem	Object	Optional	No	Line-item array (commodity, qty, cost, tax, duty, extended).
processingDetail.location	Object	Optional	Yes	Link a location.
processingDetail.location.id	Long	—	Yes	Ahrvo Location ID.
processingDetail.batch.id	Long	—	No	ACH batch ID (Retrieve).
funding	Object	Optional	No	Additional funding tags (key / value).
status	String	—	No	Current status (see § 11.3.1).
statusReason	String	—	No	Reason code.
statusDate	Timestamp UTC	—	No	mm/dd/yyyy HH:MM:SS.
processDate	Timestamp UTC	—	No	Date settled.
pendingCaptureAmount	N/A	—	—	Not used for ACH.
isFinalCapture	N/A	—	—	Not used for ACH.

---

11.2.3 WIRE Transaction Attributes

Field	Type	M / O	Upd?	Description
resourceName	Enum	—	No	Always transaction.
url	Object	—	No	Endpoint for this transaction.
id	Integer	—	No	Ahrvo ID.
externalId	String ≤ 45	Optional	No	Program reference.
method	String	Mandatory	No	"WIRE".
type	String	Optional	No	REGULAR.
isTaxPayment	Boolean	Optional	No	true = Tax wire, false = regular wire.
source	Object	Mandatory	No	Debit Ahrvo Account or External Account (CORPORATE only).
source.account.id	Long	Mandatory (Ahrvo)	No	Account ID.
source.externalAccount.id	Long	Mandatory when debiting External Account	No	External Account ID.
destination	Object	Conditional (REGULAR)	No	Credit Ahrvo or External Account.
destination.account.id	Long	Mandatory if crediting Ahrvo Account	No	Account ID.
destination.externalAccount.id	Long	Mandatory if crediting stored External Account	No	External Account ID.
destination.externalAccount.holderName	String	Mandatory for one-time	No	Bank holder name.
destination.externalAccount.accountNumber	Long	Mandatory for one-time	No	Bank account number.
destination.externalAccount.routingNumber	Long	Mandatory for one-time	No	ACH routing.
destination.externalAccount.wireRoutingNumber	Long	Mandatory for one-time	No	Fedwire routing.
destination.externalAccount.type	Enum	Optional	No	SAVINGS | CHECKING.
destination.externalAccount.holderType	Enum	Optional	No	CONSUMER | CORPORATE.
processingDetail	Object	Optional	Yes	Wire details.
processingDetail.memo	String ≤ 40	Optional	Yes	Fedwire description.
processingDetail.originator	String	Optional	Yes	Originator name.
processingDetail.wireReference	String	—	No	Bank reference (Retrieve).
processingDetail.location.id	Long	Optional	Yes	Location link.
processingDetail.payor	Object	Mandatory if PM requires	Yes	Payor KYC.
processingDetail.payor.name	String ≤ 23	M	Yes	Payor name.
processingDetail.payor.email	String ≤ 80	M	Yes	Payor email.
processingDetail.payor.phone	String	M	Yes	Payor phone (XXX-XXX-XXXX).
processingDetail.payor.address.*	Object	M	Yes	Payor address lines, city, state, zip (≤ 9), country (ISO-2).
processingDetail.taxDetail	Object	Conditional (isTaxPayment=true)	Yes	IRS tax wire fields (authority, TIN, taxType, year, month).
linkedDocument	Object	Optional	Yes	Authorization / proof docs.
amount	Big Decimal > 0	Mandatory	Yes	Wire amount.
amountOriginType	Enum	Cond.	No	For non-USD support (SOURCE/DESTINATION).
purpose	String ≤ 128	Mandatory	Yes	Reason.
allowDuplicate	Boolean	Optional	Yes	Default false.
(Audit/status fields)	—	—	No	Same as common table.

---

11.2.4 INTERNATIONAL_WIRE Transaction Attributes

Field	Type	M / O	Upd?	Description
method	"INTERNATIONAL_WIRE"	Mandatory	No	Fixed.
type	String	Optional	No	REGULAR | REFUND.
source.account.id	Long	Mandatory	No	Debit Ahrvo Account.
destination.internationalExternalAccount.id	Long	Mandatory when stored IEA	No	IEA ID.
destination.internationalExternalAccount.holderName	String ≤ 60	Mandatory for one-time	No	Holder name.
destination.internationalExternalAccount.holderAddress.addressLine1	String 4-40	Mandatory	No	Address line 1.
destination.internationalExternalAccount.holderAddress.addressLine2	String ≤ 30	Optional	No	Address line 2.
destination.internationalExternalAccount.holderAddress.city	String ≤ 45	Mandatory	No	City (Unicode allowed).
destination.internationalExternalAccount.holderAddress.state	Enum 2	Mandatory	No	State / province code.
destination.internationalExternalAccount.holderAddress.country	String 2	Mandatory	No	ISO-2 country.
destination.internationalExternalAccount.accountNumber	Long	Mandatory	No	Bank account number.
destination.internationalExternalAccount.swiftCode	String 8–11	Conditional	No	SWIFT/BIC.
destination.internationalExternalAccount.type	Enum	Optional	No	SAVINGS | CHECKING.
destination.internationalExternalAccount.holderType	Enum	Optional	No	CONSUMER | CORPORATE.
processingDetail.memo	String ≤ 40	Optional	Yes	Wire memo.
processingDetail.fxQuote.id	String	Optional	No	FX Quote ID (valid 30 s).
processingDetail.fxQuote.destination.amount	Big Decimal	—	No	Destination amount (Retrieve).
processingDetail.fxQuote.destination.currency	Enum	—	No	Destination currency.
processingDetail.fxQuote.fxRate	Big Decimal	—	No	Rate applied.
processingDetail.fxQuote.fee	Big Decimal	—	No	FX fee.
processingDetail.originator	String	Optional	Yes	Originator name.
processingDetail.wireReference	String	—	No	Bank reference.
processingDetail.location.id	Long	Optional	Yes	Location.
processingDetail.payor	Object	Mandatory if Payor-validation enabled	Yes	Payor details (name, email, phone, address).
amount	Big Decimal > 0	Mandatory	No	Wire debit amount.
amountOriginType	Enum	Mandatory for non-USD	No	SOURCE | DESTINATION.
currency	Enum 3	Mandatory	No	Debit currency (system currently USD).
purpose	String ≤ 128	Mandatory	Yes	Reason.
allowDuplicate	Boolean (default false)	Optional	Yes	Permit duplicates.
linkedDocument	Object	Optional	Yes	Authorization proof.
(Audit / status fields)	—	—	No	As common.

11.2.4 INTERNATIONAL_WIRE Transaction Attributes (continued)

Field	Type	M / O	Upd?	Description
linkedDocument	Object	Optional	Yes	Authorization / proof document set.
linkedDocument.id	String	—	No	Unique doc identifier (Retrieve).
linkedDocument.purpose	Enum	Conditional	Yes	Purpose of the linked document. Possible Values: AUTHORIZATION CHECK_DEPOSIT ESCALATION_IDENTIFICATION_PROOF
linkedDocument.document	Object	Conditional	Yes	Document metadata.
linkedDocument.status	Enum	Conditional	Yes	Document status. PENDING, VERIFIED, REJECTED
linkedDocument.document.resourceName	String	—	No	Always document.
linkedDocument.document.url	String	—	No	System endpoint to fetch the document.
linkedDocument.document.id	String	—	No	System-generated doc ID.
linkedDocument.document.type	Enum	Conditional	Yes	Linked-doc type. Possible Values (AUTHORIZATION): SPAA, DMF, ATD, EFT, TEL_RECEIPT, WEB_RECEIPT, SEND_PROOF, INVOICE, CUSTOMER_AGREEMENT, AMENDED_AGREEMENT Possible Values (CHECK_DEPOSIT): CHECK_IMAGE_BACK, CHECK_IMAGE_FRONT Possible Values (ESCALATION_IDENTIFICATION_PROOF): PASSPORT, DRIVING_LICENSE, STATE_ID, UTILITY_BILL, PERMANENT_RESIDENT_CARD, HOMEOWNERS_INSURANCE, PAY_STUB, PROPERTY_TAX_STATEMENT, RENTAL_AGREEMENT, CREDIT_REPORT, LEASE_AGREEMENT, HOMELOAN_STATEMENT, W2, ITIN_CARD, FORM_1099R, MARRIAGE_CERTIFICATE, BIRTH_CERTIFICATE, SSN_CARD, DEATH_CERTIFICATE, TAX_STATEMENT, BUSINESS_LICENSE, BANK_STATEMENT
linkedDocument.document.name	String	Conditional	Yes	Friendly file name.
linkedDocument.document.base64encodedContent	String	Conditional	Yes	Base-64 encoded body.
linkedDocument.linkedOn	Timestamp UTC	—	No	mm/dd/yyyy HH:MM:SS
linkedDocument.linkedBy	Object	—	No	User who linked the doc.

---

11.2.5 CHECK Transaction Attributes

Field	Type	M / O	Upd?	Description
resourceName	Enum	—	No	Always transaction.
url	Object	—	No	Endpoint for this transaction.
id	Integer	—	No	Ahrvo-assigned ID.
externalId	String ≤ 45	Optional	No	Program reference.
method	String	Mandatory	No	"CHECK".
type	String	Optional	No	REGULAR | EXTERNAL.
source	Object	Mandatory	No	Debit Ahrvo account (or external for REFUND).
source.account.id	Long	Mandatory	No	Debiting account ID.
destination	Object	Conditional (REGULAR)	No	Credit via Mailing Address or Contact.
destination.address.id	Long	Conditional	No	MailingAddress ID.
destination.payeeName	String	Optional	No	Payee name.
destination.contact.id	Long	Mandatory when Contact recipient	No	Contact ID.
destination.contact.mailingAddress.id	Long	Mandatory when Contact has mailing address	No	Address ID.
processingDetail	Object	Conditional	Yes	Check-specific controls.
processingDetail.deliveryMode	Enum	Optional	Yes	STANDARD (default), TWO_DAY, OVERNIGHT
processingDetail.remittanceInfo	Object	Optional	Yes	Check remittance template columns <key1>…<key10> (≤17 entries each).
processingDetail.memo	String ≤ 255	Optional	Yes	Memo printed on check.
processingDetail.isEndorsed	Boolean	Optional	No	true if user‐supplied endorsed images. Default false.
processingDetail.checkType	Enum	Conditional	No	BUSINESS_CHECK, PERSONAL_CHECK. Mandatory if isEndorsed = true.
processingDetail.accountNumber	String	Conditional	No	MICR account # (if endorsed).
processingDetail.routingNumber	String 9	Conditional	No	MICR routing # (if endorsed or checkType present).
processingDetail.onUs	String	Conditional	No	MICR on-us field.
processingDetail.auxiliaryOnUs	String	Conditional	No	Auxiliary on-us (business checks).
processingDetail.checkNumber	String 1-4	Conditional	No	Check number (if endorsed).
processingDetail.shippedBy	String	—	No	Shipping vendor (Retrieve).
processingDetail.printedBy	String	—	No	Printing vendor (Retrieve).
processingDetail.shippingStatus	String	—	No	Shipping status.
processingDetail.checkReference	String	—	No	Bank reference number.
processingDetail.location.id	Long	Optional	Yes	Location link.
linkedDocument	Object	Mandatory when type = REGULAR	Yes	Front/back images or document group.
linkedDocument.document.type	Enum	Mandatory	No	CHECK_IMAGE_FRONT, CHECK_IMAGE_BACK (Regular); or CK, CO, EN, IN, WP (External).
linkedDocument.document.name	String	Optional	No	File name.
linkedDocument.document.base64encodedContent	String	Mandatory	No	Base-64 payload.
linkedDocument.purpose	Enum	Mandatory	No	CHECK_DEPOSIT (Collect) or CHECK_IMAGE (Send).
amount	Big Decimal > 0	Mandatory	Yes	Check amount.
processInstantly	Boolean	Optional	No	Ledger debit instantly (default false).
purpose	String ≤ 128	Mandatory	Yes	Reason.
allowDuplicate	Boolean (default false)	Optional	Yes	Permit duplicate schedule.
comment	String ≤ 512	Optional	Yes	User comments.
(Audit / status fields)	—	—	No	As common.

11.2.5 CHECK Transaction Attributes (continued)

Field	Type	M / O	Upd?	Description
processingDetail.device.inputCapability	N/A	—	—	(Card-only; not used for Check)
Endorsement & MICR Validations	—	—	—	- processingDetail.isEndorsed = true requires all of:   • processingDetail.checkType   • processingDetail.routingNumber (9 digits)   • processingDetail.accountNumber   • processingDetail.checkNumber (1-4 digits) - For BUSINESS_CHECK, processingDetail.auxiliaryOnUs is mandatory.
Quick-Settle	—	—	—	Quick-Settle node is available only if Program Manager has enabled the feature.
PO Box Restriction	—	—	—	For Overnight / Two-Day checks, destination address cannot be PO Box / Lockbox.

---

11.2.6 BOOK Transaction Attributes

Field	Type	Mandatory / Optional	Can be updated?	Description
resourceName	Enum	—	No	Always transaction.
url	Object	—	No	Endpoint to fetch this transaction.
id	Integer	—	No	Unique Ahrvo ID.
externalId	String (max 45)	Optional	No	Program-manager reference.
method	String	Mandatory	No	"BOOK".
type	String	Optional	No	REGULAR (initiated by customer).
source	Object	Mandatory	No	Ahrvo account debited.
source.account.id	Long	Mandatory	No	Debit account ID.
destination	Object	Mandatory	No	Ahrvo account / card credited.
destination.account.id	Long	Mandatory	No	Credit account ID.
destination.account.externalId	Long	Conditional	No	External identifier (if supplied).
destination.card.id	Long	Mandatory	No	Ahrvo-issued CARD (type=CREDIT) for authorized user.
destination.card.externalId	Long	Conditional	No	External ID of the Credit Card (if supplied).
comment	String ≤ 512	Optional	Yes	User comments.
tags	List of String	Optional	Yes	Labels / tags assigned.
status	String	—	No	Current status (see § 11.3).
statusReason	String	—	No	Reason for status.
statusDate	Date	—	No	When status was set (UTC mm/dd/yyyy HH:MM:SS).
processDate	Date	—	No	When transaction processed (UTC).
createdOn	Timestamp UTC	—	No	Creation time.
createdBy.userType	Enum	—	No	User type.
createdBy.username	String	—	No	Username.
createdBy.status	Enum	—	No	User status.
lastUpdatedOn	Timestamp UTC	—	No	Last modification time.
lastUpdatedBy.userType	Enum	—	No	User type.
lastUpdatedBy.username	String	—	No	Username.
lastUpdatedBy.status	Enum	—	No	User status.

---

11.2.7 VIRTUAL_CARD Transaction Attributes

Field	Type	Mandatory / Optional	Can be updated?	Description
resourceName	Enum	—	No	Always transaction.
url	Object	—	No	Endpoint to fetch this transaction.
id	Integer	—	No	Ahrvo ID.
externalId	String (max 45)	Optional	No	Program-manager reference.
method	String	Mandatory	No	"VIRTUAL_CARD".
type	String	Optional	No	REGULAR.
source	Object	Mandatory	No	Ahrvo account debited.
source.account.id	Long	Conditional	No	Debit account ID (required when debiting specific account).
destination	Object	Mandatory	No	Entity to be credited.
destination.contact	Object	Mandatory	No	Contact receiving the Virtual Card.
destination.contact.id	Long	Mandatory	No	Ahrvo Contact ID.
processingDetail	Object	Conditional	Yes	Virtual-card specifics.
processingDetail.virtualCard	Object	Mandatory	No	Virtual card payload.
processingDetail.virtualCard.cardProgram	Object	Mandatory	No	Card-program link (contact Ahrvo AM for IDs).
processingDetail.virtualCard.cardProgram.id	Long	Mandatory	No	Card Program ID.
processingDetail.location	Long	Optional	Yes	Location reference.
processingDetail.location.id	Object	—	Yes	Ahrvo Location ID.
comment	String ≤ 512	Optional	Yes	User comments.
status	String	—	No	Current status (see § 11.3).
statusReason	String	—	No	Reason code.
statusDate	Date	—	No	When status set (UTC).
processDate	Date	—	No	When processed (UTC).
createdOn	Timestamp UTC	—	No	Creation timestamp.
createdBy.userType	Enum	—	No	User type.
createdBy.username	String	—	No	Username.
createdBy.status	Enum	—	No	User status.
lastUpdatedOn	Timestamp UTC	—	No	Last updated timestamp.
lastUpdatedBy.userType	Enum	—	No	User type.
lastUpdatedBy.username	String	—	No	Username.
lastUpdatedBy.status	Enum	—	No	User status.

11.3 Statuses

This section lists every status, status reason, and event—verbatim—from the specification.

---

11.3.1 Transaction Statuses & Status Reasons

(Applies to ACH, Check, Wire, International Wire, and Book)

Status	Description
SCHEDULED	Default on creation.
PENDING	Upon being unable to fulfil the following processing conditions of transaction: • Source account should be ACTIVE and have sufficient funds. • Destination should be in ACTIVE status. • Entities involved should be OFAC and CIP verified.
APPROVED	(For Card transactions only) Upon card transaction being authorized by issuing bank.
PROCESSING	Upon transaction being picked for processing.
CANCELLED	Upon receiving a request for cancellation from the user.
COMPLETED	• Post completion of realization interval (good-funds period). • Upon successful completion of refund.
FAILED	Upon being unable to process transaction within the transaction-processing interval from the authorized transaction date. Upon receiving a return due to account closure or debit block.
IN_DELIVERY	(CHECK only) Upon Check transactions being under shipment.
DELIVERED	(CHECK only) Upon Check being delivered successfully.
STOPPED	(CHECK only) Upon receiving a request to stop a Check after it has been printed.
VOIDED	Upon voiding a transaction (fraudulent, duplicate, others).

Status → Reason Map

Status	Reason
SCHEDULED	On User Request
PENDING	External Account Blocked • External Account Inactive • Account Inactive • Account Blocked • Account Closure Initiated • Account Closed • Customer Suspended • Parent Collect not in Completed Status • OFAC status is not verified
PROCESSING	Processing In Transit
CANCELLED	On Customer Request • Incorrectly Created • Others • Insufficient Funds • On User Request • Send Cancelled as per Compliance Uncleared Payment Policy
COMPLETED	Processed by System • Remote Check Processed
FAILED	Collect Processing Interval Lapsed • <return-description> (<return-code>) • Collect Processing Failed • External Account Blocked • External Account Inactive • Account Inactive • Account Blocked • Account Closure Initiated • Account Closed • Customer Suspended • Insufficient Funds • Transaction failed due to OFAC verification failure.
IN_DELIVERY	Processing In Delivery
DELIVERED	Transaction Delivered
STOPPED	Lost Check • Fraud • Incorrect Destination • Incorrect Amount • Incorrectly Created • On User Request • Others
VOIDED	Fraudulent • Duplicate • Others

---

11.3.2 CARD Transaction Statuses & Status Reasons

Status	Description
UNCAPTURED	Default on authorization transaction.
PARTIALLY_CAPTURED	• Amount of authorization captured and isFinalCapture not true. • Two captures exist and one capture is voided, leaving partial amount.
CAPTURED	• Capture amount equals authorization amount. • Capture amount greater than authorization amount. • Capture amount less than authorization but isFinalCapture true.
COMPLETED	• Post completion of realization interval (good-funds period). • Upon successful completion of refund.
FAILED	Upon receiving transaction failure from network.
VOIDED	Upon card collect being voided by merchant.
APPROVED	Default on creation of refund via CARD and on creation of capture.

---

11.3.3 External Account Statuses

Status	Description	Events Responsible For
INACTIVE	Pending Verification	Default on creation
PENDING_VERIFICATION	Pending Verification	External account is under verification & validation.
ACTIVE	• Credit Only (EWS – No debits accepted) • Credit Only (R01 – Insufficient Funds) • Upon successful verification and/or validations of external account.	—
BLOCKED	Account In Error (R02 – Account Closed) • Account Blocked (Micro-Deposit verification failure) • Account Inerror (Manually Flagged)	• Receiving returns on Collects / Prenote / Micro-deposit transactions. • Receiving “Account Closed” via instant validation. • Manual BLOCKED flag.

---

11.3.4 International External Account Statuses

Status	Status Reason	Events Responsible For
INACTIVE	Pending Verification	Default on creation.
ACTIVE	OFAC Verified	Upon successful OFAC verification of the International External Account.
BLOCKED	OFAC Rejected	Upon manually marking the OFAC of the International External Account as REJECTED.

---

11.3.5 OFAC Statuses

Status	Events Responsible For
PENDING_VERIFICATION	Default status on create or holder-name update when OFAC verification is enabled.
VERIFIED	Upon successful verification of OFAC.
UNDER_REVIEW	System unable to verify OFAC automatically—escalated to Ahrvo team for manual review.
REJECTED	OFAC disapproved during manual verification.
IGNORED	Default if OFAC verification is disabled.

---

11.3.6 Linked Document Statuses

Status	Events Responsible For
PENDING_VERIFICATION	Default status upon uploading the document.
VERIFIED	Upon successful review of a document by the reviewer.
REJECTED	Upon rejection review by the reviewer.

---

11.4 Business Validations

1. Account-validation hold – If an account-validation (prenote) feature is enabled, a user cannot schedule a Collect within 3 business days from the prenote schedule date.
2. External IDs must be unique for all transactions and cannot be updated once provided.
3. Configurable Card fields – At onboarding, Ahrvo allows a Program Manager to mark cvv, billingAddress, holderName, and brand as optional. If any of these are optional, a warning is displayed:

   “It is recommended to pass CVV, billing address, holder name to minimize processing expense and prevent fraud exposure.”

4. Transaction date must be the current UTC date (no back-dating or future-dating).
5. A CHECK transaction can be stopped only if its status is PROCESSING, IN_DELIVERY, or DELIVERED.
6. For a transaction with method CHECK OVERNIGHT or CHECK TWO_DAY, the destination address cannot be a PO Box or Lockbox.
7. For a one-time International External Wire, the holder address cannot be a PO Box.
8. If reason = OTHERS, the field comment becomes mandatory.
9. Refund rules
   • parent may reference either the id or externalId of the original transaction.
   • method may be CARD or ACH.
   • A refund can be scheduled when the parent is in PROCESSING, APPROVED, or COMPLETED; it will not process until the parent reaches COMPLETED.
   • Refund amount ≤ parent amount.
   • If multiple refunds exist, the sum of refunds must not exceed the parent amount.
10. Check Remittance templates
    • Configured by Ahrvo admin. Contact AM to obtain template ID & columns.
    • Max 10 columns; max 17 entries per column.
11. Endorsement validation flags (processingDetail.checkType, routingNumber, accountNumber, checkNumber, isEndorsed) are optional, mandatory, or not supported based on PM settings. Contact admin to change settings.
12. Default ACH authType – PM may configure a default (WRITTEN, ONLINE, PHONE). If default is none, customers must supply authType on Create.
13. processInstantly flag
    • Considered only for CHECK and BOOK.
    • For BOOK, default is false; if true, the customer’s account is debited immediately and transaction status becomes COMPLETED.
14. Quick-Settle is visible only for ACH & Check if the PM has enabled the feature.
15. Virtual Card issuance – Creating virtual cards for your own use does not require PCI-DSS; issuing for your users may classify you as a Service Provider and require compliance.
16. For newly-onboarded PMs & Customers, CARD captures & refunds are created in APPROVED status (legacy INITIATED kept for existing integrations).
17. Foreign-Exchange Quote
    • Use the FX Quote API for non-USD International Wires.
    • The fxQuote.id is valid for 30 s; an expired quote causes an error.
    • If no quote is supplied, the system fetches one and returns its ID in the Retrieve response.
18. Surcharge logic
    • Where surcharge is disabled, integrator must omit surchargeAmount or set it to 0.
    • surchargeAmount is calculated on originalAmount, excluding tip.
    • Banker’s rounding is enforced:
      • 3.455 → 3.46 (third decimal 5, second decimal odd)
      • 3.465 → 3.46 (third decimal 5, second decimal even)
      • 3.454 → 3.45 (third decimal < 5)
      • 3.456 → 3.46 (third decimal > 5)
    • Debit & Prepaid cards – surcharge prohibited.
    • State restrictions: Connecticut, Maine, Texas, Massachusetts, Puerto Rico prohibit surcharges. Colorado: max 2 % or processing cost. All other states: max 3 %.
    • For Ad-hoc refunds, merchants with surcharge enabled must either refund the exact surcharge or 0. Any deviation triggers an error.

---

11.5 Error Codes & Messages

Code	Error Message	Condition
EC-VA-0005	"field":"<field-name>", "message":"Is required."	Mandatory node omitted.
EC-VA-0001	"field":"<field-name>", "message":"Invalid Value <value> for field <field-name>."	Unsupported field value.
EC-BL-2305	"A duplicate transaction already exists."	Duplicate transaction created.
EC-BL-0003	Send with external reference: <external-id> already exists.	Attempt to change externalId.
EC-BL-0020	externalAccount with id: <external-id> does not exist.	Non-existent External Account ID.
EC-VA-0005	"field":"scheduleDate", "message":"Date cannot be in past or future."	Transaction date not current.
EC-VA-0001	"field":"method", "message":"Invalid Value <value> for field method."	Unsupported method.
EC-BL-0019	Please add a comment as the reason for stopping a send instruction is 'Others'.	comment missing when reason = OTHERS.
EC-BL-4384	"Authorisation failed-<reason>", "processorCode":"<code>"	Card authorization failure (see processor code list).
EC-BL-0034	CHECK Send transaction with id :<id> and externalId :<externalId> does not exist	Unknown Check send reference.
EC-BL-0035	No document found for the requested send transaction.	Send transaction lacks document.
EC-BL-0908	You cannot update mailing address with PO box/ Lock box. Check 2day/ Check Overnight send instructions are scheduled for this mailing address with :<object>	Attempt to update address linked to expedited Check.
EC-BL-1127	Can not stop a check send transaction in :<object> status.	Stop request in disallowed status.
EC-BL-1153	Can not stop a WIRE send transaction.	Stop request for Wire.
EC-BL-1175	Invalid field :<entity> for creating a :<method> send transaction.	Unsupported node for method.
EC-BL-4422	Credited account : [accountNumber] does not match with the payment account	Credited account mismatch.
EC-BL-1181	Invalid header for remittance template.	Remittance header mismatch.
EC-BL-1181	Remittance template does not exist.	Unknown remittance template.
EC-VA-0005	The length should not exceed 255 characters.	Memo length > 255.
EC-BL-9954	:<method> method not supported by this :<entityName>.	Unsupported method for entity.
EC-BL-9977	:<value> is not an accepted currency for the International External Account :<id>	Unsupported currency for IEA.
EC-BL-9999	Only USD is supported as currency.	IEA does not support provided currency.
EC-BL-10196	Authorization cannot be voided as it has already been captured	Attempt to void captured auth.
WARN-2213	Authorization: {id} adjusted from amount: {original_amount} to amount: {final_capture_amount}	Pending capture adjusted.
EC-BL-10191	Final capture received for Authorization.	Cannot adjust after final capture.
EC-BL-0373	processingDetail.checkType cannot be null.	Missing checkType on endorsed Check.
EC-BL-0382	processingDetail.checkNumber cannot be null.	Missing Check number on endorsed Check.
EC-BL-0383	processingDetail.routingNumber cannot be null.	Missing routing number on endorsed Check.
EC-BL-0384	processingDetail.accountNumber cannot be null.	Missing account number on endorsed Check.
EC-BL-10351	FxQuote has expired. Please try again.	FX Quote older than 30 s.
EC-VA-0004	amountOriginType as Destination is mandatory when the transaction involves a non-USD foreign currency.	Missing amountOriginType on non-USD Intl Wire.

---

11.5 Error Codes & Messages (continued)

Code	Error Message	Condition
EC-BL-10362	Delete not allowed on Non USD accounts.	Attempt to delete non-USD account.
EC-BL-10355	Update not allowed on Non USD accounts.	Attempt to update non-USD account.
EC-BL-10359	{"field":"taxID","message":"taxID is mandatory…"}	Missing country-specific field.
EC-BL-0005	{"field":"acceptedCurrency", …}	Missing mandatory fields.
EC-BL-9999	Only USD is supported as currency.	Provided currency not supported.
Codes EC-VA-0005, EC-VA-0001, EC-BL-2305, EC-BL-0003, EC-BL-0020, EC-BL-0019, EC-BL-4384, EC-BL-0034, EC-BL-0035, EC-BL-0908, EC-BL-1127, EC-BL-1153, EC-BL-1175, EC-BL-4422, EC-BL-1181, EC-BL-9954, EC-BL-9977, EC-BL-10196, WARN-2213, EC-BL-10191, EC-BL-0373, EC-BL-0382, EC-BL-0383, EC-BL-0384, EC-BL-10351, EC-VA-0004 appear earlier in Part 7 with their full messages and triggers.

---

11.6 Operations Supported

The Transaction entity supports the following operations:

#	Operation	Description
11.6.1	Create Transaction	Schedule a new transaction (collect, send, refund, etc.).
11.6.2	Update Transaction	Modify allowed fields of an existing transaction.
11.6.3	Retrieve Transaction by ID	Fetch full details of a specific transaction.
11.6.4	Delete Transaction	Permanently delete a transaction (where permitted).
11.6.5	Cancel Transaction	Cancel a scheduled or pending transaction.
11.6.6	Stop Transaction	Stop a Check transaction already printed/shipped.
11.6.7	List Transaction	List transactions matching filter criteria.
11.6.8	Void Transaction	Void an uncaptured card authorization.
11.6.9	Refund Transaction	Issue a refund against a completed collect/send.
11.6.10	Adjust Transaction	Adjust a prior card authorization amount.
11.6.11	Retrieve Virtual Card Image	Get the image (front/back) of a virtual card.
11.6.12	Capture Transaction	Capture funds on a prior card authorization.

---