Skip to main content
Aria Knowledge Central

update_payment_method_m Guide

This API allows you to update payment method-related information associated with an account. This information includes:

  • Billing Contact Information: Update, or completely replace, the billing contact associated with a payment method. You can either specify new contact information; or, replace the contact information with another contact already associated with the account, specified by a bill_contact_no.
  • Payment Method: You can update or replace a payment method by specifying a pay_method_type, then supplying the new payment method information.
  • Payment Method Name and Description: When updating or replacing a payment method as described above, you can also replace the Payment Method Name and/or Description.
API Specification: update_payment_method_m
Required Fields:
  • <client_no>
  • <auth_key>
  • <acct_no> or <client_acct_id>

Error Codes

Error Code/Description Associated Inputs

1001: unexpected error


 

1004: authentication error

Associated Inputs: auth_key, client_id, client_no


 

1016: invalid input, acct_no: (acct_no) is not a valid long, assignment_directive: (assignment_directive) is not a valid long, “billing_group_no: (billing_group_no) is not a valid long, threshold_billing_rule_no: (threshold_billing_rule_no) is not a valid long

Associated Inputs: alt_service_no_to_apply, assignment_directive, auto_skip_to_next_bill_date, client_billing_group_id, custom_rate_service_no/custom_rate_client_service_id, plan_instance_no, plan_instance_service_no, client_plan_instance_id, client_plan_instance_service_id, plan_instance_no, plan_instance_service_no, client_plan_instance_id, client_plan_instance_service_id, plan_instance_service_no, eligible_plan_no, eligible_service_no, email, force_master_bill_date_reset, fulfillment_only, include_master_plans, include_supp_plans, include_billing_groups, include_payment_methods, include_master_plans, include_supp_plans, include_billing_groups, include_payment_methods, invoice_no, length_months, end_date, limit, limit_records, modify_directive, contract_plan_instances_update, modify_directive, contract_plan_instances_update, offset, percent_amount, percent_eval_plan_instance_no, client_percent_eval_plan_instance_id, percent_eval_service_no, client_percent_eval_service_id, phone_ext, work_phone_ext, plan_unit_inst_status_cd, plan_units, reason_code, start_date, end_date, start_date, end_date, status_cd, acct_no, assignment_directive, billing_group_no, threshold_billing_rule_no

Additional Comments:  This error can be caused by the wrong type of input, for example, text in a numbers-only field, an  or specifying a value other than one of the documented allowable values.

  • For the get_order_m API, this is the error code returned when the user passes an invalid order value for the <status_filter_cd> input which is other than the allowed values (0/null, 1, 2, 3, 4 and 5).
  • For the bulk_cancel_order_m API, invalid input can occur with the <order_status_directive> argument. Allowed values are 0, 1, 2, 3, 4/null, 5 and 6.
  • For the get_acct_coupon_details_m API, invalid input can occur with the <include_all_active> input parameter (values are 0, 1 or NULL).

Alternate Message Output

1016: username cannot be longer than 30 characters
1016: first_name cannot be longer than 30 characters
1016: last_name cannot be longer than 30 characters

Associated APIs: create_user_m, update_user_m

Associated Inputs: username, first_name, last_name


 

1024: invalid date format

Associated Inputs: bill_birthdate, birthdate, degrade_date, initial_credit_date, invoice_line_reversing_date, service_fulfillment_date, queue_date, start_bill_date, end_bill_date, start_date, end_date, stmt_birthdate, bill_birthdate

Additional Comments: All date inputs must be in yyyy-mm-dd format.


 

1033:  a parameter that represents a true or false value contains invalid input

Associated Inputs: alt_collect_on_approve, alt_send_statement_on_approve, cancel_orders_on_discard, cascade_action, do_auto_discard, do_collect, change_status_after_coll, reset_dates_after_status, disable_existing_on_update, do_write, exclude_terminated_plan_inst, include_all_rate_schedules, include_plan_hierarchy, retrieve_bundled_nso, retrieve_included_nso, include_translations, include_inactive_items, include_invoice_activity_eligibility, include_rs_summary, include_translations, include_service_supp_fields/include_product_fields/, include_plan_instance_fields/include_plan_services/, include_surcharges, include_void_transactions, include_voided, invoice_unbilled_usage, is_unlinked_refund, record_cc_on_auth_failure, retrieve_excluded_usage, send_email, usage_pooling, do_write


 

