Create or Update Risk Assessment

Request to send a card transaction to a risk service provider without processing a payment.
You can use this operation when you want to:

  • Assess risk: request the risk service provider to assess the risk of a card transaction and provide a result. In this case set requestAction to RISK_ASSESSMENT.
  • Provide information only: inform the risk service provider about a card transaction or the outcome of processing a card transaction. You do not require the risk service provider to provide a risk assessment result. In this case set requestAction to INFORMATION_ONLY and provide details about the transaction processing result in the transactionProcessingResponse parameter group.
You can submit more than one risk assessment request for the same payment by using the same risk assessment ID. For example, you might want to assess the risk of a transaction before processing the payment and then provide an update to the risk service provider after it has been processed. Note that if the previous risk assessment was not successful (result=FAILURE) you must use a new risk assessment ID.

PUT https://na.gateway.spring.citi.com/api/rest/version/100 / merchant / {merchantId} / riskassessment / {riskassessmentid}

Authentication

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request

URL Parameters

{merchantId} Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.


This identifier can be up to 12 characters in length.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
{riskassessmentid} Alphanumeric + additional characters REQUIRED

A unique identifier for this risk assessment to distinguish it from any other risk assessment you create.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'

Min length: 1 Max length: 40

Fields

agreement OPTIONAL

A commercial agreement you have with the payer that allows you to store and use their payment details for later payments.

For example, an agreement to a series of recurring payments (a mobile phone subscription), an agreement to take payment for a purchase by a series of installments (hire purchase), an agreement to make additional payments when required (account top up), or to fulfil a standard industry practice (no show penalty charge).

Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.

See Credential on File, Cardholder, and Merchant Initiated Transactions for details.

agreement.type Enumeration OPTIONAL

The type of commercial agreement that the payer has with you.

Specify the agreement type when you have provided a value for agreement.id and this payment is the first in a series of payments. The default value is OTHER.

The gateway will use the value you specify for subsequent payments in the series.

Value must be a member of the following list. The values are case sensitive.

INDUSTRY_PRACTICE

An agreement where the payer authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. These additional payments are triggered by an event not known at the time of the payer's initial agreement. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show charge when the payer fails to show for a booking.

INSTALLMENT

An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.

OTHER

An agreement where you want to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.

RECURRING

An agreement where the payer authorizes you to process repeat payments for bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.

UNSCHEDULED

An agreement where the payer authorizes you to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

apiOperation String = CREATE_OR_UPDATE_RISK_ASSESSMENT FIXED

Any sequence of zero or more unicode characters.

billing OPTIONAL

Details of the payer's billing address.

billing.address OPTIONAL

The payer's billing address.

This data may be used to qualify for better interchange rates on corporate purchase card transactions.

billing.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.company String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
billing.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
billing.address.stateProvince String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode String OPTIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
billing.address.street String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.street2 String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
correlationId String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
customer OPTIONAL

Information about the customer, including their contact details.

customer.email Email OPTIONAL

The email address of the customer.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

customer.firstName String OPTIONAL

The payer's first name.

Data can consist of any characters

Min length: 1 Max length: 50
customer.lastName String OPTIONAL

The payer's last or surname.

Data can consist of any characters

Min length: 1 Max length: 50
customer.mobilePhone Telephone Number OPTIONAL

The payer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
customer.phone Telephone Number OPTIONAL

The payer's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
device OPTIONAL

Information about the device used by the payer for this transaction.

device.browser String OPTIONAL

The User-Agent header of the browser the customer used to place the order.

For example, MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)

Data can consist of any characters

Min length: 1 Max length: 2048
device.fingerprint String OPTIONAL

Information collected about a remote computing device for the purpose of providing a unique identifier for the device.

For example, session ID, blackbox ID.

Data can consist of any characters

Min length: 1 Max length: 4000
device.ipAddress String OPTIONAL

The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format.

Data can consist of any characters

Min length: 7 Max length: 15
device.mobilePhoneModel String OPTIONAL

The mobile phone manufacturer's identifier for the model of the mobile device used to initiate the payment.

Data can consist of any characters

Min length: 1 Max length: 255
order REQUIRED

