Developer Resources
ChargePaymentFraudRequest
Conditional.
Use the ChargePaymentFraudRequest API to connect to our Payment Protect product. This API will support both preauthorization and postauthorization implementations based on whether you include authorization result parameters.
ChargePaymentFraudRequest evaluates the risk associated with a transaction and responds with a risk score plus up to five insights into that score when you are enrolled in Payment Protect.
Note: This API may also be used for a single-step Payment Guarantee integration in postauthorization (authorization result parameters are required for this case).
Use the ChargePaymentFraudRequest API if you have already authorized the transaction with your gateway/acquirer and received the authorization results. Otherwise, use the ChargePaymentRequest API.
ChargePaymentFraudRequest determines the risk associated with the transaction and checks if it can be guaranteed before deciding to settle or cancel the transaction.
Note: This API acts as a combination of the ChargePaymentRequest and AuthResult APIs. Authorization results from your gateway/acquirer must be provided to use this API.
Request Parameters
Use the following request parameters when integrating to ChargePaymentFraudRequest:
AccountHolderAddressLine1 (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The cardholder's address, line 1. Required when AccountNumberIndicator=4 and to guarantee a transaction unless explicitly exempted by our platform.
Maximum Length: 30
AccountHolderAddressLine2Data Type: String
Field Dependence: Optional
Sensitive: No
Description: The cardholder's address, line 2.
Maximum Length: 30
AccountHolderCity (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The cardholder’s city. Required to guarantee a transaction unless explicitly exempted by our platform.
Maximum Length: 30
AccountHolderCountryCode (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The cardholder’s two-character country code. Use the ISO-3166 official country codes. Required to guarantee a transaction unless explicitly exempted by our platform.
Maximum Length: 2
AccountHolderFirstName (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The cardholder’s first name. Required to guarantee a transaction unless explicitly exempted by our platform.
Maximum Length: 20
AccountHolderLastName (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The cardholder’s last name. Required to guarantee a transaction unless explicitly exempted by our platform.
Maximum Length: 20
AccountHolderPostalCode (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The cardholder’s ZIP or postal code. Required when AccountNumberIndicator=4 and to guarantee a transaction unless explicitly exempted by our platform.
Maximum Length: 10
AccountHolderRegion (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The cardholder’s region name. For U.S. addresses, use the two-character state code. Required to guarantee a transaction unless explicitly exempted by our platform.
Maximum Length: 30
AccountName (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: API username.
Maximum Length: 32
AccountNumber (Required)Data Type: String
Field Dependence: Required
Sensitive: Yes
Description: The credit/debit card number, token or the BIN plus Last4 of the credit/debit card number/ApplePay Encrypted Payment Token to be authorized. If AccountNumberIndicator=4, then the value entered must be either 10 digits or 4 digits: BIN = First 6 digits of the credit/debit card number and Last4 = Last 4 digits of the credit/debit card number.
Maximum Length: 19
AccountNumberIndicator (Required)Data Type: Integer
Field Dependence: Required
Sensitive: No
Description: The type of account number being sent to the API.
Maximum Length: 1
Possible Values:
1 - Credit card (credit card number)
2 - Temporary token
3 - Permanent token
4 - BIN + Last4
5 - ApplePay Encrypted Payment Token
AcquirerAVSResultCodeData Type: String
Field Dependence: Optional
Sensitive: No
Description: The result of your acquirer's address verification system (AVS) check.
Maximum Length: N/A
AcquirerAVSResultCode (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The result of your acquirer's address verification system (AVS) check. Required unless explicitly exempted by our platform.
Maximum Length: N/A
AcquirerAuthResultCodeData Type: String
Field Dependence: Optional
Sensitive: No
Description: The result from the authorization transaction.
Maximum Length: N/A
AcquirerAuthResultCode (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The result from the authorization transaction.
Maximum Length: N/A
AcquirerCD (Required)Data Type: Integer
Field Dependence: Required
Sensitive: No
Description: The acquirer used to authorize a transaction.
Maximum Length: N/A
Possible Values:
1 - Chase Paymentech
2 - FirstData
3 - AIB
4 - Vantiv
5 - RapidConnectCNP
6 - Synthesis
7 - TSYS
8 - ProPay
9 - Allpago
1000 - Braintree
1001 - TrustCommerce
1002 - Authorize.Net
1003 - Wells Fargo
1004 - PayKings
1005 - Credibanco
1006 - Card Connect
1007 - Stripe
AcquirerCVVResultCodeData Type: String
Field Dependence: Optional
Sensitive: No
Description: The result of your acquirer's card verification value (CVV) check.
Maximum Length: N/A
AcquirerCVVResultCode (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The result of your acquirer's card verification value (CVV) check. Required unless explicitly exempted by our platform.
Maximum Length: N/A
Amount (Required)Data Type: Currency
Field Dependence: Required
Sensitive: No
Description: The amount of money sent for authorization.
Maximum Length: 12
AppealEligibleData Type: Boolean
Field Dependence: Conditional
Sensitive: No
Description: Indicates if the transaction is declined by the bank and eligible for a Bank Decline appeal.
Maximum Length: N/A
Possible Values:
0 - Not eligible
1 - Eligible for Bank Decline Appeal
AutoDispositionData Type: Boolean
Field Dependence: Conditional
Sensitive: No
Description: Indicates if the transaction uses one step (post-authorization) or two step (pre-authorization and post-authorization) request processing.
Maximum Length: N/A
Possible Values:
0 - Two step ChargePaymentFraudRequest, Disposition
1 - One step ChargePaymentFraudRequest, Disposition
CVVData Type: Numeric
Field Dependence: Conditional
Sensitive: Yes
Description: The credit/debit card security code (e.g., CVV2 for MC and Visa or CID for American Express). If PaymentSource=PPD, this field is not required.
Maximum Length: 4
CreatedByUserData Type: String
Field Dependence: Optional
Sensitive: No
Description: The fraud or Revenue Assurance (RA) gateway user account name.
Maximum Length: 128
ExpirationMMYY Data Type: Numeric
Field Dependence: Conditional
Sensitive: Yes
Description: The credit/debit card expiration date. Required when AccountNumberIndicator=4. The format is MMYY.
Maximum Length: 4
MerchantRoutingID (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The identification number associated with the merchant account.
Maximum Length: 20
PartnerCustomerKeyData Type: String
Field Dependence: Optional
Sensitive: No
Description: The unique data element created to identify a customer, such as a billing account number.
Maximum Length: 64
Password (Required)Data Type: String
Field Dependence: Required
Sensitive: Yes
Description: API password.
Maximum Length: 64
PaymentDescriptorData Type: String
Field Dependence: Optional
Sensitive: No
Description: The description of the transaction. Used for tracking purposes and to identify the transaction when contacting Support.
Maximum Length: 128
PaymentSource (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The source of the transaction.
Possible Values:
PPD - Use this to specify that the transaction has been prearranged. This is used when the credit/debit card number has been validated or already had a successful charge against it. When this option is used, the CVV is not required.
TEL - Use this to specify that the transaction has been taken over a telephone through a call center or interactive voice response (IVR) system.
WEB - Use this to specify that the transaction has been taken over the Web, the mobile Web, a native mobile application, or a hybrid-mobile application.
ReportingInformationData Type: String
Field Dependence: Optional
Sensitive: No
Description: The attribute-based XML blob that contains information the merchant wishes to report on for the specific transaction. The information does not affect processing. It is passed through to use in reporting and PRT search functionality.
Maximum Length: 3000
RiskInformation (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The XML string containing risk-related data. See the Risk Information XML and contact your Integration Specialist for details.
Maximum Length: N/A
StoreCardData Type: Boolean
Field Dependence: Optional
Sensitive: No
Description: Indicates if the credit/debit card number needs to be exchanged for a permanent token.
Maximum Length: N/A
Possible Values:
0 - Do not exchange card number for a permanent token
1 - Exchange card number for a permanent token
TransactionID (Required)Data Type: String
Field Dependence: Required
Sensitive: No
Description: The unique identification number used to track the transaction.
Maximum Length: 36
WebSessionIDData Type: String
Field Dependence: Conditional
Sensitive: No
Description: The WebSessionID generated by the GetSessionTags API for the current transaction. This is used for device fingerprinting.
Maximum Length: 4000
Response Parameters
ChargePaymentFraudRequest returns the following response parameters:
CardFirst6Data Type: Numeric
Sensitive: No
Description: Returns the first six digits of the credit/debit card number processed.
Maximum Length: 6
CardLast4Data Type: Numeric
Sensitive: No
Description: Returns the last four digits of the credit/debit card number processed.
Maximum Length: 4
CardTypeCDData Type: Integer
Sensitive: No
Description: Returns the issuer type for the credit/debit card number processed.
Maximum Length: N/A
Possible Values:
1 - AAFEES
3 - American Express
4 - Visa
5 - MasterCard
6 - Discover
7 - Diners Club
9 - Carte Blanche
25 - Dankort
27 - Electron
34 - Lasercard
35 - Maestro
98 - Unknown
IsPaymentGuaranteeableData Type: Boolean
Sensitive: No
Description: Returns whether our platform can guarantee the transaction.
Maximum Length: N/A
Possible Values:
0 - Payment cannot be guaranteed
1 - Payment can be guaranteed
IsShadowPaymentData Type: Boolean
Sensitive: No
Description: Returns whether the transaction is a shadow payment (not actually guaranteed).
Maximum Length: N/A
Possible Values:
1 - This is a shadow payment and so not actually guaranteed.
PartnerCustomerKeyData Type: String
Sensitive: No
Description: Returns the unique data element for identifying a customer.
Maximum Length: 64
PaymentGuaranteeStatusData Type: Integer
Sensitive: No
Description: Returns our platform's decision to guarantee the payment.
Maximum Length: N/A
Possible Values:
1 - Guaranteed payment
2 - Non-guaranteed payment
PaymentIDData Type: String
Sensitive: No
Description: Returns the identification number to track the transaction.
Maximum Length: 12
PaymentStatusData Type: Integer
Sensitive: No
Description: Returns the result of the authorization transaction.
Maximum Length: N/A
Possible Values:
1 - Bank denied.
2 - Pending. This can occur if Vesta has determined that additional insight could help determine the risk of this transaction. See the response parameter PendResolutionMethods for the resolution method that was used for the transaction.
10 - Successful payment.
21 - Bank Denied, pending appeal.
52 - Post-Authorization completed.
62 - Post-Authorization communication error. The transaction did not complete. Re-run the transaction. If the problem persists, contact Support.
PendResolutionMethodData Type: Integer
Sensitive: No
Description: The method Vesta used to gather additional insights on the transaction to resolve the Pending status.
Maximum Length: N/A
Possible Values:
20 - Silent Pending. See Silent Pending.
21 - Manual Review. See Manual Review.
PermanentTokenData Type: String
Sensitive: No
Description: Returns a permanent token for the credit/debit card number when StoreCard=1.
Maximum Length: 19
ResponseCodeData Type: Integer
Sensitive: No
Description: Returns a 0 for success or a non-zero code for failure to process the API. See Response Codes for the possible non-zero code returned by the ChargePaymentFraudRequest API.
Maximum Length: N/A
ResponseTextData Type: String
Sensitive: No
Description: Returns a description for non-zero Response Codes.
Maximum Length: 1024
RiskDecisionCodeData Type: Integer
Sensitive: No
Description: Returns the decision code from the decision engine when the transaction is denied or pended.
Maximum Length: N/A
Possible Values:
1701 - Score exceeds risk system thresholds.
1702 - Insufficient information for risk system to approve.
1703 - Insufficient checking account history.
1704 - Suspended account.
1705 - Payment method type is not accepted.
1706 - Duplicate transaction.
1707 - Other payment(s) still in process.
1708 - SSN and/or address did not pass bureau validation.
1709 - Exceeds check amount limit.
1710 - High risk based upon checking account history (EWS).
1711 - Declined due to ACH regulations.
1712 - Information provided does not match what is on file at bank.
RiskDecisionCodeTextData Type: String
Sensitive: No
Description: Returns the description of the decision code from the decision engine when the transaction is denied or pended.
Maximum Length: N/A
RiskProbabilityIndexData Type: Integer
Sensitive: No
Description: Returns the level of risk associated with accepting the requested transaction.
Maximum Length: N/A
Possible Values:
1 - High Risk
2 - Mild Risk
3 - Average
4 - Safe
5 - Very Safe
RiskScoreData Type: Integer
Sensitive: No
Description: Returns the risk score associated with the transaction. Valid values are 0-100; the higher the score, the greater the fraud risk associated with the transaction. This score is only presented if the Fraud Score feature is enabled.
Maximum Length: N/A
RiskSystemDecisionData Type: DataSet
Field Dependence: Conditional
Sensitive: No
Description: The set of risk decision codes and associated text.
Child Parameters:
RiskSystemDecisionCDData Type: Numeric
Field Dependence: Conditional
Sensitive: No
Description: The risk decision code provided by the fraud engine.
Maximum Length: 10
DescriptionData Type: String
Field Dependence: Conditional
Sensitive: No
Description: The description of the risk decision code.
Maximum Length: 1024
Response Codes
Each API call returns a numeric response code. If the response code is zero, the API transaction completed successfully without errors; however, the status of the transaction may not be complete. If the response code is non-zero, an error message is included with the response code.
Note: When non-zero response codes are returned, the response fields might not be returned correctly. Review the error messages associated with non-zero response codes and take appropriate steps to resolve the error conditions. Most of the non-zero response codes indicate a system configuration or integration issue. Before production deployment, you should resolve these issues during the testing phase.
0 Success.Suggested Customer Message: Transaction completed.
Note: Not an error condition.
1 General system failure.Suggested Customer Message: System not available. Please try again later.
Note: A low-level error message that may indicate a communication problem, a timing problem, an intermittent failure to contact an acquirer, or another condition not captured by the other response codes. If this response code is returned after repeated attempts, contact Support.
510 Parameter [name] is required.Note: No value was sent for a required parameter. Check all required parameters are included in the API call.
511 Parameter [name] exceeds max length of [value].Note: A required parameter contains too many characters. Check the length does not exceed the maximum length value specified for the parameter.
512 Parameter [name] is not a valid [value].Note: A general type-mismatch error. Check the required parameters are being populated correctly.
513 Parameter [name] cannot be undefined or null.Note: The parameter is empty. Check the parameter that fills this field.
514 Parameter [name] is invalid. Valid values are [valid values].Suggested Customer Message: Please select a correct value.
Note: The input value does not match one of the multiple-choice values provided.
521 Parameter [name] is not a valid credit card number.Suggested Customer Message: Please check your credit card information.
Note: The credit/debit card number must contain 13 to 19 digits.
1001 Login failed.Suggested Customer Message: System not available. Please try again later.
Note: Authentication failed. Check your credentials and try again, or contact Support.
1002 Invalid credit card length.Suggested Customer Message: Transaction not found.
Note: Credit/debit card number must contain 13 to 19 digits.
1003 Credit card fails Mod-10 check.Suggested Customer Message: Please check your credit card information.
Note: The credit/debit card number provided does not pass basic length and format validation. Mod-10 is a basic numeric check to see if it meets the minimum rules to be valid. Usually, this occurs when the credit/debit card number has been mistyped.
1005 Account not active.Suggested Customer Message: System not available. Please try again later.
Note: Indicates a problem with the merchant's account. Contact Support.
1030 Provide account holder name and complete address.Note: The full customer information and address must be provided.
1031 Provide account holder address.Note: The full customer address must be provided.
1032 Provide account holder name.Note: The full customer information must be provided.
1033 Parameter {Amount} exceeds maximum transaction amount of [MaxTransactionAmount].
1034 Parameter {AutoDisposition} value is not valid for the requested transaction.
1035 Amount must be greater than 0.
1036 Payment not eligible for authorization results processing.
1060 No acquirer available.Suggested Customer Message: We were unable to process this transaction. Please try again later.
Note: An acquirer is required to complete this transaction. If the problem persists, contact Support.
1063 Account only eligible for signature debit transactions.Suggested Customer Message: We cannot process this type of card. Please select a credit/debit card with a Visa, Discover, American Express, or MasterCard logo.
Note: Your configuration only supports debit transactions. The customer provided a credit card.
1069 Account not eligible to use AccountNumberIndicator value provided in request.
1070 Unable to decrypt ApplyPay encrypted payment token data.