Evaluate customer session/transaction Risk
Refer to the overview for API URL and Authentication. Check all the reason codes returned in signals here. Use the top level field called as level in the response to make your risk decisioning and use other response fields to understand the reasons for the risk level.
Products
Use Case | Description | How | Checkpoint(s) |
---|---|---|---|
KYC | SSN Verification with Synthetic ID detection | Pass taxId in the request. If you want to do KYC SSN verification, customers id, taxid, name, dob and address are required. Please refer to the KYC (SSN Verification) example on RHS. | customer |
KYC | Sanctions Screening & Monitoring (PEP, Sanction, AdverseMedia) | Pass Name and Country (DOB is optional but reduces false positives) after this is enabled by Sardine. As seen in the example you can pass Place of birth using personalInfo Onboarding. Please refer to the KYC (Sanctions) example on RHS. | customer |
Payment Fraud | Card Fraud | Pass transaction.paymentMethod.type = “card” for transaction.amount > 0. Please refer to the Payment Fraud (Card) example on RHS. | customer + payment |
Payment Fraud | Bank Fraud | Pass transaction.paymentMethod.type = “bank” for transaction.amount > 0. Please refer to the Payment Fraud (Bank) example on RHS. | customer + ach |
Anti-Money Laundering/Transaction Monitoring | AML Foundational - Fiat and Crypto (BYO data) | For crypto Transaction Monitoring (TM), pass: crypto address in the address field. For Fiat TM, pass: transaction object. Please refer to the AML (Fiat & Crypto) example on RHS. | aml |
Anti-Money Laundering/Transaction Monitoring | AML Crypto with Analytics | For crypto address analytics, the “Crypto Analytics” flag must be enabled by Sardine to enable blockchain monitoring. Please ensure to talk to your Integration Manager about enabling this. Please refer to the AML (Crypto) example on RHS. | aml |
Typical Integration Issues
Different sessionKey and/or userIdHash (customer.id) values are used across the Device SDK and Customer API; they need to be the same values, i.e.:
- Front End Device SDK sessionKey must correspond to the Back End Customer API’s sessionKey value
- Front End Device SDK userIdHash must correspond to the Back End Customer API’s customer.id value
- Country/Region/Phone number is not passed in ISO format. e.g. phone number has +1 missing for US.
- Some data is not passed, despite it being available to the merchant to easily pass, e.g., Country or createdAtMillis or Address line 1 is missing.
- OrderNumber is not passed in the transaction.id field and instead sessionKey is passed.
Important Customers API Checkpoints Behavior
Please refer to checkpoints for recommended use cases, descriptions and prerequisites.
- When calling the customers API, if no checkpoint is specified, then the checkpoint defaults to “customer”
- When the “customer” checkpoint is invoked, the “device” checkpoint is also automatically applied, which determines the risk level of the device being used. The risk level determined by the devices checkpoint will only impact the device risk level (device.level) response field
When calling the customers API, if a checkpoint is specified, then only that checkpoint will be executed
- e.g., if “aml” is called, only “aml” would be called
- If the merchant wants “customer” to be run, then they would need to specify both “customer” and “aml”
When calling the customers API, regardless of what checkpoints are specified (i.e., regardless of the two items above), the “device” checkpoint is always called if either:
- The sessionKey matches an existing sessionKey whose device data was sent to Sardine via SDK, or
- The device.id that is sent matches an existing Sardine device.id
Important Customers API Notes
Calling the Customers API
- When calling the customers API multiple times, you will need to pass all the customer-level information in the top-level customer object the first time (this is intuitive)
- For subsequent API calls for that same customer, you don’t need to (but you can) re-pass data, e.g., customer.firstName, customer.lastName, etc. Only the customer.id will need to be passed. If you don’t re-pass this data to us, Sardine will use the existing name, email, phone, address, and SSN that exist in our records from the most recent customers API request
- NOTE this does not apply to advanced fields like personalInfo and custom fields; for such fields, merchants need to always pass these fields if they want to use them in rules.
Passing customer-level info
- Use the top-level customer object to send master customer data, e.g., firstName, lastName, etc.
- Do NOT use customer.personalInfo unless explicitly discussed with Sardine for your use-case
- customer.personalInfo is used only if you perform verification(s) via a non-Sardine third-party provider.
Retry mechanism
- As a best practice, we’d recommend you implement a retry mechanism as detailed here
Please review the JSON data with Sardine during development, before deploying this API in production. There may be some undocumented fields in our API response. Please ignore them as they may be present for backward compatibility or may be in beta.
curl --request POST \
--url https://api.sandbox.sardine.ai/v1/customers \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '{
"flow": {
"id": "37dc138c-9a3a-42ca-80de-030f8492cf2f",
"name": "kyc-email-phone",
"type": "onboarding"
},
"sessionKey": "37dc138c-9a3a-42ca-80de-030f8492cf2f",
"customer": {
"id": "e7654be0-43d7-438f-83ad-8f0196e9c179",
"createdAtMillis": 1655827465000,
"firstName": "Jane",
"middleName": "Jo",
"lastName": "Doe",
"dateOfBirth": "1988-08-08",
"address": {
"street1": "123 Sardine Street",
"street2": "Unit #101",
"city": "San Francisco",
"regionCode": "CA",
"postalCode": "94110",
"countryCode": "US"
},
"phone": "+11234567890",
"emailAddress": "jdoe@example.com",
"isPhoneVerified": false,
"isEmailVerified": true
},
"checkpoints": [
"customer"
]
}'
{
"sessionKey": "37dc138c-9a3a-42ca-80de-030f8492cf2f",
"level": "high",
"status": "Success",
"customer": {
"score": 0,
"level": "high",
"reasonCodes": [
"EF1",
"PNA",
"POS"
],
"signals": [
{
"key": "addressRiskLevel",
"value": "low"
},
{
"key": "emailDomainLevel",
"value": "low"
},
{
"key": "emailLevel",
"value": "high",
"reasonCodes": [
"EF1"
]
},
{
"key": "phoneCarrier",
"value": "Verizon"
},
{
"key": "phoneLevel",
"value": "low",
"reasonCodes": [
"PNA",
"POS"
]
},
{
"key": "phoneLineType",
"value": "Mobile"
},
{
"key": "manualReview",
"value": "false"
}
],
"phone": {
"nameScore": 100,
"addressScore": 100,
"cityMatch": true,
"regionMatch": true,
"postalCodeMatch": true
},
"address": {
"validity": "unknown"
}
},
"device": {
"id": "d5648820-912b-40c4-8e5b-4cc0ba8013ff",
"level": "low",
"attributes": {
"Browser": [
"Mobile Safari UI/WKWebView"
],
"Model": [
"iPhone"
],
"OS": [
"iOS"
]
},
"signals": [
{
"key": "TrueOS",
"value": "Mac/iOS"
},
{
"key": "DeviceAgeHours",
"value": "5"
},
{
"key": "TrueIP",
"value": "111.111.111.111"
},
{
"key": "VPN",
"value": "low"
},
{
"key": "Proxy",
"value": "low"
},
{
"key": "RemoteSoftware",
"value": "false"
},
{
"key": "RemoteSoftwareLevel",
"value": "low"
},
{
"key": "OSAnomaly",
"value": "low"
},
{
"key": "Emulator",
"value": "false"
},
{
"key": "TamperedApp",
"value": ""
},
{
"key": "IpType",
"value": "Fixed Line ISP"
},
{
"key": "SessionIpCount",
"value": "2"
},
{
"key": "SessionIpCountryCount",
"value": "1"
},
{
"key": "RemoteSessionLevel",
"value": ""
},
{
"key": "AccountDeviceId",
"value": "22357d9a-60e3-48f8-8977-803585acf147"
},
{
"key": "behaviorBiometricLevel",
"value": "low"
}
],
"sessionKey": "37dc138c-9a3a-42ca-80de-030f8492cf2f",
"fingerprint": "85618515-7924-4519-892b-e6a48bb230a9",
"confidenceScore": 0.4759486,
"fingerprintConfidenceScore": 48,
"deviceReputation": "medium_risk",
"behaviorBiometrics": {
"hesitationPercentile": {
"nonLtm": 0,
"ltm": 0
},
"numDistractionEvents": 0,
"numContextSwitchEvents": 0,
"typingSpeed": {
"typingSpeed": 0.0041813012209399565,
"upSpeed": 0.0783132530120482,
"downSpeed": 0.004427129449265097,
"firstKeySpeed": 0.0847457627118644,
"firstKeyUpSpeed": 0.0847457627118644,
"medianDownTime": 194,
"medianUpTime": 11,
"secondKeySpeed": 0.0027533039647577094,
"secondKeyDownSpeed": 0.002852253280091272,
"secondKeyUpSpeed": 0.07936507936507936,
"typingAccuracy": 1
},
"fields": [
{
"name": "first_name",
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": true,
"timeSpendInMsEvents": [
3453
],
"timeSpendInMs": 0
},
{
"name": "last_name",
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": true,
"timeSpendInMsEvents": [
1290
],
"timeSpendInMs": 0
},
{
"name": "company",
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": false,
"timeSpendInMsEvents": [
1020
],
"timeSpendInMs": 0
}
],
"pageFieldLTM": {
"absolute": {
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": false,
"timeSpendInMsEvents": null,
"timeSpendInMs": 5338
},
"percent": {
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": false,
"timeSpendInMsEvents": null,
"timeSpendInMs": 0
},
"average": {
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": false,
"timeSpendInMsEvents": null,
"timeSpendInMs": 2669
}
},
"pageFieldNonLTM": {
"absolute": {
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 1,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": false,
"timeSpendInMsEvents": null,
"timeSpendInMs": 24267
},
"percent": {
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": false,
"timeSpendInMsEvents": null,
"timeSpendInMs": 0
},
"average": {
"numCopyPasteEvents": 0,
"numClipboardEvents": 0,
"numAutoFillEvents": 0,
"numExpertKeyEvents": 0,
"hesitationPercentage": 0,
"isLTM": false,
"timeSpendInMsEvents": null,
"timeSpendInMs": 4853.4
}
},
"totalTimeSpentInMs": 59925,
"flowTimesInMs": {
"/onboarding/personal-details": 59925
}
},
"bot": {
"level": "low"
},
"ipLocation": {
"city": "San Francisco",
"region": "California",
"country": "US",
"latitude": "37.77",
"longitude": "-122.42"
},
"ipAddresses": {
"v4": "111.111.111.111",
"v6": "f289:7242:b06b:49db:dccd:ef2b:afc6:1bdf"
},
"checkpoints": {
"device": {}
}
},
"checkpoints": {
"customer": {
"customerPurchaseLevel": {
"value": "low",
"ruleIds": [
120,
124
]
},
"emailLevel": {
"value": "high",
"ruleIds": [
31
]
},
"phoneLevel": {
"value": "low",
"ruleIds": [
143
]
},
"historicalLevel": {
"value": "low",
"ruleIds": [
124
]
},
"riskLevel": {
"value": "low",
"ruleIds": [
31
]
}
}
},
"rules": [
{
"id": 124,
"isLive": true,
"isAllowlisted": false,
"name": "Rule name #1"
},
{
"id": 31,
"isLive": true,
"isAllowlisted": false,
"name": "Rule name #2"
},
{
"id": 120,
"isLive": true,
"isAllowlisted": false,
"name": "Rule name #3"
},
{
"id": 143,
"isLive": true,
"isAllowlisted": false,
"name": "Rule name #4"
},
{
"id": 227,
"isLive": false,
"isAllowlisted": false,
"name": "Rule name #5"
},
{
"id": 226,
"isLive": false,
"isAllowlisted": false,
"name": "Rule name #6"
}
],
"checkpointData": [
{
"name": "customer",
"type": "weighted_max"
}
]
}
Authorizations
Basic authentication header of the form Basic <encoded-value>
, where <encoded-value>
is the base64-encoded string username:password
.
Headers
Unique identifier for the request. Only alphanumeric character and dash is allowed.
72
Body
Customer details
User ID of the customer on your system. Please use the same value as passed to device intelligence SDK as UserIDHash.
100
Address
City
100
name of the company
100
2 letter Country code for the customer in ISO 3166-1 code e.g. US
2
Postal (Zip) code
20
The state or region for the customer. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is preferred
50
Street Address line 1
100
Street Address line 2
100
business name of the customer
100
Whether customer give a consent to pull data from carrier. 'unknown', 'optedIn' or 'optedOut'. Default 'unknown'
This is time the customer was onboarded/created in your system. Please pass it as Unix timestamp in milliseconds. e.g. 1622057169587 for Wed May 22021 19:26:09
0 < x < 4102444800000
The customer's date of birth in format YYYY-MM-DD. The API will return a 422 if the customer's age is <1 or >150 years old.
domain of business (eg sardine.ai)
email address of the user
100
first name of the customer
100
yearly income amount in major units, e.g., 50000.0 for fifty-thousand dollars
true if the email is verified by you
true if phone number is verified by you (eg via sending confirmation SMS)
last name of the customer
100
middle name of the customer
100
list of personal info such as name and email obtained from various sources
Address
City
100
name of the company
100
2 letter Country code for the customer in ISO 3166-1 code e.g. US
2
Postal (Zip) code
20
The state or region for the customer. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is preferred
50
Street Address line 1
100
Street Address line 2
100
The customer's date of birth in format YYYY-MM-DD. The API will return a 422 if the customer's age is <1 or >150 years old.
email address of the user
first name
document used for ID verification such as passport or driver's license
number of ID
Type of document: passport, driver_license or other
passport
, driver_license
, other
issuing country
issuing state or region
Dump of data you receive from third party provider. For instance if you use plaid for bank verification, please pass us JSON value of plaid's identity object
true if the email is verified by you
If user has been verified via KYC process
true if phone number is verified by you (eg via sending confirmation SMS)
last name
middle name
Nationality of the person in 2-digit ISO code
2
The customer's phone number in ISO E.164 format. e.g. USA: +14151231234, UK: +442012341234.
Source of personal information obtained via external third-party (non-Sardine) for verification. Discuss with Sardine before using.
id_verification
, bank_verification
, phone_verification
, onboarding
, payment
The customer's phone number in ISO E.164 format. e.g. USA: +14151231234, UK: +442012341234.
20
status of user in merchant's system: 'active' or 'inactive'
List of tags associated with the customer entity
Tag name, may contain alphanumeric characters and underscores only.
Tag value type. String and level are both strings, score and int are integer numbers and float is a floating number.
string
, level
, score
, int
, float
Tag value to save. May be a string or number (integer or float).
SSN or ITIN if customer is a end-user. EIN if customer is an company. <br/><b>IMPORTANT:</b> only populate when you have a valid SSN or EIN. Otherwise, omit this field altogether. Valid formats include: 123-45-6789 or 123456789. Do not send an empty string. <br/>The API will return a 422 if either an empty string or incorrect formatting is used.
This is the type of customer entity represented, e.g., standard end-user (customer), a vendor, business, etc.
customer (default)
, sole_proprietor
, vendor
, business
, tenant
, owner
, institutional
, retail
, courier
, driver
, controlling_officer
, beneficial_owner
, applicant
, coapplicant
, employee
identifies the current user flow such as onboarding, login or payment
Unique identifier for this flow event
Name of the event as defined on your end
The type of category event this request is for
signup
, onboarding
, login
, transaction
, password_reset
, password_change
, address_change
, email_change
, phone_change
, payment_method_link
, account_update
, logout
, other
, identity_verification
, 2fa_update
The timestamp in milliseconds of the event. This is only used when sending past event data (e.g. backfill) to specify the timestamp of that original event. You should omit this field for real-time events integrations.
0 < x < 4102444800000
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). Please refer to https://docs.sardine.ai/guides/integration/developerResources/sessionKeys#session-key-design for details
100
Name of the checkpoints to be invoked. Please discuss with Sardine. customer
checkpoint will be executed by default if checkpoints array is omitted and device
checkpoint will be run if a matching device sessionKey is found. Refer to checkpoints for recommended use cases, descriptions and prerequisites. Invalid checkpoints will return a 422 error.
Config Object. Default config values to enable/disable various Sardine functionality is done at merchant level. For some merchants, Sardine may allow overriding the default configuration. eg By default, sanction screening may be enabled for all api calls for a merchant and Sardine may allow selective sanction screening to be enabled via config.
Determines if Adverse Media screening should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
enabled
, disabled
Determines if bank consortium data enrichment should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
Determines whether card data enrichment screening should be performed for this request, provided that all required input data is valid. If not specified, the default behavior is determined by your account-level settings.
Determines if device intelligence and behaviour biometrics SDK data is expected for this session. Please set to false
for any flows where it is know the Sardine SDK is not integrated and no device data is collected.
If set to true
, the user from this request will not be subscribed to ongoing sanction monitoring. The default behavior if omitted is determined by your account-level setting. This flag can only be used to disable ongoing monitoring, setting it to false
will not subscribe a user to ongoing monitoring.
Determines if email data enrichment should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
Determined if the Sardine transaction indemnification details should be returned in the API response (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
Determines if Politically Exposed Person (PEP) screening should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
enabled
, disabled
Determines if phone data enrichment should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
If set to false, no riskLevel will be returned and this request will provide a one-way data feed to Sardine. By default, if this field is not provided, riskCheck is set to true. Please ensure you discuss this with your Integration Manager prior to implementing this config.
Determines if Sanction screening should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
enabled
, disabled
If set to true
, Sardine will sanction screen the counterparty (counterparty
field in API) of the transaction. By default, screenCounterparty
is set to false
. Please ensure you discuss this with your Integration Manager prior to implementing this config.
If set to true
, Sardine will sanction screen the bank of the counterparty (counterparty.paymentMethod
) of the transaction. By default, screenCounterpartyBank
is set to false
. Please ensure you discuss this with your Integration Manager prior to implementing this config.
Determines if Tax ID verification should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
Determines if crypto wallet verification should be run on this request (assuming valid required input data is provided). The default behavior if omitted is determined by your account-level setting.
Transaction counterparty information.
Counterparty id
This is the type of counterparty entity, e.g., standard end-user (customer), a vendor, business, etc.
customer (default)
, sole_proprietor
, vendor
, business
, tenant
, owner
, agent
, ceo
, executive
, unknown
Address
City
100
name of the company
100
2 letter Country code for the customer in ISO 3166-1 code e.g. US
2
Postal (Zip) code
20
The state or region for the customer. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is preferred
50
Street Address line 1
100
Street Address line 2
100
Business name. This field is required if the counterparty type is business
or unknown
.
The customer's date of birth in format YYYY-MM-DD. The API will return a 422 if the customer's age is <1 or >150 years old.
email address of the user
First name of the counterparty. This field is required if the counterparty type is customer
.
document used for ID verification such as passport or driver's license
number of ID
Type of document: passport, driver_license or other
passport
, driver_license
, other
issuing country
issuing state or region
Dump of data you receive from third party provider. For instance if you use plaid for bank verification, please pass us JSON value of plaid's identity object
true if the email is verified by you
If user has been verified via KYC process
true if phone number is verified by you (eg via sending confirmation SMS)
last name
middle name
Nationality of the person in 2-digit ISO code
2
Payment method information.
Type of payment method
card
, bank
, wire
, crypto
, wallet
, cash
, other
Bank information.
The name of the bank that is sending or receiving the payment.
Bank account number. MUST be at least 5 digits, otherwise the API will return a 422. This field is required in the context of counterparty screening if a routingNumber
is provided.
5 - 100
type of bank account
checking
, saving
, certificate
, loan
, other
last known bank balance in fractional units like cents
3-digit ISO 4217 currency code
3
The full form of BIC is Bank Identifier Code. BIC is also better known as SWIFT ID, SWIFT-BIC, or SWIFT code, and it can be defined as a distinctive alpha-numerical identification code that is approved by the ISO or International Organization for Standardization. This field or ibanFull
or routingNumber
is required in the context of counterparty screening.
check number
classification of bank account such as business, personal or other
An IBAN, or international bank account number, is a standard international numbering system developed to identify an overseas bank account. This field or bicFull
or routingNumber
is required in the context of counterparty screening.
id of bank in your system or in third party api (eg plaid)
source of id field (eg plaid)
indicates if the bank transfer is an international (cross-border) transaction
Bank routing number. This field or bicFull
or ibanFull
is required in the context of counterparty screening.
5 - 100
Sort code
ACH, sameDayACH, eCheck, fastPayment, RTP, FedNow, IAT or interbank
ACH
, sameDayACH
, eCheck
, fastPayment
, RTP
, FedNow
, IAT
, interbank
Address
City
100
name of the company
100
2 letter Country code for the customer in ISO 3166-1 code e.g. US
2
Postal (Zip) code
20
The state or region for the customer. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is preferred
50
Street Address line 1
100
Street Address line 2
100
Card information
Balance of debit card / prepaid card in fractional units like cents
3-digit ISO 4217 currency code
3
Bin (first 6 or 8 digits) of card number. <br/>IMPORTANT: Please note that for American Express (AMEX) cards, this is always the first 6 digits of the card number. <br/><br/>For all other cards, please simply pull the BIN from the card (either first 6 or 8 for Discover, JCB, Mastercard, UnionPay, or Visa).
6 - 8
Two-letter ISO code representing the country of the card BIN (bank identification number)
2
Card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Information you get as part of credit card authorization
Result of 3DS. Valid values are: success, issuer_not_supported, signature_verification_failed, rejected, frictionless_failed, error, and bypassed
Reason code returned by AVS check from processor
Result of AVS check for street address. match, nomatch, not_verified, error or nodata.
Result of AVS check for zip code. match, nomatch, not_verified, error or nodata.
Result of cvv match check. match, nomatch, not_verified, not_supported, or error.
name of card processor
status of card authorization request such as approved or declined.
Example - 10000, 20001. This could be an authorization code or a decline code.
Expiration month of the card used for this transaction; should be a value between 1-12
1 < x < 12
Expiration year of the card used for this transaction; min value is 2022 and the max value is 2100.
2022 < x < 2100
Sha-256 hash of card number (PAN). Please use a salt with the SHA256 algorithm on the PAN. If you cannot provide a hash of the full card number, please use some unique identifier here noting that it's this particular card without containing the actual card number, e.g., row id in your db. Lastly, please do not pass this field as a hash of only BIN + last4 as it may cause false positives.
If ownership of card is verified via card 2FA (sending small amount authorization to card and asking user to confirm authorization details) or any other means
Last 4 digit of card number
4
Crypto wallet address
crypto address
Crypto asset symbol e.g. USDT, BTC, ETH etc.
Cryptocurrency network or blockchain of the given asset.
algorand
, aptos
, arbitrum
, avalanche_c_chain
, base
, binance
, binance_smart_chain
, bitcoin
, bitcoin_cash
, bytom
, cardano
, celo
, cosmos
, dash
, dogecoin
, elastos
, ethereum
, ethereum_classic
, elrond
, filecoin
, hedera
, icon
, iost
, iota
, klaytn
, lisk
, litecoin
, monero
, nebulas
, neo
, oasis
, omni
, ontology
, optimism
, pai
, polkadot
, polygon
, qtum
, ripple
, solana
, sonic
, steem
, stellar
, tezos
, tron
, unichain
, zcash
, zilliqa
The identifier uniquely identify the transaction.
first name
last name
middle name
Other payment method
ID of payment method
Type of payment method
extra metadata about the payment method
If payment method has been verified by 2fA (for example, sending small amount authorization to card and asking user to confirm authorization details)
Wallet such as ApplePay
ID of the payment method.
This is the actual token value for this particular wallet. This would be the Device Account Number (DAN) for Apple Pay, Virtual Account Number for Google Pay, and Digital Card Number for Samsung Pay.
This is the BIN value of the token, could be the first 6 or 8, depending on the card.
6 - 8
Brand of card in lowercase. Example values: visa, mastercard, amex.
This is the last four digits of the token.
4
Type of the wallet
apple_pay
, google_pay
, samsung_pay
, amazon_pay
, venmo
, paypal
, cash_app
, phonepe
, ola
, internal
, other
, unknown
Bank account details
bank account number
5 - 100
name of the bank
bank routing code(IRC)
100
last known bank balance in fractional units like cents
3-digit ISO 4217 currency code
3
International Bank Account Number
Swift Code
international_wire, domestic_wire
international_wire
, domestic_wire
The customer's phone number in ISO E.164 format. e.g. USA: +14151231234, UK: +442012341234.
Source of personal information obtained via external third-party (non-Sardine) for verification. Discuss with Sardine before using.
id_verification
, bank_verification
, phone_verification
, onboarding
, payment
List of tags associated with the counterparty entity.
Tag name, may contain alphanumeric characters and underscores only.
Tag value type. String and level are both strings, score and int are integer numbers and float is a floating number.
string
, level
, score
, int
, float
Tag value to save. May be a string or number (integer or float).
Key-value pair for boolean type custom fields to be made available in the dashboard and rule editor.
key-value pair for number type custom fields to be made available in the dashboard and rule editor.
Key-value pair for string type custom fields to be made available in the dashboard and rule editor.
Device details
This is the time the device was seen in your system. Please pass it as a Unix timestamp in milliseconds. e.g., 1622057169587 for Wed May 22021 19:26:09
0 < x < 4102444800000
Fingerprint of the device/browser
ID of device given by specified source (see source parameter below)
IP address with which device is associated to. can be either IPv4 or IPV6
The accept-language HTTP header (Language Culture Name). Examples: (en-EN, de-DE)
Source from where the deviceId was created, e.g., Sardine, Merchant A, Other. Please note: if the source provided is not 'Sardine', IP-related details will be returned in the place of device intelligence features
Indicating if device is blocked by your system. allowed or blocked
allowed
, blocked
userAgent header
ID of the partner/business/merchant this event is tied to
100
Name of the partner/business/merchant this event is tied to
100
Referral code
amount tied to the referral in major currency unit (eg dollars)
The referral code used for this event by the customer
currency code for the amount tied to the referral
3
ID of user who issued the referral code used by the customer
Transaction details
ID of the transaction (defined by you) e.g. Order Number
Indicates the type of transaction. It is used to determine the direction of the money movement from the customer perspective as outward (buy, withdraw, transfer, loanRepayment, multiParty, exchange (if paymentMethodType!=crypto)) or inward (sell, deposit, topup, refund, loanFunding, exchange (if paymentMethodType==crypto)). If omitted, Sardine considers the transaction as an outward money movement.
buy
, sell
, deposit
, withdraw
, refund
, topup
, exchange
, transfer
, multiParty
, loanRepayment
, loanFunding
, credit
, debit
Amount of transaction, it can only be zero in the case of a $0 card auth. In the case of adding/linking a card or bank account, omit this field altogether. Note: This is a float number in major units (e.g. dollar amount for USD)
Tranasction timestamp as unix timestamp in milliseconds. If you risk score the transaction in realtime you can omit this field. This field can be provided when you backfill past transaction data.
0 < x < 4102444800000
Indicates whether this transaction is considered inward or outward as it relates to aggregations. Please consult with Sardine prior to implementing this field.
Main item category in cart. e.g. crypto asset(ETH, BTC), gift card, alcohol, generic
List of items in the transaction
Is this a digital or physical good
The category of the item, e.g., ELECTRONICS, ALCOHOL, etc.
Name of the item
Quantity of items
1 < x < 10000000
SKU of item
Total price for all items
Unit price of item
Full URL to the item listing
mcc (merchant category code) for this transaction
Note associated with the transaction.
Payment Method
Type of payment method
card
, bank
, wire
, crypto
, wallet
, cash
, other
Bank account details
The name of the bank that is sending or receiving the payment.
bank account number. MUST be at least 5 digits, otherwise the API will return a 422
5 - 100
type of bank account
checking
, saving
, certificate
, loan
, other
last known bank balance in fractional units like cents
3-digit ISO 4217 currency code
3
The full form of BIC is Bank Identifier Code. BIC is also better known as SWIFT ID, SWIFT-BIC, or SWIFT code, and it can be defined as a distinctive alpha-numerical identification code that is approved by the ISO or International Organization for Standardization.
check number
classification of bank account such as business, personal or other
An IBAN, or international bank account number, is a standard international numbering system developed to identify an overseas bank account.
id of bank in your system or in third party api (eg plaid)
source of id field (eg plaid)
indicates if the bank transfer is an international (cross-border) transaction
bank routing number
5 - 100
Sort code
ACH, sameDayACH, eCheck, fastPayment, RTP, FedNow, IAT or interbank
ACH
, sameDayACH
, eCheck
, fastPayment
, RTP
, FedNow
, IAT
, interbank
Address
City
100
name of the company
100
2 letter Country code for the customer in ISO 3166-1 code e.g. US
2
Postal (Zip) code
20
The state or region for the customer. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is preferred
50
Street Address line 1
100
Street Address line 2
100
Card information
Balance of debit card / prepaid card in fractional units like cents
3-digit ISO 4217 currency code
3
Bin (first 6 or 8 digits) of card number. <br/>IMPORTANT: Please note that for American Express (AMEX) cards, this is always the first 6 digits of the card number. <br/><br/>For all other cards, please simply pull the BIN from the card (either first 6 or 8 for Discover, JCB, Mastercard, UnionPay, or Visa).
6 - 8
Two-letter ISO code representing the country of the card BIN (bank identification number)
2
Card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Information you get as part of credit card authorization
Result of 3DS. Valid values are: success, issuer_not_supported, signature_verification_failed, rejected, frictionless_failed, error, and bypassed
Reason code returned by AVS check from processor
Result of AVS check for street address. match, nomatch, not_verified, error or nodata.
Result of AVS check for zip code. match, nomatch, not_verified, error or nodata.
Result of cvv match check. match, nomatch, not_verified, not_supported, or error.
name of card processor
status of card authorization request such as approved or declined.
Example - 10000, 20001. This could be an authorization code or a decline code.
Expiration month of the card used for this transaction; should be a value between 1-12
1 < x < 12
Expiration year of the card used for this transaction; min value is 2022 and the max value is 2100.
2022 < x < 2100
Sha-256 hash of card number (PAN). Please use a salt with the SHA256 algorithm on the PAN. If you cannot provide a hash of the full card number, please use some unique identifier here noting that it's this particular card without containing the actual card number, e.g., row id in your db. Lastly, please do not pass this field as a hash of only BIN + last4 as it may cause false positives.
If ownership of card is verified via card 2FA (sending small amount authorization to card and asking user to confirm authorization details) or any other means
Last 4 digit of card number
4
Crypto wallet address
crypto address
Crypto asset symbol e.g. USDT, BTC, ETH etc.
Cryptocurrency network or blockchain of the given asset.
algorand
, aptos
, arbitrum
, avalanche_c_chain
, base
, binance
, binance_smart_chain
, bitcoin
, bitcoin_cash
, bytom
, cardano
, celo
, cosmos
, dash
, dogecoin
, elastos
, ethereum
, ethereum_classic
, elrond
, filecoin
, hedera
, icon
, iost
, iota
, klaytn
, lisk
, litecoin
, monero
, nebulas
, neo
, oasis
, omni
, ontology
, optimism
, pai
, polkadot
, polygon
, qtum
, ripple
, solana
, sonic
, steem
, stellar
, tezos
, tron
, unichain
, zcash
, zilliqa
The identifier uniquely identify the transaction.
first name
last name
middle name
Other payment method
ID of payment method
Type of payment method
extra metadata about the payment method
If payment method has been verified by 2fA (for example, sending small amount authorization to card and asking user to confirm authorization details)
Wallet such as ApplePay
ID of the payment method.
This is the actual token value for this particular wallet. This would be the Device Account Number (DAN) for Apple Pay, Virtual Account Number for Google Pay, and Digital Card Number for Samsung Pay.
This is the BIN value of the token, could be the first 6 or 8, depending on the card.
6 - 8
Brand of card in lowercase. Example values: visa, mastercard, amex.
This is the last four digits of the token.
4
Type of the wallet
apple_pay
, google_pay
, samsung_pay
, amazon_pay
, venmo
, paypal
, cash_app
, phonepe
, ola
, internal
, other
, unknown
Bank account details
bank account number
5 - 100
name of the bank
bank routing code(IRC)
100
last known bank balance in fractional units like cents
3-digit ISO 4217 currency code
3
International Bank Account Number
Swift Code
international_wire, domestic_wire
international_wire
, domestic_wire
The promotion category
store_credit
, egift_card
, coupon_code
, automatic_coupon
The code that the user input
The text description of this promotion code
The promotion discount type
fixed_amount
, percentage
, free_shipping
amount received by the receiver
3-digit ISO 4217 currency code for the receiver
3
amount sent by the sender
3-digit ISO 4217 currency code for the sender
3
Address
City
100
name of the company
100
2 letter Country code for the customer in ISO 3166-1 code e.g. US
2
Postal (Zip) code
20
The state or region for the customer. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is preferred
50
Street Address line 1
100
Street Address line 2
100
Shipping method carrier
How is this being fulfilled, e.g., delivery vs. pickup
Latest delivery time as unix timestamp
0 < x < 4102444800000
Earliest delivery time as unix timestamp
0 < x < 4102444800000
The cost of this shipping method
Name of the shipping method
Carrier-provided tracking number
status of transaction. pending, accepted, denied_fraud or denied. Default is pending.
pending
, accepted
, denied_fraud
, denied
subscription ID for this recurring payment
name of the workflow to be run (if using workflows instead of the checkpoints
array)
100
Response
List of checkpoints run for this session
Name of the checkpoint
Total score from all live rules triggered in the checkpoint. Only returned for weighted_sum type checkpoints
0 < x < 10000000
Type of the checkpoint
weighted_max
, weighted_sum
, score
Result of rule evaluations for each checkpoint. customer
checkpoint is executed by default.
information about AML (sanction, pep, adversemedia) screening
List of adverse media check result
category of the data source
description of the data source
name of data source
url of the data source
sub-category of the data source
list of alias of the entity
list of citizenships
A list of country codes in 2-letter ISO 3166 format
list of date of births
name of the entity that matches given data
list of ID document information
The issuing country of the ID submitted for verification
The ID number submitted for verification
The type of ID submitted for verification
possible score 0 to 100 higher the closer match. represents how close the entity match the given data
0 < x < 100
list of nationalities
List of PEP (Politically Exposed Person) check result
category of the data source
description of the data source
name of data source
url of the data source
sub-category of the data source
list of postal addresses
possible score 0 to 100 higher the riskier. represents how risky a entity is.
0 < x < 100
List of sanction check result
category of the data source
description of the data source
name of data source
url of the data source
sub-category of the data source
counterparty payment method
information about AML (sanction, pep, adversemedia) screening for payment method (eg sanction screening result for counterparty bank)
List of adverse media check result
category of the data source
description of the data source
name of data source
url of the data source
sub-category of the data source
list of alias of the entity
list of citizenships
A list of country codes in 2-letter ISO 3166 format
list of date of births
name of the entity that matches given data
list of ID document information
The issuing country of the ID submitted for verification
The ID number submitted for verification
The type of ID submitted for verification
possible score 0 to 100 higher the closer match. represents how close the entity match the given data
0 < x < 100
list of nationalities
List of PEP (Politically Exposed Person) check result
category of the data source
description of the data source
name of data source
url of the data source
sub-category of the data source
list of postal addresses
possible score 0 to 100 higher the riskier. represents how risky a entity is.
0 < x < 100
List of sanction check result
category of the data source
description of the data source
name of data source
url of the data source
sub-category of the data source
customer riskiness level and associated signals
Address verification result
Whether the customer provided address is valid or not. Possible values - valid, invalid, unknown.
valid
, invalid
, unknown
AML (sanction, PEP, adversemedia) check result
List of adverse media check result
category of the data source
description of the data source
name of data source
url of the data source
sub-category of the data source
list of alias of the entity
list of citizenships
A list of country codes in 2-letter ISO 3166 format
list of date of births
name of the entity that matches given data
possible score 0 to 100 higher the closer match. represents how close the entity match the given data
0 < x < 100
list of nationalities