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.
Authorizations
Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.
Body
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)
ID of the partner/business/merchant this event is tied to
Name of the partner/business/merchant this event is tied to
name of the workflow to be run (if using workflows instead of the checkpoints array)
Customer details
Transaction
Personal information obtained via third-party external to Sardine
Device details
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.
Key-value pair for string type custom fields to be made available in the dashboard and rule editor. Example: ”customerSegment”:”premium”
Key-value pair for boolean type custom fields to be made available in the dashboard and rule editor.
Example: ”verifiedCustomer": true
key-value pair for number type custom fields to be made available in the dashboard and rule editor.
Example: ”internalRiskScore": 57
Referral code
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.
ach, aml, aml_bank, aml_crypto, customer, device, kyc, login, onboarding, payment, withdrawal Response
Unique identifier for the given customer session as provided by you in the API request payload
Risk at overall level: "very_high", "high", "medium", "low". This is the top-level field that you can use to make a risk decision. It is max of customer.level and device.level
status of the API response
Success, Timeout customer riskiness level and associated signals
Device riskiness level and associated signals
transaction related information
Result of rule evaluations for each checkpoint. customer checkpoint is executed by default.
List of live and shadow rules that triggered for this session
List of checkpoints run for this session
workflow excecution output data if a workflowName was provided in the request