5. Buyer

4.1 Overview

A buyer represents the organization who has to pay to multiple vendors at a defined cadence. There can be multiple buyers on-boarded under an institution. Each institution on boards its own buyer. Currently, there is no buyer that is associated with more than 1 institution in CPX production.

Buyers who are considered high-risk are typically set up as Pre Fund, which means they must first fund their account before payment can be made. Dual Approval is activated for these buyers and the payment instruction file (PIF) is processed only if there are sufficient funds available. CPX can perform a consolidated debit for all instructions in a batch that is grouped in the PIF file.
In contrast, other buyers are usually set up as Good Funds. In this case, CPX obtains funds from the buyer's shared billing account. The buyer can be configured to obtain funds from different billing accounts for each payment method, either before the PIF file is processed for certain buyers or after the payment is made for others. The funds are deposited into an account maintained by Priority at one of the banks, Synovous.
CPX also provides support for Credit Buyers. For this type of buyer, CPX funds the payments from its own account and then collects interest from the buyers as a return.
ACH only processes Good Funds and cannot be used by Pre Fund buyers. Pre Fund buyers cannot use ACH because ACH requires money to be directly pulled from the buyer's account, while Pre Fund buyers send the money to CPX on their own instead of having CPX pull it.

4.2 Attributes

Field	Sub Field	Type	Description
id		string	Internal Id of the Buyer
acl		array	access control list for the buyer
name		string	Name of the Buyer
address	street1 city state country postalCode	string string string string string string	street1 is the street address of the Buyer street2 is the street address of the Buyer city of the Buyer state of the Buyer country of the Buyer
creditLimit		integer	Credit Limit of the Buyer
yearlyEstimatedSpent		String	Estimated amount spent/ paid by the buyer in an year
status		string	Internal status of the Buyer
externalStatus		string	External Status of the Buyer
contacts	id primary name title email phone	boolean string string string string string	primary determines the default contact in case there are multiple contacts of a buyer name of the buyer title determines the position of the contact in the respective organisation email of the contact phone of the contact
associatedInstitutionName		string	Name of the Institution to which Buyer is associated
associatedInstitutionId		string	Internal Id of the Institution to which Buyer is associated
bid		string	An unique id between a respected buyer and an institution
mri		Object	Only used for MRI Network
	clientId	String	Client ID for MRI Network
	database	String	Database name for MRI Network
	username	String	Username for Database for MRI Network
	password	String	Password for Database for MRI Network
virtualCardRequested		boolean	to allow vcn payment
virtualCardEnabled		boolean	Underwriting node (internal)
virtualCard		Object	Virtual card configuration for the buyer
	bankAccountId	string	bank account used to process VCN payments
	billing	string	items : Pre Fund Daily bill daily pay Good Funds 7/3 7/10 14/3 30 days other
	debitMethod	string	Manual Processor (DBDP- Braves) Debit by batch Debit for each transaction Debit by Day
	debitProcessor	Enum	The debit process for Virtual Card. This will be NA by default when VC is requested. Valid Values: For Good Funds CPX PASSPORT For DBDP CPX for Falcons NA for Braves For Prefund and credit billing NA
	delayDays	number	Payment is debited from buyer on payment date but is paid to supplier after number of days specified Min - 0 Max 7
	exposureTracking enabled days limit lastUpdatedDate currentExposureAmount	object boolean integer number string number	Track spending of buyer. If limit is breached, payments require approval for processing. Minimum 1, max 150
achRequested		boolean	to allow ach payment
achEnabled		boolean	Underwriting node
ach		object	ACH configuration for Buyer
	bankAccountId	string	bank account used to process ACH payments
	billing	string	Billing method for the buyer for ACH : GOOD_FUNDS PRE_FUND OTHER
	delayDays	number	Number of days the credit should be delayed by after payment creation date.
	debitProcessor	Enum	The debit process for ACH. This will be NA by default when ACH is requested. Valid Values: For Good Funds CPX PASSPORT For Prefund NA
	debitMethod	string	Manual Debit by batch Debit for each transaction
	exposureTracking enabled days limit lastUpdatedDate currentExposureAmount	object boolean integer number String number	To track exposure and spending for the payment method
