Issuing Risk

Realtime risk check for credit/debit card authorization requests (for card issuers)

Please refer to API Authentication for API URL and authentication.

This API endpoint can be used for real-time transaction approval decisions.

Note you must call /v1/customers API at least once prior to calling this API with customer information so Sardine can pre-compute customer-level risk information and can correlate the cardId (/v1/issuing/risks) to the transaction.paymentMethod.card.hash (/v1/customers) that is sent in this API request.

Sardine automatically sets issuingrisk as the checkpoint for this API endpoint. You can review the rules applied under the issuingrisk checkpoint in Sardine Dashboard.

POST

issuing

risks

curl --request POST \
  --url https://api.sandbox.sardine.ai/v1/issuing/risks \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sessionKey": "972ae59c-a792-4123-a31e-b6311ef22f49",
  "customerId": "1a9ea105-2f59-4737-b4c2-3c5a8926ff8e",
  "partnerId": "59b8d327-97a6-4a6b-9436-6706ecec6325",
  "customer": {
    "accountAgeInDays": 325
  },
  "transaction": {
    "id": "2964c6d5-4e3f-484e-958f-44536c5d11e3",
    "createdAtMillis": 1605827465000,
    "amount": 12.34,
    "currencyCode": "USD",
    "type": "purchase",
    "merchant": {
      "id": "526567789012346",
      "mcc": "5411",
      "name": "SuperFoods CA USA"
    },
    "terminal": {
      "id": "36881001",
      "type": "pos_terminal",
      "operator": "customer_operated",
      "onPremise": true,
      "pinCapability": true
    },
    "address": {
      "street1": "3865 Jasmine Circle",
      "city": "San Jose",
      "regionCode": "CA",
      "postalCode": "95135",
      "countryCode": "US"
    },
    "entryInfo": {
      "pan": "contactless",
      "pinEntered": true,
      "card": "card_present",
      "cardHolder": "customer_present"
    },
    "validation": {
      "avsZip": "nodata",
      "avsStreet": "nodata",
      "cvv": "match"
    },
    "fraudScore": {
      "networkScore": 253,
      "partnerScore": 21,
      "reason": "SUSPICIOUS_ACTIVITY|LOW_TRANSACTIONS"
    },
    "foreignTransaction": false,
    "recurring": false,
    "note": "SUPERFOODS 94715",
    "accountBalance": 123.23,
    "status": "attempt"
  },
  "card": {
    "id": "cc15ad54-f71e-4245-85f6-6707faf408bc",
    "network": "mastercard",
    "balance": 235,
    "balanceCurrencyCode": "USD",
    "isVirtual": false
  },
  "checkpoints": [
    "issuingrisk"
  ]
}'