Information about the order associated with this transaction.

order.amount Decimal OPTIONAL

The total amount for the order.  This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.

The value of this field in the response is zero if payer funds are not transferred.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.cashbackAmount Decimal OPTIONAL

The amount the payer has chosen to receive as cash in addition to the amount they are paying for the goods or services they are purchasing from you.

The cash back amount is included in the total amount of the order you provide in order.amount.

This field corresponds to EMV tag 9F03

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.currency Upper case alphabetic text REQUIRED

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.description String OPTIONAL

Short textual description of the contents of the order.

Data can consist of any characters

Min length: 1 Max length: 127
order.discount OPTIONAL

Information about a price reduction you have applied to the order.

For example, you may apply discounts for trade, employees, bulk purchase, or a sales promotion.

order.discount.amount Decimal OPTIONAL

The total amount of the discount you have applied to the order.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.discount.code String OPTIONAL

The code you use to identify the reason for the discount.

Data can consist of any characters

Min length: 1 Max length: 40
order.item[n] OPTIONAL

Information about the items the payer purchases with the order.

order.item[n].brand String OPTIONAL

The brand of the item.

For example, Dell.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].category String OPTIONAL

Your category for the item.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].name String REQUIRED

A short name describing the item.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].quantity Decimal REQUIRED

The quantity of the item.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number greater than zero.

Min length: 0 Max length: 30
order.item[n].sku String OPTIONAL

The SKU (Stock Keeping Unit) or the item identifier for this item.

Data can consist of any characters

Min length: 1 Max length: 127
order.item[n].unitPrice Decimal REQUIRED

The cost price for the item.

This amount is multiplied with the item quantity (item.quantity) to determine the total amount for this item (item.amount). This amount does not include the tax amount and/or discount amount applicable to this item.

Data is a string that consists of the characters 0-9, '.' and '-' and represents a valid decimal number.

Min length: 1 Max length: 14
order.merchantCategoryCode Digits OPTIONAL

A 4-digit code used to classify your business by the type of goods or services it offers.This is also known as the Merchant Category Code (MCC).

You only need to provide the MCC if you want to override the default value configured for your acquirer link.The value you provide must match one of those configured by your payment service provider.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
requestAction Enumeration REQUIRED

Informs the risk service provider how you want them to process the information you have provided in the request.

Informs the risk service provider how you want them to process the information you have provided in the request..

Value must be a member of the following list. The values are case sensitive.

INFORMATION_ONLY

You are informing the risk service provider about a card transaction or the outcome of a card transaction. You do not require the risk service provider to provide a risk assessment result.

RISK_ASSESSMENT

You are requesting the risk service provider to assess the risk of a card transaction and provide a risk assessment result.

shipping OPTIONAL

Shipping information for this order.

shipping.address OPTIONAL

The address to which this order will be shipped.

shipping.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.company String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
shipping.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
shipping.address.stateProvince String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
shipping.address.street String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.street2 String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
shipping.contact OPTIONAL

Details of the contact person at the address the goods will be shipped to.

shipping.contact.email Email OPTIONAL

The contact person's email address.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

shipping.contact.firstName String OPTIONAL

The first name of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.lastName String OPTIONAL

The last name or surname of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.mobilePhone Telephone Number OPTIONAL

The contact person's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
shipping.contact.phone Telephone Number OPTIONAL

The contact person's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
shipping.method Enumeration OPTIONAL

The shipping method used for delivery of this order.

Value must be a member of the following list. The values are case sensitive.

ELECTRONIC

Electronic delivery.

GROUND

Ground (4 or more days).

NOT_SHIPPED

Order for goods that are not shipped (for example, travel and event tickets)

OVERNIGHT

Overnight (next day).

PICKUP

Shipped to a local store for pick up.

PRIORITY

Priority (2-3 days).

SAME_DAY

Same day.

sourceOfFunds REQUIRED

Information about the payment type selected by the payer for this payment and the source of the funds.

Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.

sourceOfFunds.provided REQUIRED

Information about the source of funds when it is directly provided (as opposed to via a token or session).

For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.

sourceOfFunds.provided.card REQUIRED

Details about the card.