checkEnabled		boolean	To Enable Check for Buyer
checkIssuing		Object	Check Issuing Configuration
	bankAccountId	string	Id of Bank account to be used for Check Issuing
	debitMethod	enum	Debit method set for check issuing
	debitProcessor	enum	Debit Processor set for Check Issuing. This is NA by default but can be PASSPORT as well.
	delayDays	number	Number of days the credit should be delayed by after payment creation date. Only valid for PASSPORT as debit processor.
	billing	enum	Billing method for buyer. Blank by default. It can be GOOD_FUNDS for PASSPORT debit processor.
	exposureTracking enabled days Limit lastUpdatedDate currentExposureAmount	object boolean integer number string number	Track spending of buyer. If limit is breached, payments require approval for processing. Minimum 1, max 150
managedCheck		Object	Managed Check Configuration
	bankAccountId	string	Id of Bank account to be used for Managed Check
	debitMethod	enum	Debit method set for managed check
	debitProcessor	enum	Debit Processor set for Managed Check. This is PASSPORT by default.
	delayDays	number	Number of days the credit should be delayed by after payment creation date.
	billing	enum	Billing method for buyer. GOOD_FUNDS by default
	exposureTracking enabled days Limit lastUpdatedDate currentExposureAmount	object	Track spending of buyer. If limit is breached, payments require approval for processing.Minimum 1, max 150
managedCheckRequested		boolean	If Managed Check is requested to be enabled.
managedCheckEnabled		boolean	If Managed Check is enabled.
checkIssuingRequested		boolean	If Check issuing is requested to be enabled.
checkIssuingEnabled		boolean	If Check Issuing is enabled.
isEnhancedManagedCheck		boolean	If Enhanced Check Issuing is enabled
customRemittanceEnabled		boolean	If Custom Check Remittances are enabled. Applicable only for Check Issuing
checkInsertsEnabled		boolean	If Check Inserts are enabled
invoiceUploadEnabled		boolean	If Invoice PDF uploads are enabled
wireRequested		boolean	to allow wire payment
wireEnabled		boolean	Underwriting node for Wire
wire		object	Wire configuration for Buyer
	walletId	string	Wallet ID used to process wire payments
	billing	string	Billing method for the buyer for Wire : GOOD_FUNDS
	debitMethod	string	Debit method for the Payment Debit for each transaction
	debitProcessor	enum	Debit Processor set for Wire. This is PASSPORT by default.
	exposureTracking enabled days limit lastUpdatedDate currentExposureAmount	object boolean integer number String number	To track exposure and spending for the payment method
pifApproval		Boolean	To enable or disable pifApproval. Enable this feature to offer buyers the option to review and approve payment files prior to processing.
pifApprovalConfig		array	Enable approval process for PIFs at buyer level
	level	String	Level of Approval config payment pif
	DEFAULT/ACH/ CARD/ CHECK Approvers firstLevel Id firstName lastName Email Username role Id Name secondLevel Id firstName lastName Email Username role Id Name Threshold firstLevel secondLevel requireAllLevelApproval	Array Array Array String String String String String Array String String Array Array String String String String String Array String String Array String String Boolean	PIF/Payment level approval set. For PIF level approval and Payment level approval with same threshold for different payment modes, node would be default else the payment method for which threshold is being set. Approvers - List of approvers set for each threshold. firstLevel - Approver set at the first level. secondLevel - Approver set at the second level. Id of the approver Firstname of the approver Last name of the approver Email of the approver Username of the approver Role of the approver Id of the role of the approver Name of the role of the approver Threshold - threshold limits for approval requireAllLevelApproval- if both level approvals are required for the approval
	paymentMethodLevelApproval	Boolean	Whether different thresholds for different payment method are enabled