1066: Locale name does not exist in the system.

Associated Inputs: locale_name


 

1067: Locale no does not exist in the system.

Associated Inputs: locale_no, master_plan_instance_no


 

1500: Unsupported bank/country code for this payment method.

Associated Inputs: proc_status_code, proc_status_code, bank_country_cd

Additional Comments: Added in support of ACH payments via Direct Debit (country code must be US).


 

4006: invalid pay method or alternate pay method

Associated Inputs: alt_pay_method, pay_method_type, pay_method_type


 

4008: invalid expiration date

Associated Inputs: alt_pay_method, cc_expire_mm, cc_expire_yyyy, credit_expiry_date, pay_method_type

Additional Comments: Dates must be in yyyy-mm-dd format.


 

4009: invalid cc number

Associated Inputs: cc_number, alt_pay_method, cc_num, pay_method_type


 

4010: invalid bank draft info

Associated Inputs: bank_acct_no, bank_routing_no, alt_pay_method

Additional Comments:

  1. The client parameter BANK_DRAFT_INDICATOR must be enabled.
  2. Bank_acct_no and bank_routing_no are required.
  3. Valid bank_routing_no from Aria's ABA lookup in case of US address.
  4. Bank_routing_no must be numeric.
  5. For US, bank_routing_no should be 9 digits in length (left padded with zeros).
  6. Bank_routing_no must pass checksum validation.

 

4011: cc authorization failed

Associated Inputs: alt_pay_method, cc_number, cc_expire_mm, cc_expire_yyyy, pay_method_type

Additional Comments: $1 authorization has failed.


 

4017: duplicate payment method client defined id.

Associated Inputs: client_payment_method_id, new_client_payment_method_id

Additional Comments: This value must be unique at the client level.


 

4019: Invalid Bank Account Type.

Associated Inputs: alt_pay_method, bank_acct_type


 

4022: invalid cc id

Associated Inputs: pay_method_type, cc_id


 

4023: The payment method provided is currently associated with a billing group and cannot be disabled. Either remove the payment method from the billing group before disabling it, or call the remove_acct_payment_method_m API to remove that payment method from the account.

Associated Inputs: disabled_ind, payment_method_no, client_payment_method_id


 

4032: cc_id is required.

Associated Inputs: cc_id, pay_method_type

Additional Comments: cc_id is required for this payment processor.


 

4044: Missing a required value. Please check that either bank_account_no, bank_routing_number or agreement_id is present.


 

5017: invalid iso country code

Associated Inputs country, bank_country_cd, bill_country


 

5018: account in uneditable status

Additional Comments: If the account is in an archived state, edit is not allowed.


 

6003: could not validate billing information

Associated Inputs: pay_method_type, cc_auth_amount

Additional Comments: There was an error during the $1 authorization attempt.


 

6021: Invalid state_prov entered

Associated Inputs: bill_state_prov, state_prov, stmt_state_prov, bill_state_prov


 

6027: IBAN is alphanumeric and is 16 to 34 characters in length

Associated Inputs:  iban, alt_pay_method_iban


 

6029: Bank swift code is alphanumeric and is 8 or 11 characters in length

Associated Inputs: bank_swift_cd, alt_pay_method


 

6031: BBAN is numeric and up to 16 digits

Associated Inputs: alt_payment_method, bank_acct_no


 

6032: Bank ID code is numeric and up to 10 digits


 

6033: Bank branch code is numeric and up to 10 digits

Associated Inputs: bank_branch_cd


 

6034: Basic bank account number or IBAN is required for Direct Debit

Associated Inputs: iban, bank_acct_no


 

6045: Account can have only one active NETS payment method.

Associated Inputs: payment_method_type


 

6053:Either IBAN or Agreement ID is required for this payment method. 

Associated Inputs: iban, bill_agreement_id, pay_method_type, alt_pay_method


 

14053: Invalid Master Plan Instance number

Associated Inputs: master_plan_instance_no


 

14054: Invalid client Master Plan Instance identifier

Associated Inputs: client_master_plan_instance_id


 

14121: Include Master Plan Instances in order to retrieve Supplemental Plan instances.