Use this parameter group when you have sourced payment details using:
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).

sourceOfFunds.provided.card.devicePayment OPTIONAL

Details about the card that you have sourced using digital payment methods.

Use this parameter group when you have sourced payment details using:

  • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
  • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
  • • Card scheme tokens. This applies when you have tokenized the payer's card number using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES) or Visa Token Service (VTS).

sourceOfFunds.provided.card.devicePayment.eciIndicator Digits OPTIONAL

The Electronic Commerce Indicator generated for payments made using a device payment method.

You source this field directly from the decrypted payment token.

You must provide this field if you have it. This field is not applicable for payments using digital wallets.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 2
sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram Base64 OPTIONAL

A cryptogram used to authenticate the transaction.

Use this field for:

  • • Device payments: source this field directly from the decrypted payment token.
  • • Card scheme tokens: source this field directly from the decrypted transaction credentials. For MDES (Mastercard Digital Enablement Service) tokens this is the UCAF cryptogram (de48se43Data). For VTS (Visa Token Service) tokens this is the TAVV cryptogram.

Data is Base64 encoded

Min length: 1 Max length: 128
sourceOfFunds.provided.card.expiry OPTIONAL

Expiry date, as shown on the card or as provided for a card scheme token.

This field corresponds to EMV tag 5F24

sourceOfFunds.provided.card.expiry.month Digits REQUIRED

Month, as shown on the card.

Months are numbered January=1, through to December=12.

Data is a number between 1 and 12 represented as a string.

sourceOfFunds.provided.card.expiry.year Digits REQUIRED

Year, as shown on the card.

The Common Era year is 2000 plus this value.

Data is a string that consists of the characters 0-9.

Min length: 2 Max length: 2
sourceOfFunds.provided.card.nameOnCard String OPTIONAL

The cardholder's name as printed on the card.

Data can consist of any characters

Min length: 1 Max length: 256
sourceOfFunds.provided.card.number Digits OPTIONAL

The account number of the payer's account used for the payment.

On requests, provide the number in the form that you receive it (as explained below). On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).

  • Request

    On request, populate this field based on the payment method you are using for the payment:
    • • Card: the account number embossed onto the card. This field corresponds to EMV tag 5A.
    • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay. Normally for device payments, you would populate sourceOfFunds.provided.card.devicePayment.paymentToken and the gateway will decrypt and extract this field. However, you can populate this field if you decrypt the payment token yourself. In this case use the Device PAN (DPAN) provided in the payment token.
    • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout. In this case, provide the PAN retrieved from the wallet.
    • • Scheme tokens such as MDES (Mastercard Digital Enablement Service) or Visa Token Service (VTS). For MDES tokens, supply the value called the "Token PAN". For VTS tokens, supply the value called "Token"
  • Response

    On return, the card number will be populated in 6.4 masking format, for example, 000000xxxxxx0000. If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.

    When a DPAN or scheme token was provided in the transaction request, then this field will represent the PAN of the associated payer's account (when supported by the acquirer). This is also referred to as the Funding PAN (FPAN).

Data is a string that consists of the characters 0-9.

Min length: 9 Max length: 19
sourceOfFunds.provided.card.paymentAccountReference String OPTIONAL

The unique identifier that links a Primary Account Number (PAN) for a card with all Device Primary Account Numbers (DPANs) or card scheme tokens issued for the card.

Data can consist of any characters

Min length: 29 Max length: 29
sourceOfFunds.provided.card.securityCode Digits OPTIONAL

Card verification code, as printed on the back or front of the card or as provided for a card scheme token.

Data is a string that consists of the characters 0-9.

Min length: 3 Max length: 4
sourceOfFunds.provided.card.storedOnFile Enumeration OPTIONAL

This field only applies if you collect card details from your payer, store them, and either you or your payer use the stored credentials for subsequent payments.

Refer to Credential on File, Cardholder and Merchant-initiated Transactions for details.

Value must be a member of the following list. The values are case sensitive.

NOT_STORED

Set this value if you are not storing the card details provided by the payer for this transaction. The gateway sets this value by default, if you are submitting a payer-initiated transaction. You must not use this value when submitting merchant-initiated transactions.

