PSPs > API Reference > Endpoints > Transaction

Transaction

POST api.ravelin.com/psp/transaction

The address of the cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

additional string optional

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

addressee string optional

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

country string optional

An ISO 3166-1 Alpha 3 country code.

locality string optional

This normally represents the city.

postalCode string optional

The postal code or ZIP code.

region string optional

The state, province, or county.

source string optional

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.

street1 string optional

The first line of the street address.

street2 string optional

The second line of the street address, if applicable.

customer object

The customer instigating this transaction, if available.

Show definition

customerId string optional

The merchant's ID for the customer.

email string optional

telephone string optional

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

device object

The customer's phone, tablet or computer used to trigger this update to the transaction. Do not include device information if the device is known to be a shared device, for example an in-store terminal.

Show definition

deviceId string optional

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

ipAddress string optional

The IP address of the device connecting to your services.

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

lang string optional

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

manufacturer string optional

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

model string optional

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.

os string optional

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

type string optional

The type of device

userAgent string optional

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

paymentMethod object

A primary payment method to be charged in completing the checkout process.

Show definition

countryIssued string optional

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.

eWallet string optional

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.

email string optional

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.

expiryMonth integer optional

The expiry month of the card.

expiryYear integer optional

The expiry year of the card.

googlePayAccountVerified boolean optional

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.

googlePayCardholderAuthenticated boolean optional

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.

iin string optional

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.

instrumentId string optional

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.

issuer string optional

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.

lastFour string optional

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.

methodType string optional

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

nameOnCard string optional

The cardholder name.

prepaid boolean optional

Is the card pre-paid?

scheme string optional

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.

shippingAddress object

The delivery or drop-off location of the order.

Show definition

additional string optional

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

addressee string optional

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

country string optional

An ISO 3166-1 Alpha 3 country code.

locality string optional

This normally represents the city.

postalCode string optional

The postal code or ZIP code.

region string optional

The state, province, or county.

source string optional

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.

street1 string optional

The first line of the street address.

street2 string optional

The second line of the street address, if applicable.

threeds object

This object describes the result of 3DS authentication if attempted.

Show definition

challengeCancel string optional

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

challenged boolean optional

Whether the authentication was challenged.

deviceChannel string optional

Indicates the channel being used to initiate the authentication.

01: App-based (APP)
02: Browser (BRW)
03: 3DS Requestor Initiated (3RI)

eci string optional

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

endTime integer optional

When the 3DS authentication attempt finished.

errorCode string optional

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

errorComponent string optional

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

C: 3DS SDK
S: 3DS Server
D: Directory Server
A: Access Control Server

errorDescription string optional

A description of the error that occurred.

errorDetail string optional

A detailed description of the error that occurred.

errorMessageType string optional

Identifies the Message Type that was identified as erroneous.

liabilityShifted boolean optional

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

requestorChallengeInd string optional

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)

startTime integer optional

When the 3DS authentication attempt started.

transStatus string optional

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.

transStatusReason string optional

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

version string optional

The 3DS version

whiteListStatus string optional

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

whiteListStatusSource string optional

Identifies the system which set the whiteListStatus value.

01: 3DS Server
02: Directory Server (DS)
03: Access Control Server (ACS)

timestamp integer required

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

transaction object

A transaction is an attempt to charge a payment method or refund money to a payment method. When charging a payment method funds need to be authorised and then captured for payment. Authorisation and capture may take place in one step, or authorisation can take place well in advance of capture.

In some situations the authorised amount can be updated over time. Equally the captured amount can be incremented.

To support this you can send multiple updates to the same transaction, and ask for fraud scoring at any point within the transaction lifecycle.

Show definition

acquirerBin string optional

The IIN (Issuer Identification Number) of the acquirer.

acquirerCountryCode string optional

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

acquirerId string optional

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

amount integer optional

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.

arn string optional

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

avsResultCode object

Show definition

postalCode string optional

This field encodes the result of the AVS ZIP or Postal Code check. Do not send this field if this AVS check was not requested.

