These changed endpoints are for these application corrections:
#22804 "API Allows NULLs for Bank_Account_Nam so User cannot edit payment method on customer"
#27220 "Add GET api/paymentmerchant/bankaccounts"
POST api/paymentmerchant/addbankaccount:
- CustomerBankId - Must be supplied but is ignored. Response contains the CustomerBankId created.
- CustomerId - Optional.
- If supplied, must reference a valid Customer. If CustomerNumber is also supplied, both must reference the same Customer.
- If not supplied, CustomerNumber must be supplied.
- CustomerNumber - Optional.
- If supplied, must reference a valid Customer. If CustomerId is also supplied, both must reference the same Customer.
- If not supplied, CustomerId must be supplied.
- BankId / BankCode are both optional and processed in the following order. Note that once the bank is set, it cannot be changed via an update, as it is directly linked to the ACHDirectToken (which also cannot be changed).
- If BankId supplied, must reference a valid Bank defined as a "customer bank". If BankCode is also supplied, both must reference the same Bank. Will either have a valid Bank or an error -> done.
- If BankCode supplied:
- If this references an existing Bank, that Bank must be defined as a "customer bank". If so -> done; otherwise -> error.
- If this does not reference an existing Bank Code, and the BankCode is nine digits, the BankCode is assumed to be a routing number. A Bank will then attempt to be found using that routing number.
- If found, that Bank must be defined as a "customer bank". If so -> done; otherwise -> error.
- If not found, a Bank will be added with that routing number when this customer bank record is added -> done.
- The supplied ACHDirectToken is be used to determine the bank account. If found -> done; otherwise -> error.
- BankName - Incoming value ignored - populated in response.
- BankDescription - Incoming value ignored - populated in response.
- PreNoteRequired - Specifies whether a prenote is required. If null or not supplied, defaults to false.
- PreNoteDone - Specifies whether a prenote has been performed. If null or not supplied, defaults to false.
- CheckingOrSavings - Must supply C, S, Checking, or Savings. This cannot be changed by an update.
- AccountType - Incoming value ignored - populated in response.
- PaymentMethodId - Optional.
- If supplied, it must reference a valid payment method. If PaymentMethodCode is also supplied, both must reference the same payment method.
- If not supplied, PaymentMethodCode must be supplied.
- PaymentMethodCode - Optional.
- If supplied, it must reference a valid payment method. If PaymentMethodId is also supplied, both must reference the same payment method.
- If not supplied (and PaymentMethodId not supplied), the first payment method code that begins with EFT will be used. If not found -> error.
- Note about payment method: The payment method does not necessarily need to be a bank (non-credit card) type. Although perhaps unexpected behavior, the SO client allows that, so the API does the same.
- BankAccountName - Incoming value ignored - populated in response.
- UsedForAutoProcess - See explanation below under "Common Properties".
- AutoProcessDay - Optional, set to 1 if not supplied or value < 1 is supplied. This specifies the day of the month on which auto recurring charges will be processed. This cannot be greater than 28.
- LastFourDigits - The last four digits of the bank account. This is optional, but it should be included for easier identification of the bank account.
- Scanned - Specifies whether the bank account is "scanned" (shows in "Scanned Banks" section - see below). If null or not supplied, defaults to false.
- ACHDirectToken - Required. This is the token created by the payment processor. This cannot be changed by an update.
- UsedForNonRecurAuto - See explanation below under "Common Properties".
- MaxNonRecurAmount - Optional, set to zero if not supplied or value < 0 is supplied or UsedForNonRecurAuto is false.
- DaysPastInvoiceToHold - Optional, set to zero if not supplied or value < 0 is supplied or UsedForAutoProcess is false.
- CustomerBillId - Optional, set to 1 if not supplied or value < 1 is supplied or UsedForAutoProcess is false. If this bank account should be used to auto pay the recurring of only a specific Bill To, that Id should be supplied; otherwise leave empty or set to 1.
- CustomerBillBusinessName - Ignored. The response will have this populated.
- PrintCycleInvoices - See explanation below under "Common Properties".
- Customer_Name - Ignored. The response will have this populated.
- AccountNumber - Deprecated property - incoming value ignored and will be empty in response.
PUT api/paymentmerchant/updatebankaccount/{id}:
- CustomerBankId - Must be supplied and reference the Customer Bank record being updated.
- CustomerId - Ignored. The customer to which a bank entry applies cannot be changed.
- CustomerNumber - Ignored. The customer to which a bank entry applies cannot be changed.
- CheckingOrSavings - Ignored. This cannot be changed because it is determined by the ACHDirectToken.
- BankId and BankCode - Ignored. Bank cannot be changed because it is determined by the ACHDirectToken.
- ACHDirectToken - Ignored. The token cannot be changed because it defines the bank account.
The remaining fields are processed as follows:
- Any field supplied as 'null' will retain its existing value in the database. Regarding multiple fields referencing the same entity, such as PaymentMethodId / PaymentMethodCode, all fields must be null to retain the existing value - if *any* of the fields are supplied, it means that an update is desired.
- Any field with a supplied value will update the specified Customer Bank record according to the rules described in POST.
POST api/paymentmerchant/addcreditcard: - CustomerCCId - Must be supplied but is ignored. Response contains the CustomerCCId created.
- CustomerId - Optional.
- If supplied, must reference a valid Customer. If CustomerNumber is also supplied, both must reference the same Customer.
- If not supplied, CustomerNumber must be supplied.
- CustomerNumber - Optional.
- If supplied, must reference a valid Customer. If CustomerId is also supplied, both must reference the same Customer.
- If not supplied, CustomerId must be supplied.
- Customer_Name - Ignored. Response contains the customer’s name.
- CardType - Optional, but it should match the card type submitted to the payment processor.
- If supplied, must contain one of the following:
- VISA
- MAST
- DISC
- AMER
- DINE
- If not supplied, PaymentMethodId and/or PaymentMethodCode must be supplied and the CardType will be set according to the payment method. Note that once this is set, it cannot be changed via an update, as it is directly linked to the ACHDirectToken (which also cannot be changed). Under normal circumstances, the CardType should be explicitly included so there is no mistake in its value.
- If supplied, must contain one of the following:
- CardTypeDescription - Ignored. Response contains the card type description.
- CardNumber - Ignored and will always be empty in the database. This information is determined by the ACHDirectToken.
- ExpirationMonth - Required and must have a value from 1 to 12 (a leading zero for months 1 to 9 is ok). Should match the expiration month submitted to the payment processor. This cannot be changed by an update.
- ExpirationYear - Required and must be a valid number greater than or equal to zero. If more than 2 digits is supplied, only the last 2 digits are used. Should match the expiration year submitted to the payment processor. This cannot be changed by an update.
- AccountName - The account name should be able to be determined by the ACHDirectToken, but if it cannot be, the value supplied here will be used. If this is not supplied, the customer's Bill To name will be used.
- PaymentMethodId - Optional.
- If supplied, it must reference a valid payment method. If PaymentMethodCode is also supplied, both must reference the same payment method.
- If not supplied, PaymentMethodCode must be supplied.
- PaymentMethodCode - Optional.
- If supplied, it must reference a valid payment method. If PaymentMethodId is also supplied, both must reference the same payment method.
- If not supplied, PaymentMethodId must be supplied.
- If neither PaymentMethodId nor PaymentMethodCode is supplied, CardType must be supplied and the payment method will attempt to be set based on that.
- Note about payment method: The payment method does not necessarily need to be a credit card type. Although perhaps unexpected behavior, the SO client allows that, so the API does the same. However, if the CardType is not supplied, it will be set based on the payment method, so in that case the payment method must be a credit card type or an error will be generated.
- CustomerAddress - Optional. Should be the address submitted to the payment processor. If not supplied, the customer's Bill To address will be used.
- CustomerPostalCode - Optional. Should be the postal code submitted to the payment processor. If not supplied, the customer's Bill To postal code will be used.
- SecurityCode - Deprecated property - Ignored and will always be empty in the database. This information is determined by the ACHDirectToken.
- UsedForAutoProcess - See explanation below under " Common Properties ".
- AutoProcessDay - Optional, set to 1 if not supplied or value < 1 is supplied. This specifies the day of the month on which auto recurring charges will be processed. This cannot be greater than 28.
- LastFourDigits - The last four digits of the credit card. This is optional, but it should be included for easier identification of the credit card.
- ACHDirectToken - Required. This is the token created by the payment processor. This cannot be changed by an update.
- UsedForNonRecurAuto - See explanation below under " Common Properties ".
- MaxNonRecurAmount - Optional, set to zero if not supplied or value < 0 is supplied or UsedForNonRecurAuto is false.
- MerchantId - Essentially ignored. The appropriate MerchantId will be obtained from the customer's ACH provider. The response will have the MerchantId populated.
- DaysPastInvoiceToHold - Optional, set to zero if not supplied or value < 0 is supplied or UsedForAutoProcess is false.
- CustomerBillId - Optional, set to 1 if not supplied or value < 1 is supplied or UsedForAutoProcess is false. If this credit card should be used to auto pay the recurring of only a specific Bill To, that Id should be supplied; otherwise leave empty or set to 1.
- CustomerBillBusinessName - Ignored. The response will have this populated.
PUT api/paymentmerchant/addcreditcard: - CustomerCCId - Must be supplied and reference the Customer CC record being updated.
- CustomerId - Ignored. The customer to which a credit card entry applies cannot be changed.
- CustomerNumber - Ignored. The customer to which a credit card entry applies cannot be changed.
- CardType - Ignored. The card type cannot be changed because it is determined by the ACHDirectToken.
- ExpirationMonth and ExpirationYear - Ignored. Expiration cannot be changed because it is determined by the ACHDirectToken.
- ACHDirectToken - Ignored. The token cannot be changed because it defines the credit card.
The remaining fields are processed as follows:
- Any field supplied as 'null' will retain its existing value in the database. Regarding multiple fields referencing the same entity, such as PaymentMethodId / PaymentMethodCode, all fields must be null to retain the existing value - if *any* of the fields are supplied, it means that an update is desired.
- Any field with a supplied value will update the specified Customer CC record according to the rules described in POST.
Common Properties
- UsedForAutoProcess - Optional, set to false if not supplied. This specifies if the bank account or credit card will be used to automatically pay recurring charges. If a bank account or credit card is added or updated with this "true", any other credit card or bank account of the customer, currently marked as "UsedForAutoProcess" for the same Customer Billing Id, will be set to "not used". Note that a specific Billing Id can be specified when this is true. If the Billing Id is 1, the bank account or credit card applies to all bill-to's that don't have their own Auto Process defined. Each bill-to of the customer can have its own Auto Process defined if so desired.
- UsedForNonRecurAuto - Optional, set to false if not supplied. This specifies if the bank account or credit card will be used to automatically pay non-recurring charges. If a bank account or credit card is added or updated with this "true", any other credit card or bank account of the customer, currently marked as "UsedForNonRecurAuto", will be set to "not used". Note that only one bank account or credit card of the customer can be marked as "UsedForNonRecurAuto", regardless of the Billing Id.
- PrintCycleInvoices - Optional. Not used to add/update a bank account or credit card itself. If true or false is supplied during an add or update, the customer's "Print Cycle Invoices" option will be set accordingly. The "add" response will contain the customer's current setting.