Associated Inputs: include_master_plans, include_supp_plans

Additional Comments:  You must include Master Plans when retreiving suplemental Plans.


 

20026: agreement id OR credit card info is required

Associated Inputs: pay_method_type, bill_agreement_id, cc_num

Additional Comments: The pay_method_type is "13", the bill_agreement_id is null and cc_num is null.


 

25020: Illegal characters entered

Associated Inputs: All character field inputs like firstname lastname, dunning_group_name, comments, etc.


 

25023: Primary payment method is required.

Associated Inputs: pay_method_type, pay_method_name, client_pay_method_cdid,bill_agreement_id

Additinal Comments: There must be a primary pay method before setting up a secondary pay method. When the primary pay method is removed, then the secondary becomes primary.


 

25025: Backup pay method cannot be different than primary pay method

Associated Inputs: new pay_method_type, primary_payment_method_no, backup_payment_method_no, client_primary_payment_method_id, client_backup_payment_method_id


 

25026: Primary pay method cannot be different than backup pay method

Associated Inputs: new pay_method_type, primary_payment_method_no, backup_payment_method_no, client_primary_payment_method_id, client_backup_payment_method_id


 

25027: Provided payment method is not a credit card

Associated Inputs:cc_expire_yyyy, cc_expire_mm, pay_method_type

Additional Comments: expiry date can be modified only for credit card.


 

25028: Provided payment_method_id is already in a disabled state.

Associated Inputs: payment_method_type, payment_method_no, client_payment_method_id


 

25042: The expiration date for tokenized credit cards cannot be edited as that information is provided by the payment processor.

Associated Inputs: cc_expire_yyyy, cc_expire_mm, payment_method_no, client_payment_method_id


 

25043: Primary payment method does not support secondary pay method.

Associated Inputs: new pay_method_type, primary_payment_method_no, backup_payment_method_no, client_primary_payment_method_id, client_backup_payment_method_id, pay_method_type

Additional Comments: The primary_client_payment_method_id is not 1, 2, or 13) and the backup_client_payment_method_id is not null.


 

25044: Secondary payment method type must match the primary.

Associated Inputs: new pay_method_type, primary_payment_method_no, backup_payment_method_no, client_primary_payment_method_id, client_backup_payment_method_id

Additional Comments: The backup_client_payment_method_id is not 1, 2, or 13.


 

26004: Include billing groups in order to retrieve payment methods.

Associated Inputs: include_billing_groups, include_payment_methods


 

26007: Provided client defined pay method ID does not exist for this account.

Associated Inputs: client_payment_method_id, client_primary_payment_method_id, client_backup_payment_method_id


 

26008: Provided payment_method_id does not exist for this account.

Associated Inputs: payment_method_no, payment_method_no, client_payment_method_id, primary_payment_method_no, backup_payment_method_no


 

26010: Invalid billing group number

Associated Inputs: billing_group_no


 

26012: Invalid client-defined billing group ID.

Associated Inputs: client_billing_group_id


 

29005: The contact number provided is invalid for the specified account.

Associated Inputs: acct_contact_no, bill_contact_no, stmt_contact_no


 

Additional Guidance

Inputs passed to this API call will override any fraud options that you specified in your payment gateway, collection group, or Direct Post settings, unless stated otherwise below.

Input Fields
Field Name: Notes:
<payment_method_no>

The same pay method sequence number cannot be used for a primary and secondary payment method.

<cc_auth_amount>

To authorize a tokenized credit card:

  • For the Braintree payment gateway, complete the required Aria configuration fields.
  • For the Worldpay payment gateway, first add the client_acct_id to the account as described in the Worldpay configuration notes.

Do one of the following:

  • If the card has already been added to the account, pass in the <payment_method_no>; or
  • If the token was already generated outside of Aria, set the <pay_method_type> to 13 and pass in the <bill_agreement_id>; or
  • If you need to generate a token for the card, set the <pay_method_type> to 13 and pass in the credit card details.
  • Pass in the <cc_auth_amount> to be authorized.

Please contact your payment gateway representative for more information.

  • <alt_client_collection_acct_group_id>
  • <alt_collection_acct_group_no>