STORED

Set this value if you have previously stored the card details provided by the payer and are now using these stored details. The gateway sets this value by default, if you are submitting a merchant-initiated transaction.

TO_BE_STORED

Set this value if this is the first transaction using these card details and you intend to store the card details if the transaction is successful.

sourceOfFunds.type Enumeration OPTIONAL

The payment method used for this payment.

If you are passing card data (in any form) on the API, then you need to set this value, and also provide the card details in the sourceOfFunds.provided.card group. In the case of digital wallets or device payment methods, you must also populate the order.walletProvider field.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.

Value must be a member of the following list. The values are case sensitive.

CARD

Use this value for payments that obtained the card details either directly from the card, or from a POS terminal, or from a wallet, or through a device payment method.

transaction REQUIRED

Information about the transaction.

transaction.creationDate DateTime REQUIRED

The date and time the transaction was created in your system or in the system that you used to submit the transaction to the acquirer.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

transaction.source Enumeration REQUIRED

Indicates the channel through which you received authorization for the payment from the payer.

For example, set this value to INTERNET if the payer initiated the payment online.

If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.

Value must be a member of the following list. The values are case sensitive.

CALL_CENTRE

Transaction conducted via a call centre.

CARD_PRESENT

Transaction where the card is presented to the merchant.

INTERNET

Transaction conducted over the Internet.

MAIL_ORDER

Transaction received by mail.

MERCHANT

Transaction initiated by you based on an agreement with the payer. For example, a recurring payment, installment payment, or account top-up.

TELEPHONE_ORDER

Transaction received by telephone.

VOICE_RESPONSE

Transaction conducted by a voice/DTMF recognition system.

transaction.type Enumeration REQUIRED

Informs the risk service provider about the type of transaction for which you are requesting a risk assessment.

Value must be a member of the following list. The values are case sensitive.

AUTHORIZATION

Authorization

AUTHORIZATION_UPDATE

Authorization Update

CAPTURE

Capture

OTHER

Any other transaction type

PAYMENT

Payment (Purchase)

REFUND

Refund

REFUND_AUTHORIZATION

Refund Authorization

VERIFICATION

Verification

VOID_AUTHORIZATION

Void Authorization

VOID_CAPTURE

Void Capture

VOID_PAYMENT

Void Payment

VOID_REFUND

Void Refund

transaction.url Url OPTIONAL

If transaction.source=INTERNET, provide the URL of the site (including the full path, parameters, port etc.

) on which the payer clicked the 'Pay' button to initiate the payment for this transaction.

Ensure that this is a valid URL according to RFC 1738.

transactionProcessingResponse OPTIONAL

Provide this parameter group if you are requesting a risk assessment for a transaction that you have already submitted to the acquirer for processing.

Provide all available details about the transaction processing outcome, based on the response you have received from your acquirer.

transactionProcessingResponse.acquirerCustomData String OPTIONAL

Additional data that you may have received from the acquirer in the transaction response.

Data can consist of any characters

Min length: 1 Max length: 250
transactionProcessingResponse.approvedAmount Decimal OPTIONAL

The amount returned by the acquirer in the transaction response.

Only provide this amount if it differs from the amount you requested.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
transactionProcessingResponse.authorizationMethod Enumeration OPTIONAL

Indicates the method used to authorize the payment returned by the acquirer in the transaction response.

Value must be a member of the following list. The values are case sensitive.

OFFLINE

The transaction was approved by the terminal.

OFFLINE_AFTER_ONLINE_FAILURE

The transaction was approved by the terminal after a request to authorize online failed.

ONLINE

The transaction was sent online to the acquirer for authorization.

VOICE_REFERRAL

Voice authorization for the transaction was obtained from the acquirer because the terminal does not have online capability. The authorization code was manually entered.

VOICE_REFERRAL_AFTER_ONLINE_FAILURE

Voice authorization for the transaction was obtained from the acquirer after a request to authorize online failed. The authorization code was manually entered.

transactionProcessingResponse.avsResponseCode Enumeration OPTIONAL

The Address Verification Service (AVS) result returned by the acquirer in the transaction response.