paymentFileType		string	Defines the payment file type which will used to process payments uploaded in a file
achPaymentRoute		string	route through which ach payments will be happening
schedulePaymentsForFuture		boolean	Enable payments to be scheduled upto 90 days in future
dualPifApproval	enabled	boolean	to hold the payment file before processing it. Used in case of high risk buyers. Internal team manually approves the payment files of the buyer for which this toggle is ON
failOverPayment	enabled	boolean	to determine whether to process a payment through different route if the default payment has failed
	VCN		Switch VCN to ACH or CHK
bankAccounts	accountNumber	String	bank account number of the Buyer
	routingNumber	String	routing number of the Buyer’s bank account
	defaults VCN ACH CHK MCK	array	To determine the default bank account for a particular payment MCK not available right now
	accountType	string	type of the bank account i.e. checking and savings
	id		Id of bank account
	bankName		Name of bank account
	passportBankAccountStatus	string	Whether Bank account is enabled for transaction on Passport.
nachaId		String	Nacha ID to be used for ACH payments. By default, CPX’s Nacha ID is used.
achMerchantId		String	The merchant id of the buyer for the ACH transaction.
achConfig		Object	Custom ACH configuration to be passed with ACH payments
	metadata description field Text addenda Mapping Field order text	Object Object String String Object Object String String String	Data to be passed with ACH payment Information for description Payment field to be passed in description Static Text if field is set as other Information to be passed in addenda Mapping for addenda Payment field to be passed in addend Order of the field set Static Text if field is set as other
buyerWalletEnabled		Boolean	To enable buyer virtual wallet functionality
vcnHost		string	card processor for the Buyer
vcnHostConfig		Object	Configuration for VCN host. Necessary if vcnrequested if true
	falcons paymentReferenceNumber location products VCN id name value VWA LDG id name value PPD	Object String String Object Object String String String String Object String String String String	Falcons configuration for the Cards Reference number of the card products Location of the falcons product Type of product to be added for falcons VCN - Virtual card product Id of card product Name of card product Value of card product LDG - Lodged Card product Id of card product Name of card product Value of card product PPD - Prepaid debit VWA - Virtual wallet
	united primaryAccountNumber companyNumber	Object String String	United configuration for cards Company number for united config Primary account number for united config
	braves primaryAccountNumber companyNumber centralBillAccountNumber	Object String String String	Braves configuration for cards Company number for braves config Central Bill account number for braves config. Only used for Lodged Exact Match card Primary account number for braves config
	Vpa pp enabled rva enabled visaBuyerId templateId fundingInfo creditLimit expirationDate fundingAccount	Object Object Boolean Object Boolean String String Object String String String	Visa VPA configuration for cards Process Payments Request Virtual Cards Visa Buyer Id Visa Buyers Template Id Funding account information Credit limit of a/c Expiration date of a/c Funding account number
cardRules		Array of objects	Card Rules to create virtual card products
	id	String	Id of card rule in CPX
	host	string	VCN host for the card rule
	ruleType	enum	Rule
	type	enum	Type of Card Rule Values -
	name	string	Name of Card Rule
	expirationDays	string	Number of days after which card created by card rule expires.
	ruleValue	string	Template ID or Rule value for Card Rule
	isExactAmount	boolean	If amount should be an exact match to authorization to be authorized
	isDefault	boolean	If the card rule is default card rule
	billLevel	string	Billing level for Card rule
	reOrderCount	string	Reorder count of Accounts for Pool
	initialOrderCount	string	Initial count of Accounts for Pool
	minAvailableAccounts	string	Minimum count of Accounts that should be available in Pool