It is possible to have an account with more than one payment method with an agreement ID obtained outside of Aria with a collection group that is mapped with more than one billing group. When this input argument is used to pass a token outside Aria this API will validate the agreement ID against the collection group. When no collection group is passed as an input via API, then the agreement ID will be validated against the account level collection group. If there is no collection group at the account level, then the agreement ID is validated against the last processor mapped to that client.
<fraud_filter>

If you set this field to "0", then Aria will ignore all other fraud filtering fields.

If you set this field to "1", then Aria will apply the values that you specified in the other fraud filtering fields. However, if you pass "-1" into any fraud filtering field, Aria will ignore that field.

If you set this field to "2", then Aria will apply the values that you specified in the other fraud filtering fields.

<recurring_processing_model_ind>

Currently, for only the Vantiv payment gateway, the value in this field will automatically be set to 2 if your payment gateway or collection group configuration has the Send orderSource as recurring for all transactions option enabled.

Refer to your payment gateway documentation to see if this applies.

Please contact your payment gateway representative for more information.

<attempt_3d_secure>

This will manually trigger a 3DSecure check if the payment gateway/processor supports this feature.

<disabled_ind>
Allowable Values
Values Description
0 Payment will remain enabled
1 Payment will be disabled
<pay_method_type>
Allowable Values
Values Description
-1 External Payment
1 Credit card
2 Electronic Check (ACH)
3 Pre-paid
4 Net terms 30
5 Net terms 10
6 Net terms 15
7 Net terms 60
8 Click&Buy
9 Net Terms 0
10 PayByCash
11 PayPal Express Checkout
12 Net Terms 45
13 Tokenized Credit Card
14 Purchase Power
15 Net Terms 35
16 Net Terms 75
17 Net Terms 90
18 Net Terms 120
19 Net Terms 25
20 NETS
26 Direct Debit
37 Tokenized Direct Debit
40 Merchant-Specific Gift Card
48 Tokenized ACH
<bank_acct_type>
Allowable Values
Values Description
savings savings
checking checking
business business
<do_collect>
Allowable Values
Values Description
true true
false false
<change_status_after_coll>
Allowable Values
Values Description
0 Do not reset the MPI status to active
1 Reset the MPI status to active when its current status is any non-active status.
2 Reset the MPI status to active only when its current status "Suspended" (default).
3 Reset the MPI status to active only when its current is either "Suspended" or "Terminated"
<reset_dates_after_status>
Allowable Values
Values Description
true true
false false
<cc_id>
Allowable Values
Values Description
1 Visa
2 MasterCard
3 American Express
4 Discover
5 Diners Club/Carte Blanche
6 Maestro
7 JCB
8 Laser
9 Dankort
10 Aura
11 ELO
12 Hipercard
13 UnionPay Express Pay

Note: <cc_id> is sometimes a required field when using payment method 13, Tokenized Credit Card, as the <pay_method_type> field for certain payment processors as defined in the internal Aria processor pay methods table. 

<disable_existing_on_update>
Allowable Values
Values Description
true true
false false
<fraud_filter>
Allowable Values
Values Description
0 false (disable)

Note: If you set this field to 0, then Aria will ignore all other fraud filtering fields.

1 true (enable)

Note: If you set this field to 1, then Aria will apply the values that you specified in the other fraud filtering fields. However, if you pass -1 into any fraud filtering field, Aria will ignore that field.

2 Use settings specified at the collection group or payment gateway level.

Note: If you set this field to 2, then Aria will apply the values that you specified in the other fraud filtering fields.

