Transaction

Any additional address information that's not better-captured in other fields.

The name of the person or entity to which the address refers.

An ISO 3166-1 Alpha 3 country code.

This normally represents the city.

The postal code or ZIP code.

The state, province, or county.

The source of the address information. Do not set if unknown, or if the situation does not match one of the enumerated values.

• CUSTOMER: The customer typed in the information. Note this is assumed if the field is not supplied.
• E_WALLET: The address was supplied by an e-wallet system such as ApplePay.

This must be either CUSTOMER or E_WALLET.

The first line of the street address.

The second line of the street address, if applicable.

The merchant's ID for the customer.

The telephone number of the customer in E.164 format with an international dialing code.

A unique identifier for the device used by the customer to generate the transaction.

The IP address of the device connecting to your services.

When extracting this IP address, consider X-Forwarded-For.

The ISO 639 code of your customer's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header. If the device is a browser use window.navigator.language

The device manufacturer. For example apple, samsung, huawei.

The model/identifier name of the device if the device represents a native app.

iOS models are listed here. Use the model identifier, e.g. iPhone15,3 for the iPhone 14 Pro Max.

The models supported by Google Play are listed in this CSV file. Use the value from the Model column

For Android native apps use Build.Model.

For iOS native apps the information is encoded (with other data) in the machine field returned by the uname call.

The operating system that the device is running. For example ios, android, harmonyos, windows, linux.

The type of device

One of: phone, tablet, or computer.

The browser user-agent string, if the device represents a web browser - window.navigator.userAgent

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the iin, which should be preferred.

An ISO 3166-1 Alpha 3 country code.

The e-Wallet to which the customer is using for this payment and obscures some of the card details from the merchant and payment processor.

One of: amazonpay, applepay, googlepay, samsungpay, microsoftpay, wechatpay, kakaopay, or visacheckout.

The email address associated with the account where the wallet is set up. For example, this would be an @gmail.com email address for Google Pay wallets, or the email address associated with the Apple ID for Apple Pay wallets. In some cases a temporary email address may be used; for example, for Apple Pay this may be an @privaterelay.appleid.com email address.

The expiry month of the card.

The expiry year of the card.