STRONG_MATCH: the provided ZIP/Postal Code was an exact match for the value on record for the card.
WEAK_MATCH: the provided ZIP / Postal Code was a partial match for the value on record for the card. Use this value for a 5-digit ZIP code match
DOES_NOT_MATCH: the provided ZIP / Postal Code did not match the value on record for the card.
NO_RESULT: a ZIP / Postal Code was provided, but a match result was not available. Use this value both when this was because of a failure and when it was because some party in the transaction did not support AVS ZIP / Postal Code checks.

street string optional

This field encodes the result of the AVS street address check. Do not send this field if the AVS street address check was not requested.

STRONG_MATCH: the provided street address was an exact match for the value on record for the card.
WEAK_MATCH: the provided street address was a partial match for the value on record for the card.
DOES_NOT_MATCH: the provided street address did not match the value on record for the card.
NO_RESULT: a street address was provided, but a match result was not available. Use this value both when this was because of a failure and when it was because some party in the transaction did not support AVS street address checks.

clientRuleTriggered object

Show definition

action string optional

The action which the rule produced.

ALLOW: allow the transaction to proceed
REVIEW: review whether transaction should proceed
PREVENT: prevent transaction from proceeding

description string optional

The details of the client rule that fired

stage string optional

Describes the stage in processing the transaction that the rule was triggered.

pre_auth: before authentication/authorization took place
post_auth: after authentication/authorization took place

currency string optional

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

Ravelin expects each transaction to use a single currency.

cvvResultCode string optional

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.

declineCode string optional

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.

gateway string optional

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

gatewayReference string optional

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

mcc string optional

The Merchant Category Code associated with the transaction.

merchantCountryCode string optional

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

merchantName string optional

The name of the merchant.

mid string optional

A unique identifier for the merchant.

parentTransactionId string optional

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.

partial boolean optional

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.

softDeclineCode string optional

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

stepId string optional

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.

success boolean optional

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

transactionId string required

A unique reference for the transaction.

type string optional

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.

POST https://api.ravelin.com/psp/transaction HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "billingAddress": {
    "additional": "Prestbury",
    "addressee": "John Smith",
    "country": "GBR",
    "locality": "Macclesfield",
    "postalCode": "SK10 4JQ",
    "region": "Cheshire",
    "source": "E_WALLET",
    "street1": "Flat 16",
    "street2": "7 Acacia Avenue"
  },
  "customer": {
    "customerId": "string",
    "email": "sales@ravelin.com",
    "telephone": "+16045555555"
  },
  "device": {
    "deviceId": "string",
    "ipAddress": "81.152.92.84",
    "lang": "en-US",
    "manufacturer": "apple",
    "model": "iPhone15,3",
    "os": "ios",
    "type": "phone",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36"
  },
  "paymentMethod": {
    "countryIssued": "GBR",
    "eWallet": "applepay",
    "expiryMonth": 7,
    "expiryYear": 2024,
    "iin": "454303",
    "instrumentId": "fp_abc123",
    "issuer": "rabobank",
    "lastFour": "0001",
    "methodType": "card",
    "nameOnCard": "John Smith",
    "prepaid": false,
    "scheme": "visa"
  },
  "shippingAddress": {
    "additional": "Prestbury",
    "addressee": "John Smith",
    "country": "GBR",
    "locality": "Macclesfield",
    "postalCode": "SK10 4JQ",
    "region": "Cheshire",
    "source": "E_WALLET",
    "street1": "Flat 16",
    "street2": "7 Acacia Avenue"
  },
  "threeds": {
    "challengeCancel": "01",
    "deviceChannel": "01",
    "endTime": 1512828989826,
    "liabilityShifted": true,
    "requestorChallengeInd": "01",
    "startTime": 1512828988826,
    "transStatus": "Y",
    "transStatusReason": "01",
    "version": "2.2.0",
    "whiteListStatus": "Y",
    "whiteListStatusSource": "01"
  },
  "timestamp": 1667387532297,
  "transaction": {
    "acquirerBin": "454303",
    "acquirerCountryCode": "GBR",
    "acquirerId": "adyen",
    "amount": 1337,
    "arn": "string",
    "avsResultCode": {
      "postalCode": "STRONG_MATCH",
      "street": "STRONG_MATCH"
    },
    "currency": "GBP",
    "cvvResultCode": "PASS",
    "declineCode": "LOST_OR_STOLEN",
    "gateway": "braintree",
    "gatewayReference": "string",
    "mcc": "string",
    "merchantCountryCode": "GBR",
    "merchantName": "string",
    "mid": "string",
    "parentTransactionId": "string",
    "partial": false,
    "stepId": "string",
    "success": true,
    "transactionId": "string",
    "type": "auth"
  }
}