Value must be a member of the following list. The values are case sensitive.

ADDRESS_MATCH

The street address matched. The post conde and cardholder name did not match or were not provided or were provided but not checked.

ADDRESS_ZIP_MATCH

Both the street address and post code matched. The cardholder name did not match or was not provided or was provided but not checked.

NAME_ADDRESS_MATCH

The cardholder name and street address matched. The post code did not match or was not provided or was provided but not checked.

NAME_ADDRESS_ZIP_MATCH

The cardholder name, street address and post code matched.

NAME_MATCH

The cardholder name matched. The post code and street address did not match or were not provided or were provided but not checked.

NAME_ZIP_MATCH

The cardholder name and post code matched. The street address did not match or was not provided or was provided but not checked.

NOT_AVAILABLE

The issuer did not return address verification details.

NOT_REQUESTED

AVS was not requested.

NOT_VERIFIED

The issuer did not provide the AVS because this is an international transaction.

NO_MATCH

No match. The cardholder name, street address or post code did not match or were not provided or were provided but not checked.

SERVICE_NOT_SUPPORTED

AVS is not supported by the acquirer.

ZIP_MATCH

The post code matched. The street address and cardholder name did not match or were not provided or were provided but not checked.

transactionProcessingResponse.cscResponseCode Enumeration OPTIONAL

The Card Security Code (CSC) validation result returned by the acquirer in the transaction response.

Value must be a member of the following list. The values are case sensitive.

MATCH

Valid or matched.

NOT_PRESENT

Merchant indicated CSC not present on card.

NOT_PROCESSED

Not processed.

NOT_SUPPORTED

Card issuer is not registered and/or certified

NO_MATCH

Invalid or not matched.

transactionProcessingResponse.responseCode Enumeration OPTIONAL

The transaction processing result returned by the acquirer in the transaction response.

Value must be a member of the following list. The values are case sensitive.

ACQUIRER_SYSTEM_ERROR

You received a response from the acquirer indicating that the transaction could not be approved because an error occurred within the acquirer's system while attempting to process the transaction.

APPROVED

You received a response from the acquirer indicating that the transaction was approved.

DECLINED

You received a response from the acquirer indicating that the transaction was declined.

DECLINED_CSC

You received a response from the acquirer indicating that the transaction was declined because of the Card Security Code (CSC) not being provided, invalid or not matching.

DECLINED_INVALID_PIN

You received a response from the acquirer indicating that the transaction was declined because of the provided PIN being invalid.

DECLINED_PIN_REQUIRED

You received a response from the acquirer indicating that the transaction was declined because a PIN was required but not provided.

EXPIRED_CARD

You received a response from the acquirer indicating that the transaction was declined because the card has expired.

INSUFFICIENT_FUNDS

You received a response from the acquirer indicating that the transaction was declined because of insufficient funds.

REFERRED

You received a response from the acquirer indicating that the transaction could not be approved and that you need to contact the issuer to retrieve an Authorization Code.

transactionProcessingResponse.rrn ASCII Text OPTIONAL

A unique reference generated by the acquirer for a specific merchant interaction.

The reference may be used when contacting the acquirer about a specific transaction.

Data consists of ASCII characters

Min length: 1 Max length: 100
transactionProcessingResponse.stan Digits OPTIONAL

The System Trace Audit Number (STAN) for the transaction.

The STAN is a unique trace number assigned by the gateway to identify the transaction message sent to the acquirer. It remains unchanged for the life of the transaction.

Data is a number between 1 and 999999 represented as a string.

Response

Fields

correlationId String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
id Alphanumeric + additional characters ALWAYS PROVIDED

A unique identifier for this risk assessment to distinguish it from any other risk assessment you create.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'

Min length: 1 Max length: 40
provider CONDITIONAL

Details about the risk service provider for this risk assessment.

provider.name String CONDITIONAL

The name of the risk service provider.

Data can consist of any characters

Min length: 1 Max length: 250
provider.riskAssessmentRequestId String CONDITIONAL

The unique identifier for the risk assessment request submitted to the risk service provider.

The gateway generates this value and submits it in the request to the risk service provider so that you can track the risk assessment in the risk service provider's system.