{
  "status": "success",
  "sessionKey": "972ae59c-a792-4123-a31e-b6311ef22f49",
  "level": "low",
  "amlLevel": "high",
  "score": 89,
  "checkpoints": {
    "issuingrisk": {
      "riskLevel": {
        "value": "high",
        "ruleIds": [
          123
        ]
      }
    }
  },
  "rules": [
    {
      "id": 123,
      "isLive": true,
      "isAllowlisted": true,
      "name": "Rule name #1"
    },
    {
      "id": 124,
      "isLive": true,
      "isAllowlisted": false,
      "name": "Rule name #2"
    }
  ],
  "reasonCodes": [
    "ALWR"
  ]
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Headers

X-Request-Id

string

Unique identifier for the request. Only alphanumeric character and dash is allowed.

Maximum length: 72

Body

application/json

customerId

string

required

Id of customer. Please use the same value you sent to v1/customers API

sessionKey

string

required

unique identifier for the given customer session on your platform, generated by your service. We expect it to be short-lived (e.g. expires after 30 min)

Maximum length: 100

transaction

object

required

transaction.amount

number

required

Amount of transaction. Major unit of currency (e.g. 9.99 dollars for USD)

transaction.currencyCode

string

required

3-digit ISO 4217 currency code

transaction.id

string

required

ID of the transaction

transaction.accountBalance

number

Current account balance

transaction.address

object

Address of payment terminal or merchant

transaction.createdAtMillis

integer

Unix timestamp in milliseconds for the transaction authorization time

Required range: 0 < x < 4102444800000

transaction.entryInfo

object

How card information was entered

transaction.foreignTransaction

boolean

If the transaction takes place in different country than the cardholder's country

transaction.fraudScore

object

Fraud score you get from network and your partner

transaction.merchant

object

Information about merchant

transaction.note

string

Memo associated with the transaction.

transaction.recurring

boolean

If transaction is recurring payment

transaction.status

enum<string>

status of card authorization

Available options:

attempt,

pending,

challenge,

success,

failure

transaction.terminal

object

Payment terminal

transaction.type

enum<string>

Type of transaction

Available options:

purchase,

cash,

return,

balance_inquiry

transaction.validation

object

validation information

card

object

checkpoints

string[]

Name of the checkpoints to be invoked. Defaults to issuingrisk if omitted. You can pass custom checkpoint names after they are created. Please discuss with Sardine. Example: ["issuingrisk"]

customBool

object

Key-value pair for boolean type custom fields to be made available in the dashboard and rule editor. Example: ”verifiedCustomer": true

customer

object

customNumber

object

Key-value pair for number type custom fields to be made available in the dashboard and rule editor. Example: ”internalRiskScore": 57

customString

object

Key-value pair for string type custom fields to be made available in the dashboard and rule editor. Example: ”customerSegment”:”premium”

partnerId

string

ID of the partner/business/merchant this event is tied to

partnerName

string

Name of the partner/business/merchant this event is tied to

purchaseVerification

object

Information about the purchase verification message sent to the cardholder and channel.

Response

200 - application/json

amlLevel

string

AML risk level like high, medium and low.

checkpoints

object

Result of rule evaluations for each checkpoint. issuingrisk checkpoint is executed by default.

level

string

Risk level like very_high, high, medium and low

reasonCodes

string[]

List of reason codes returned for this session (it is omitted if empty). Example: ALWR

rules

object[]

List of live and shadow rules that triggered for this session

score

number

ML Risk Score for this particular transaction. The ML model used to predict the score is trained on various features and can be used once sufficient data and feedback have been provided.

sessionKey

string

Unique identifier for the given customer session as provided by you in the API request payload

status

string

Status of the API response

curl --request POST \
  --url https://api.sandbox.sardine.ai/v1/issuing/risks \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sessionKey": "972ae59c-a792-4123-a31e-b6311ef22f49",
  "customerId": "1a9ea105-2f59-4737-b4c2-3c5a8926ff8e",
  "partnerId": "59b8d327-97a6-4a6b-9436-6706ecec6325",
  "customer": {
    "accountAgeInDays": 325
  },
  "transaction": {
    "id": "2964c6d5-4e3f-484e-958f-44536c5d11e3",
    "createdAtMillis": 1605827465000,
    "amount": 12.34,
    "currencyCode": "USD",
    "type": "purchase",
    "merchant": {
      "id": "526567789012346",
      "mcc": "5411",
      "name": "SuperFoods CA USA"
    },
    "terminal": {
      "id": "36881001",
      "type": "pos_terminal",
      "operator": "customer_operated",
      "onPremise": true,
      "pinCapability": true
    },
    "address": {
      "street1": "3865 Jasmine Circle",
      "city": "San Jose",
      "regionCode": "CA",
      "postalCode": "95135",
      "countryCode": "US"
    },
    "entryInfo": {
      "pan": "contactless",
      "pinEntered": true,
      "card": "card_present",
      "cardHolder": "customer_present"
    },
    "validation": {
      "avsZip": "nodata",
      "avsStreet": "nodata",
      "cvv": "match"
    },
    "fraudScore": {
      "networkScore": 253,
      "partnerScore": 21,
      "reason": "SUSPICIOUS_ACTIVITY|LOW_TRANSACTIONS"
    },
    "foreignTransaction": false,
    "recurring": false,
    "note": "SUPERFOODS 94715",
    "accountBalance": 123.23,
    "status": "attempt"
  },
  "card": {
    "id": "cc15ad54-f71e-4245-85f6-6707faf408bc",
    "network": "mastercard",
    "balance": 235,
    "balanceCurrencyCode": "USD",
    "isVirtual": false
  },
  "checkpoints": [
    "issuingrisk"
  ]
}'

{
  "status": "success",
  "sessionKey": "972ae59c-a792-4123-a31e-b6311ef22f49",
  "level": "low",
  "amlLevel": "high",
  "score": 89,
  "checkpoints": {
    "issuingrisk": {
      "riskLevel": {
        "value": "high",
        "ruleIds": [
          123
        ]
      }
    }
  },
  "rules": [
    {
      "id": 123,
      "isLive": true,
      "isAllowlisted": true,
      "name": "Rule name #1"
    },
    {
      "id": 124,
      "isLive": true,
      "isAllowlisted": false,
      "name": "Rule name #2"
    }
  ],
  "reasonCodes": [
    "ALWR"
  ]
}