Response (200)

data object

Holds information about Ravelin's recommendation for this transaction if requested.

Show definition

action string optional

Ravelin's recommended action for this transaction.

rules object

Information about rules that have fired

Show definition

passiveAction string optional

What Ravelin's recommended action for this transaction would have been if all test rules were active.

triggered object

Show definition

action string optional

The action which the rule produced

description string optional

A description of the rule conditions

ruleId integer optional

The ID of the rule that fired

ruleVersion integer optional

The version of the rule that fired

state string optional

Whether the rule is an active rule or a test (passive) rule

score integer optional

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.

scoreId string optional

Ravelin's ID for this recommendation.

transactionId string optional

The ID of the transaction that this recommendation is for.

transactionOptimisation object

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

Show definition

action string optional

Our transaction optimisation recommendation for whether the transaction should be authenticated or sent straight to authorisation.

actionSource string optional

The source of the given recommendation.

exemption string optional

The SCA exemption type to request for the transaction.

ruleId integer optional

The ID of the rule which triggered to produce the action.

ruleVersion integer optional

The version number of the rule which triggered to produce the action.

rules object

Indicates which rules were triggered to cause the given recommendation.

Show definition

passiveAction string optional

What Ravelin's recommended action for this transaction would have been if all test rules were active.

triggered object

Show definition

action string optional

The action which the rule produced.

description string optional

A description of the rule conditions.

exemption string optional

The exemption which the rule produced.

ruleId integer optional

The ID of the rule that fired.

ruleVersion integer optional

The version of the rule that fired.

state string optional

Whether the rule is an active rule or a test (passive) rule.

threeDSChallengePreference string optional

The 3DS challenge preference which the rule produced.

threeDSChallengePreference string optional

The preference for whether or not a 3DS challenge should be performed. This field is only present if action is AUTHENTICATE.

message string optional

If an error has occurred, a description of the error.

status integer optional

HTTP response status code.

timestamp integer optional

UNIX timestamp when Ravelin finished handling the request

HTTP/1.1 200 OK
Content-Type: applicaton/json

{
  "data": {
    "action": "ALLOW",
    "rules": {
      "passiveAction": "PREVENT",
      "triggered": [
        {
          "action": "REVIEW",
          "description": "Psp.secondsSinceEmailFirstSeen is less than 200.",
          "ruleId": 14384,
          "ruleVersion": 7,
          "state": "active"
        }
      ]
    },
    "score": 76,
    "scoreId": "b4a88559-5090-44fb-8a31-eff8a00a79dd",
    "transactionId": "6cbe7636-3c15-45e8-bf29-2f010ae829bf"
  },
  "status": 200,
  "timestamp": 1512828988826
}

Response (400)

message string optional

A text description of the problem that triggered the error

status integer optional

HTTP response status code.

timestamp integer optional

UNIX timestamp when Ravelin finished handling the request

traceId string optional

A unique identifier for the request

HTTP/1.1 200 OK
Content-Type: applicaton/json

{
  "data": {
    "action": "ALLOW",
    "rules": {
      "passiveAction": "PREVENT",
      "triggered": [
        {
          "action": "REVIEW",
          "description": "Psp.secondsSinceEmailFirstSeen is less than 200.",
          "ruleId": 14384,
          "ruleVersion": 7,
          "state": "active"
        }
      ]
    },
    "score": 76,
    "scoreId": "b4a88559-5090-44fb-8a31-eff8a00a79dd",
    "transactionId": "6cbe7636-3c15-45e8-bf29-2f010ae829bf"
  },
  "status": 200,
  "timestamp": 1512828988826
}

Feedback

Was this page helpful?