lodgePaymentEnabled		boolean	to allow lodge payment
lodgePaymentCards		Array
	id	String	Id of the lodged card
	cardNumber	String	Card number generated by card provider
	cvv	String	Cvv of the Card as per card provider
	type	String	Type of Lodged Card
	template id host name type ruleType billLevel isDefault ruleValue isExactAmount expirationDays	Object String String String String String String Boolean String Boolean String	Details of the Template to which the card is associated Id of the template Host of the template Name of the template Type of the template (Lodged / Legacy, Lodged / P-Card, Lodged / Exact Match) ruleType of the template billLevel of the template If the card is the default product Value of the rule associated with card template If the card only allowed exact amount debits Number of days after which card expires
	source	String	Source/Card provider
	reference	String	Reference for the card
	cardEntityId	String	Entity Id of the card
	expirationDate	String	Expiration date of the card
	expirationString	String	Expiration date in mmyy format
	payments	String	Number of Payments on the card
	balance	String	Balance available on the card
legalName		string	Legal Name of the buyer
isAlternateMailingAddress		boolean	If Buyer has an alternate mailing address
mailingAddress		Object	Mailing address details
	street1	String	street1 is the street address for Buyer underwriting
	street2	String	street2 is the street address for Buyer underwriting
	city	String	city for Buyer underwriting
	state	String	state for Buyer underwriting
	country	String	Country for Buyer underwriting
	postalCode	String	Postal code for Buyer underwriting
website		string	Website for Buyer underwriting
yearsInBusiness		number	The time period for which the buyer remains in the business.
annualSales		number	Annual sales amount of the buyer
ownershipType		string	Ownership type of the buyer’s business
legalEntityType		string	Entity Type of the buyer
ssnEinType		string	SSN EIN type of the buyer
taxId		string	Tax ID of the buyer
stateOfOrganization		string	State of the Buyers business
sic		object	SIC / NAICS Code
	code	string	SIC Code
	description	string	SIC description
owners		Array	Owners of Buyer
	owner id firstName lastName title ownershipPercentage isControlProng emailAddress phone isUSCitizen dateOfBirth address street1 street2 City State country postalCode ssn	Object String String String String number boolean string string boolean string object string string string string string string	Id of the owner First name of the owner Last Name of the owner Title of the owner Ownership Percentage of the owner If the owner has most control over entity Email address of the owner Phone number of the owner If owner is US citizen Date of birth of the owner Address details of the owner SSN of the owner
plastiqPayEnabled		boolean	To enable plastiqPay
created		string	Date and time of creation of Buyer
creator	id	string	Id of user creating the buyer
	username	string	Username of user creating the Buyer
modified		string	Date and time of last modification of Buyer
modifier	id	string	Id of user who has last modified the buyer
	username	string	Username of user who has last modified the buyer
deleted		Boolean	Whether buyer is deleted or not
plastiq		ObjectS	Plastiq Sync node to capture information from Plastiq
	payerId	String	Plastiq Id for the buyer entity
	syncError	String	Sync error message for Plastiq
passport		Object	Passport sync node to capture information from Passport
	customerId	String	Id of customer in Passport corresponding to the buyer
	account da id	Object Object String	Buyers account information from Passport.Deposit account information Id of deposit account
	addressId	String	Id of address in passport
	syncError	String	Sync error message for Passport
	bankAccounts Id addressId	Object String String	Id of bank account in Passport addressID of bank account
	externalAccount Check addressId id	Object Object String String	External Account information in Passport. Check, addressId and id of the external Account
checkAccounts		Object	Check account details
	id	string	Id of check account of buyer
	Address City State Country Street1 postalCode	Array String String String String String	Address details of check account of buyer
	bankName	string	Bank Name for check account of buyer
	accountId	string	Id for check account in Passport
	syncError	string	Sync error message for Plastiq
	accountType	Enum	Type of check account Checking saving
	checkProofId	string	Check proof Id corresponding to smart payables
	accountNumber	string	Account number for check account
	accountStatus	string	Status of check account
	routingNumber	string	Routing number of check account
	checkNextNumber	string	Next check number for the account
	checkStartNumber	string	Starting of check number for the account
	signatureAttachmentId	string	Id of signature image for the account in Smart payable