Data can consist of any characters

Min length: 1 Max length: 100
recommendation Enumeration CONDITIONAL

The overall result of risk assessment returned by the risk service provider.

Value must be a member of the following list. The values are case sensitive.

ACCEPT

The Risk Service Provider assessed the information you submitted in the risk assessment request and considers the risk of completing the transaction as low risk.

NOT_CHECKED

The Risk Service Provider did not risk assess the information you provided in the risk assessment request because the request contained insufficient information to make a risk assessment.

REJECT

The Risk Service Provider assessed the information you submitted in the risk assessment request and considers the risk of completing the transaction as high risk.

REVIEW

The Risk Service Provider assessed the information you submitted in the risk assessment request and considers the risk of completing the transaction as neither low risk or high risk and recommends that you perform a manual review before completing the transaction.

result Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the assessment.

Value must be a member of the following list. The values are case sensitive.

FAILURE

The operation was declined or rejected by the gateway, acquirer or issuer

PENDING

The operation is currently in progress or pending processing

SUCCESS

The operation was successfully processed

UNKNOWN

The result of the operation is unknown

review CONDITIONAL

Details of the decision need to make or have made, when the risk service provider has asked to you review this assessment.

review.decision Enumeration CONDITIONAL

The status of the risk review decision.

Where a risk review is required you need to go to the risk service provider's system and make the decision. The decision will then be recorded against the risk assessment.

Value must be a member of the following list. The values are case sensitive.

ACCEPTED

You made a review decision and accepted the payment for processing.

PENDING

A decision to accept or reject the payment for processing is pending.

REJECTED

You made a review decision and rejected the payment for processing.

review.decisionReason String CONDITIONAL

The reason you selected when you reviewed this order in the external risk service provider's system and decided to accept or reject the risk assessment.

Data can consist of any characters

Min length: 1 Max length: 100
review.note String CONDITIONAL

The note that you entered when you reviewed this payment in the risk service provider's system and decided to accept or reject the order.

Data can consist of any characters

Min length: 1 Max length: 2000
review.timeOfDecision DateTime CONDITIONAL

The date and time you made the decision to accept or reject the payment in the risk service provider's system.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

review.userId String CONDITIONAL

The identifier of the person who made the decision to accept or reject the payment in the risk service provider's system.

Data can consist of any characters

Min length: 1 Max length: 40
rule[n] CONDITIONAL

Details of the rules applied by the risk service provider to assess the risk of this payment being fraudulent, as provided by the risk service provider.

rule[n].id String CONDITIONAL

The unique identifier for the rule.

Data can consist of any characters

Min length: 1 Max length: 32
rule[n].name String CONDITIONAL

The name of the rule.

Data can consist of any characters

Min length: 1 Max length: 100
rule[n].score Signed Integer CONDITIONAL

The score resulting from the application of this rule.

JSON number data type. The represented number may have no fractional part.

Min value: -9999999999999999 Max value: 9999999999999999
totalScore Signed Integer CONDITIONAL

The total of the risk scores for all risk rules applied by the risk service provider when assessing the risk of this payment being fraudulent.

The higher the score, the higher the fraud risk.

JSON number data type. The represented number may have no fractional part.

Min value: -9999999999999999 Max value: 9999999999999999

Errors

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

Value must be a member of the following list. The values are case sensitive.

INVALID_REQUEST

The request was rejected because it did not conform to the API protocol.

REQUEST_REJECTED

The request was rejected due to security reasons such as firewall rules, expired certificate, etc.

SERVER_BUSY

The server did not have enough resources to process the request at the moment.

SERVER_FAILED

There was an internal system failure.

error.explanation String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field String

Indicates the name of the field that failed validation.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode String

Indicates the code that helps the support team to quickly identify the exact cause of the error.

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Enumeration

Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Value must be a member of the following list. The values are case sensitive.

INVALID

The request contained a field with a value that did not pass validation.

MISSING

The request was missing a mandatory field.

UNSUPPORTED

The request contained a field that is unsupported.

result Enumeration

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

ERROR

The operation resulted in an error and hence cannot be processed.