<fraud_filtering_enabled>
Allowable Values
Values Description
0 disable
1 enable
-1 Use settings specified at the collection group or payment gateway level.
<change_status_on_fraud_filtering_failure>
Allowable Values
Values Description
0 false
1 true
-1 Use settings specified at the collection group or payment gateway level.
<change_status_on_fraud_filtering_review>
Allowable Values
Values Description
0 false
1 true
-1 Use settings specified at the collection group or payment gateway level.
<change_mp_status_on_fraud_filtering_cc_prefix_failure>
Allowable Values
Values Description
0 false
1 true
<change_mp_status_on_fraud_filtering_cc_number_failure>
Allowable Values
Values Description
0 false
1 true
<change_mp_status_on_fraud_filtering_cc_issuing_country_failure>
Allowable Values
Values Description
0 false
1 true
<change_mp_status_on_fraud_filtering_cc_issuing_country_suspect>
Allowable Values
Values Description
0 false
1 true
<include_auth_results>
Allowable Values
Values Description
0 Do not return authorization attempt results
1 Return authorization attempt results
<perform_marketing_insights_inquiry>
Allowable Values
Values Description
NULL or -1 (Default) Use client-defined settings
0 Do not return
1 Return
<perform_balance_inquiry>
Allowable Values
Values Description
0 (default) False, do not return card balance.
1 True, do not return card balance.
<perform_card_type_detail_inquiry>
Allowable Values
Values Description
-1 Use Client Defined Settings (Default)
0 Do Not Return
1 Return
<recurring_processing_model_ind>
Allowable Values
Values Description
0 Cardholder-Initiated Transaction – Credentials on File: a credit card transaction initiated by the cardholder for a new order or a plan upgrade that uses a credit card that is currently stored in Aria. (Default)
1 Cardholder-Initiated Transaction: a credit card transaction initiated by the cardholder for a new account or creating an order that uses an alternate credit card that is not currently stored in Aria.
2 Merchant-Initiated Transaction – Standing Instruction – Recurring: a credit card transaction initiated by Aria’s clients for a recurring charge that uses a credit card that is currently stored in Aria.
3 Merchant-Initiated Transaction – Unscheduled Credentials on File: a credit card transaction initiated by Aria’s clients for a non-recurring charge (one-time order or plan upgrade) that uses a credit card that is currently stored in Aria.
<attempt_3d_secure>
Allowable Values
Values Description
null This will let processor to dynamically decide whether 3DS is required based on their rules. (Default)
true Attempt 3DS authentication.
false Do not attempt 3DS authentication.
<transaction_type>
Allowable Values
Values Description
-1 Use client configuration settings for "Send Transaction Type as Recurring for Initial Request Where Possible" or "Send Transaction Type as Recurring for Subsequent Request" as applicable. (default)
1 (Chase) Single transaction mail/telephone order (MOTO) - Designates a transaction where the accountholder is not present at a merchant location and completes the sale over the phone or through the mail. The transaction is not for recurring services or products and does not include sales that are processed via an installment plan.
2 (Chase) Recurring Transaction - Designates a transaction that represents an arrangement between an accountholder and the merchant where transactions are going to occur on a periodic basis.
3 (Chase) Installment Transaction - Designates a group of transactions that originated from a single purchase where the merchant agrees to bill the accountholder in installments.
4 (Chase) Deferred Transaction - Designates a transaction that represents an order with a payment delayed for a specified amount of time.
5 (Chase) Secure Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant and in which the accountholder was fully authenticated. (examples: 3-D Secure includes Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy.)
6 (Chase) Non-Authenticated Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant that attempted to authenticate the accountholder using 3-D Secure (examples: 3-D Secure includes Verified by Visa and Mastercard Identity Check.) Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy transactions in the event of: * A non-participating issuer * A non-participating accountholder of a participating issuer * A participating issuer, but the authentication server is not available
7 (Chase) Channel Encrypted Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where the transaction includes the use of transaction encryption such as SSL (Secure Sockets Layer), but authentication was not performed. The accountholder payment data was protected with a form of Internet security, such as SSL, but authentication was not performed. For Discover, indicates an e-commerce Card Transaction with data protection in which ProtectBuy for Cardholder authentication was not used.
8 (Chase) Non-Secure Electronic Commerce Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where: * The transaction does not include the use of any transaction encryption such as SSL * Authentication is not performed * An accountholder certificate is not managed.
I (Chase) IVR Transaction (PINless Debit only) - Designates a transaction where the accountholder completes the sale via an interactive voice response (IVR) system.
R (Chase) Retail Transaction - Designates a transaction where the accountholder was present at a merchant location.
telephone (Vantiv) The transaction is for a single telephone order.
mailorder (Vantiv) The transaction is for a single mail-order transaction.
<payer_auth_transaction_mode>
Allowable Values
Values Description
M MOTO (mail/telephone order)
R Retail
S eCommerce
P Mobile Device
T Tablet
<disable_pmt_method_on_auth_failure>
Allowable Values
Values Description
false (default) Disable a payment method after a failed card authorization.
true Enable a payment method after a failed card authorization.
  • Was this article helpful?