A Google Pay specific field, which is available in the [AssuranceDetailsSpecifications] (https://developers.google.com/pay/api/web/reference/response-objects#assurance-details-specifications) object from the Google Pay API. If this is set to true, it indicates that cardholder possession has been validated. We strongly recommend that you send this data for Google Pay transactions if you have access to this field.

A Google Pay specific field, which is available in the [AssuranceDetailsSpecifications] (https://developers.google.com/pay/api/web/reference/response-objects#assurance-details-specifications) object from the Google Pay API. If this is set to true, it indicates that identification and verification was performed. We strongly recommend that you send this data for Google Pay transactions if you have access to this field.

The Issuer Identification Number (IIN), formerly known as the Bank Identification Number (BIN). This is the first six or eight digits of the card number/PAN.

If you supply the IIN, Ravelin will populate the scheme, issuer, country issued, and whether the card is prepaid. The exception to this is if the payment is made via an e-Wallet. In that case we expect the IIN will be tokenised and therefore that we will not be able to use it to look up these details.

A unique identifier for the physical card, shared between customers. Used to link cards in Connect. Must not be the PAN or a hash of the PAN.

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the iin, which should be preferred.

The last two or four digits of the card number/PAN. Please note this will be truncated to the last two digits when an eight digit IIN is provided.

The type of payment method. Currently only "card" is supported

This must be card.

The cardholder name.

Is the card pre-paid?

The card network or scheme, such as visa or mastercard. Ravelin will identify the scheme on your behalf if you send the iin, which should be preferred.

One of: visa, americanexpress, mastercard, discover, jcb, maestro, dinersclub, unionpay, mir, vervecard, rupay, dankort, elo, or platima.

Any additional address information that's not better captured in other fields.

The name of the person or entity to which the address refers.

An ISO 3166-1 Alpha 3 country code.

This normally represents the city.

The postal code or ZIP code.

The state, province, or county.

The source of the address information. Do not set this if it's unknown or if the situation does not match one of the enumerated values.

• CUSTOMER: The customer typed in the information. Note this is assumed if the field is not supplied.
• E_WALLET: The address was supplied by an e-wallet system such as ApplePay.

This must be either CUSTOMER or E_WALLET.

The first line of the street address.

The second line of the street address, if applicable.

Indicates that the authentication was cancelled.

• 01: Cardholder selected "Cancel"

• 02: 3DS Requestor cancelled authentication

• 03: Transaction abandoned

• 04: Transaction timed out at ACS

• 05: Transaction timed out at ACS - First Challenge Request (CReq) not received by the ACS

• 06: Transaction error

• 07: Unknown

One of: 01, 02, 03, 04, 05, 06, or 07.

Whether the authentication was challenged.

Indicates the channel being used to initiate the authentication.

• 01: App-based (APP)

• 02: Browser (BRW)

• 03: 3DS Requestor Initiated (3RI)

One of: 01, 02, or 03.

The Electronic Commerce Indicator value generated after authentication through 3D Secure has been completed. Only send this field if you are unable to tell us whether liability has been shifted.

One of: 00, 01, 02, 03, 04, 05, 06, 07, N0, N2

One of: 00, 01, 02, 03, 04, 05, 06, 07, N0, or N2.

When the 3DS authentication attempt finished.

Code indicating the type of problem identified in the message.

• 101: Invalid message

• 102: 3DS message version not supported

• 201: A required field is missing

• 202: Critical message extensions not recognised

• 203: The format of one or more of the fields is invalid

• 204: One or more fields is duplicated

• 301: A transaction ID was invalid (threeDSServerTransID, dsTransID, acsTransID or sdkTransID)

• 302: Data decryption failure

• 303: Access denied

• 304: ISO country or currency code was invalid

• 305: Transaction data was invalid

• 306: Merchant Category Code (MCC) was invalid for the payment system

• 402: Transaction timed out

• 403: Transient system failure

• 404: Permanent system failure

• 405: System connection failure

One of: 101, 102, 201, 202, 203, 204, 301, 302, 303, 304, 305, 306, 402, 403, 404, or 405.

Code indicating the 3-D Secure component that identified the error.

• C: 3DS SDK

• S: 3DS Server

• D: Directory Server

• A: Access Control Server

One of: C, S, D, or A.

A description of the error that occurred.

A detailed description of the error that occurred.

Identifies the Message Type that was identified as erroneous.

One of: AReq, ARes, CReq, CRes, RReq, or RRes.

Whether the liability of the transaction resulting in a chargeback has moved from the merchant to the card issuer. (See Liability Shift.)

Indicates whether a challenge is requested for this transaction.

• 01: No preference

• 02: No challenge requested

• 03: Challenge requested (3DS Requestor preference)

• 04: Challenge requested (mandate, e.g. required for PSD2 compliance)

• 05: No challenge requested (transactional risk analysis is already performed)

• 06: No challenge requested (data share only)

• 07: No challenge requested (strong consumer authentication is already performed)

• 08: No challenge requested (utilise whitelist exemption if no challenge required)

• 09: Challenge requested (whitelist prompt requested if challenge required)

• 90: Enable the Cartes Bancaires Scoring Service (Cartes Bancaires only)

One of: 01, 02, 03, 04, 05, 06, 07, 08, 09, or 90.

When the 3DS authentication attempt started.

The outcome of the 3DS authentication request

• Y: The authentication was successful, continue to authorisation using the authenticationValue from the Result Response.

• A: 3DS was attempted but was not possible. However the card scheme granted a successful authentication on the issuer's behalf.

• N: The authentication failed, stop processing the transaction.

• U: Authentication could not be performed. You may attempt to proceed to authorisation without authenticating.

• R: The issuer rejected the authentication attempt and requests that authorisation is not attempted.

One of: Y, A, N, U, or R.

Provides further information when the transStatus is N, U or R.

• 01: Card authentication failed

• 02: Unknown device

• 03: Unsupported device

• 04: Exceeds authentication frequency limit

• 05: Expired card

• 06: Invalid card number

• 07: Invalid transaction

• 08: No card record

• 09: Security failure

• 10: Stolen card

• 11: Suspected fraud

• 12: Transaction not permitted to cardholder

• 13: Cardholder not enrolled in service

• 14: Transaction timed out at the ACS

• 15: Low confidence

• 16: Medium confidence

• 17: High confidence

• 18: Very high confidence

• 19: Exceeds ACS maximum challenges

• 20: Non-payment (NPA) transaction not supported

• 21: 3RI transaction not supported

• 22: ACS technical issue

• 23: Decoupled authentication required by ACS but not requested by 3DS Requestor

• 24: 3DS Requestor decoupled authentication max expiry time exceeded

• 25: Insufficient time provided for decoupled authentication to authenticate cardholder. ACS will not attempt authentication

• 26: Authentication attempted but not performed by the cardholder

• '80-99': Reserved for DS use

One of: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, or 99.

The 3DS version

Indicates whether the cardholder has added the merchant to their list of trusted merchants. A cardholder can typically only choose to trust a merchant after successfully completing a challenge. A cardholder may not be required to complete a challenge with a merchant they have previously trusted.

• Y: Merchant is trusted by cardholder
• N: Merchant has not yet been trusted by cardholder
• E: Not eligible as determined by issuer
• P: Pending confirmation by cardholder
• R: Cardholder rejected the request to trust the merchant
• U: Trusted status unknown, unavailable, or does not apply

One of: Y, N, E, P, R, or U.

Identifies the system which set the whiteListStatus value.

• 01: 3DS Server

• 02: Directory Server (DS)

• 03: Access Control Server (ACS)

One of: 01, 02, or 03.

The IIN (Issuer Identification Number) of the acquirer.

The three letter ISO 3166-1 Alpha 3 country code of the country in which the acquirer operates

The acquirer is a financial institution with whom the merchant has a bank account.

• aci_worldwide: ACI Worldwide

• adyen: Adyen

• barclays: Barclays

• braintree: Braintree

• checkout: Checkout.com

• cybersource: Cybersource

• elavon: Elavon

• first_data: First Data

• fiserv: Fiserv

• global_payments: Global Payments

• ingenico: Ingenico

• jpmorgan_chase: JPMorgan Chase

• nets: Nets

• stripe: Stripe

• worldline: Worldline

• worldpay: Worldpay

One of: aci_worldwide, adyen, barclays, braintree, checkout, cybersource, elavon, first_data, fiserv, global_payments, ingenico, jpmorgan_chase, nets, stripe, worldline, or worldpay.

The amount to be charged, in the currency's basic units.

For incremental auths or partial captures the partial flag should be set to true and amount should carry the incremental amount.

refunds should be coded as a positive amount - the amount that will be refunded to the customer account.

The Acquirer Reference Number (ARN) is the acquirer's reference for the transaction

The currency of the amount of this transaction, as an ISO 4217 currency code.

Ravelin expects each transaction to use a single currency.

Result of the CVV check, if requested. Do not send this field if the CVV check was not requested.

• PASS: The CVV provided matches the value on file

• FAIL: The CVV provided does not match the value on file

• NO_RESULT: A CVV check was attempted, but no result was available. This could be because of a system failure, or because there's no CVV for the card.

One of: PASS, FAIL, or NO_RESULT.

The reason the transaction was declined, if applicable. Please map the decline code from the gateway into one of these categories.

• ADDITIONAL_VERIFICATION_REQUIRED: Use this if more verification steps are needed before the transaction can be accepted. E.g. if PIN entry or an AVS check is necessary. Set SCA_REQUIRED in softDeclineCode instead if the decline code is a 3DS soft decline and strong customer authentication is required.

• BANK_DECLINE: Use this if the card issuer declined the transaction.

• EXPIRED: Use this if the decline code indicates that the card has expired.

• FRAUD: If the decline code indicates fraud use this value.

• INSUFFICIENT_FUNDS: Use this if there are insufficient funds available.

• INVALID: Anything relating to incorrect or invalid information supplied by the consumer. If authentication information (PIN, AVS, CVC) is invalid use INVALID_VERIFICATION instead.

• INVALID_VERIFICATION: Use this if authentication fails, including if the consumer enters an incorrect PIN or AVS or CVC checks fail.

• LIMIT_EXCEEDED: Use this if the payment limit on the account is exceeded.

• LOST_OR_STOLEN: If the card has been reported lost or stolen.

• RISKY: Use this if the decline code indicates the transaction is too risky, but there's no explicit indication that there is fraud.

• OTHER: Use this if no other value is a better match for the decline code.

• ERROR: Use to indicate a system error.

One of: ADDITIONAL_VERIFICATION_REQUIRED, BANK_DECLINE, EXPIRED, FRAUD, INSUFFICIENT_FUNDS, INVALID, INVALID_VERIFICATION, LIMIT_EXCEEDED, LOST_OR_STOLEN, RISKY, OTHER, or ERROR.

The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.

The gateway's ID for this transaction. We expect this ID to be present on any subsequent chargeback.

The Merchant Category Code associated with the transaction.

The three letter ISO 3166-1 alpha-3 country code of the country in which the merchant operates.

The name of the merchant.

A unique identifier for the merchant.

If this transaction refers to a previous transaction, then put the ID of that previous transaction in parentTransactionId.

• When refunding a transaction where the previous transaction ID was known. In this case you only need fill in the amount for a partial refund.

• For repeated subscription transactions the repeats should be modeled as separate transactions that refer to the original transaction.

This should be set to true if this is a partial capture or an incremental authorisation. In this case the amount should be set to the additional amount captured or authorised.

Use this field to indicate that the authorisation was declined because 3DS Strong Customer Authentication was required.

This must be SCA_REQUIRED.

You may send several updates for the same step of a transaction. For example you might want to send an "auth" request to Ravelin to request a fraud score before submitting the transaction to the acquiring bank for processing. Once the acquirer or issuer has authorised or declined the request you should update Ravelin with details of the response (e.g. cvvResultCode, avsResultCode, success, etc).

The stepId is used to ensure an update like this is applied correctly. Supply the same stepId for all updates that relate to the same "auth".

Required if any threeds field is set or if any of the following transaction fields is set: amount, avsResultCode, cvvResultCode, declineCode, partial, softDeclineCode, succeeded or type.

Set success when a transaction step has completed to indicate whether the step succeeded or failed.

A unique reference for the transaction.

Type indicates the current action on the transaction.

• auth: An auth is used to reserve funds on the customer's card without yet deducting it.

• capture: A capture is used to immediately deduct authorised funds from a customer's card. There should be a proceeding auth on the transaction.

• auth_capture: A simultaneous combination of auth and capture in one, for when there is no need to separately auth then capture. This is the normal case.

• refund: A refund credits a customer's payment method. Note that a refund should be a separate transaction, not an update to a transaction with a preceding auth, capture or auth_capture.

• void: A void returns funds that have been authorised or captured back to the customer. Unlike a refund it should be an update to a transaction with proceeding auth, capture or auth_capture updates. The full amount that has been authorised or captured is returned.

One of: auth, capture, auth_capture, void, or refund.

Ravelin's recommended action for this transaction.

Information about rules that have fired

The Ravelin machine learning model score for the transaction, if available. The score will be integral number between 0 and 100. Larger values are a stronger indication of fraud. Note that this score is not the only factor in Ravelin's recommendation and in some cases may be ignored.

Ravelin's ID for this recommendation.

The ID of the transaction that this recommendation is for.

If transaction optimisation is enabled, and a transaction optimisation recommendation was requested, this will contain the recommendation and related details.