externalCards		Object	External card details
	id	String	Id/Token of external card in Plastiq
	Address City State Country Street1 postalCode	Array string string string string string	Billing address details for the card
	isDefault	Boolean	Whether the card is the default card
	cardNumber	String	Card number of the external card
	securityCode	String	Security code/cvv of the external card
	cardHolderName	String	Name of the card holder
	expirationString	String	Month and year of expiry of the card
	plastiqPaymentMethodId	String	Payment method id for the card in Plastiq
dualPifApproval		Object	Whether dual PIF approval is enabled for the buyer
	enabled	boolean	If dual Pif is enabled
lodgePCards		Object	P card details
	id	String	Id of lodged P card
	cvv	String	CVV of lodged P card
	type	String	Type of Lodge P Card
	source	String	Card processor of Lodge P Card
	disabled	boolean	Whether the card is disabled
	supplier id name sid	Object String String String	Details of the supplier to which the card is associated Id of supplier Name of supplier SID of supplier
	template id host name type ruleType billLevel isDefault ruleValue isExactMatch expirationDays	Object String String String String String String Boolean String Boolean String	Details of the Template to which the card is associated Id of the template Host of the template Name of the template Type of the template (Lodged / Legacy, Lodged / P-Card, Lodged / Exact Match) ruleType of the template billLevel of the template If the card is the default product Value of the rule associated with card template If the card only allowed exact amount debits Number of days after which card expires
	reference	String	Reference number of the P card to map between Card provider and CPX
	cardNumber	String	Card Number of Lodged card
	creditLimit	String	Limit set for the Lodged Card
	cardEntityId	String	Entity Id of the Lodged P Card
	expirationDate	String	Expiration Date of the Lodged P Card
	expirationString	String	Expiration Date of the Lodged P Card in MMYY format
	createdNotificationSent	String	Date and time when notification for P Card has been sent to supplier
	payments	String	Number of payments on lodged P card
	dailySpendLimit	String	Daily spend limit on the P card
associatedInstitutionPifApproval		boolean	Whether PIF approval is enabled for the associated institution
associatedInstitutionManagedCheck		boolean	Whether managed check is enabled for the associated institution
associatedInstitutionSchedulePaymentsForFuture		boolean	Whether schedule payments is enabled for the associated institution
associatedInstitutionCheckInserts		boolean	Whether check inserts is enabled for the associated institution
associatedInstitutionExpeditedShipping		boolean	Whether expedited shipping is enabled for the associated institution
associatedInstitutionInvoiceUpload		boolean	Whether invoice uploadis enabled for the associated institution
associatedInstitutionVcnHost		String	Which VCN host is enabled for the associated institution
associatedInstitutionPlastiqPayEnabled		boolean	Whether PlastiqPay is enabled for the associated institution
backupCardRetrialEnabled		boolean	Whether Payment should be retried with backup card if primary card fails.
flagsEnable		Array	Features enabled for the buyer
cpa		Object	CPA sync node to capture information from CPA
	id	String	Id of buyer on CPA
	isActive	Boolean	Whether VPA is enabled at the buyer level or not
	cardTypes id syncError errors id code message statusCode	Object String Object Object String String String String	Types of cards associated Id of card associated Sync error for cardTypes Errors for card Types Error information Id of error Code of error Status code of error
	syncError	String	Sync Error for CPA
	fundingAccount syncError	Object String	Funding account for VPA Sync error for Funding account

4.3 Statuses

Internal Status

Received
Under Review
Closed
Approved
Declined
Canceled
Suspended

External Status

Active
Inactive

4.4 Operations

4.4.1. Create Buyer
4.4.2. Update Buyer
4.4.3. Retrieve Buyer By Id
4.4.4. Retrieve Buyer By Id for Export
4.4.5. Retrieve Buyer by Custom Field
4.4.6. Delete Buyer
4.4.7. Update Exposure Tracking Data for Buyer