Socure Connector

The Socure connector lets you verify identity documents and get fraud scores in your PingOne DaVinci flows.

The connector allows you to direct users to a unique verification URL where they submit their driver license or passport along with selfie photos. After Socure verifies the user’s identity, it sends the results to DaVinci where you can branch your flow accordingly.

To make sure a camera is available to scan the documents and take photos, the user typically completes the verification process on a mobile device.

Setup

Resources

For information and setup help, see the following:

DaVinci documentation:

Requirements

To use the connector, you’ll need a Socure license.

Configuring the Socure connector

Add the connector in DaVinci as shown in Adding a connector, then configure it as follows.

Connector configuration

ID+ Key

Your Socure ID+ key, such as “a1b234cd-75e1-9e01-f234-56abcdef6789”.

Get this key from Setting up Socure.

SDK Key

Your Socure SDK key, such as "d450e856-9e01-75e1-8cec-64efe8eef39b".

Get this key from Setting up Socure.

API URL

The Socure API URL to target. Select the environment that you chose in Getting your Socure ID+ and SDK keys.

Get this URL from Setting up Socure.

Webhook URL

The DaVinci webhook URL for this instance of your connector.

Copy this URL. You’ll use it in Setting up Socure.

Setting up Socure

Allowing the DaVinci webhook URL in your Socure configuration

Sign on to the Socure administrator portal at https://admin.socure.com.
Go to Developer → Webhook. Click New Webhook.
In the Subscription Type list, select Document Verification.
In the Subscription Channel Name field, enter a name.
In the Webhook URL field, enter the webhook URL that you copied from your Socure connector configuration.
Leave the Secret Key field blank.
Leave the Choose certificate section blank.
Click Test. Check that the test was successful.

Allowing the DaVinci domain in your Socure configuration

Click Create.

See IP address and domain reference for a list of domains that DaVinci uses. Follow the steps below to add all the domains for your region:

Sign on to the Socure administrator portal at https://admin.socure.com.
Go to Developers → IPs & Domains.
Click New Domain.
In the IP/DOMAINS field, enter the domain. Click Create.
Repeat this process for each DaVinci domain in your region.

Getting your Socure ID+ and SDK keys

Your ID+ Key and SDK Key are different for each environment.

Sign on to the Socure administrator portal at https://admin.socure.com.
Select the environment you want to connect to:
1. Click your organization.
2. Click to select the Production, Certification, or Sandbox environment.
3. Go to Developers → ID+ Keys and SDK Key to get your ID+ and SDK keys.

Using the connector in a flow

Verify identity documents with a link or QR code

A screen capture of the complete verify document flow.

This flow uses Socure to get a unique verification URL and show it as a link and QR code in the user’s web browser. When the user opens the link with their mobile device, they are guided through the process of submitting photos of their identification card (either a driver license or passport) and taking a selfie photo. After the documents and photos are accepted, the flow continues where it started in the web browser.

This flow creates a "challenge" to pause the main flow on the QR code while a secondary flow continues the verification process. When the verification process is complete, a Challenge connector resolves the challenge and triggers the main flow to continue. To learn more about this technique, see the Challenge connector.

Download the Socure - Identity verification with link or QR code flow template. For help, see Using DaVinci flow templates.
On the flow canvas, select the Get a Document Verification URL and QR Code node.
(Optional) In the Customer User ID field, change the value to a test user ID that exists in your Socure records. In a real-world flow, click {} and populate this with a variable from earlier in your flow.
(Optional) Customize the document verification prompt:
1. Select the Verification Prompt node.
2. In the Message Title field, customize the title of the prompt.
3. In the Message field, customize the user-facing text.
4. Click Apply.
Test the flow:
1. Click Save, Deploy, and Try Flow.
2. With your mobile device, scan the QR code and open the link.
3. Complete the document verification process on your mobile device.
4. See the result in your web browser on the original device.

Verify identity documents with an SMS prompt

In this flow, Socure prompts the user to enter their phone number in their web browser. Socure sends an SMS message to the number, which guides the user through the process of submitting photos of their identification card (either a driver license or passport) and taking a selfie photo. After the documents and photos are accepted, the flow continues where it started in the web browser.

Download the Socure - Identity verification with SMS prompt flow template. For help, see Using DaVinci flow templates.
(Optional) Customize the "Check Your Device" message:
1. Select the Check Your Device node.
2. In the Message Title field, customize the title of the prompt.
3. In the Message field, customize the user-facing text.
4. Click Apply.
Test the flow:
1. Click Save, Deploy, and Try Flow.
2. Register a new user or sign in with an existing user.
3. Enter your mobile device SMS number.
4. Complete the document verification process on your mobile device.
5. See the result in your web browser on the original device.

Getting ID+ scores

A screen capture of the complete Get ID+ scores flow

You can use the connector to get a variety of risk scores, fraud scores, and other information based on information you provide about a person or device.

This flow sends information about a person to Socure then shows the resulting score. You can customize the information you send to and get from Socure.

Download the Socure - ID+ score check flow template. For help, see Using DaVinci flow templates.

Select the Socure ID+ modules that you want to use:

On the flow canvas, select the Get an ID+ Score node.

In the Modules list, select one or more modules.

Socure ID+ modules represent a variety of data sources that verify identities. For more information, see ID+ Modules in the Socure documentation.

When you use the Get an ID+ Score capability, you can select as many modules as you want, with the following limitations:

Only select modules that you have a license to use in Socure.
Only select one Global Watchlist module.
If you select the Decision module, you have to select at least one other module. For more information, see Decision in the Socure documentation.
The Device Risk capability requires a device session ID. To get a session ID, include the device profiling script in your web app. The script sends a device profile to Socure and provides a session ID that DaVinci uses to get the device risk score. For help, see Sigma Device Client-Side Javascript in the Socure documentation.

Populate the personal attributes by clicking {} and selecting variables from your flow.

For demonstration purposes, the flow template includes an HTML form with pre-filled information. When you build your own flow, you can collect information about the person from a form, database, or another source in your flow.

Populate the Document UUID field with the unique ID for an identity document that the person submitted.
Click Apply.
Test the flow:
1. Click Save, Deploy, and Try Flow.
2. Submit the HTML form.

Capabilities

Verify a Document

Verify the authenticity of an identity document. This uses the Socure Predictive Document Verification Web SDK.

Show details

Properties
Input Schema

screen0Config

title textField

Default:

Socure Document Verification

bodyHeaderText textField

Default:

Receive you Document verification URL through SMS

Verification Level dropDown required

Set the verification process workflow for the transaction.

Document upload only (Default)
Document upload and document verification
Document upload, document verification, and Phone RiskScore

Country textField

Two letter ISO Country

registerInitiate object
- properties object
  - sdkKey string required
- parameters object
  - phoneNumber string required minLength: 6
registerComplete object
- parameters object
  - referenceId string
  - credId string

Wait for the Documentation Verification Result

Wait for Socure to send the result of a document verification check to the DaVinci webhook URL.

Show details

Output Schema

output object
- rawResponse object
  - id string
  - origId string
  - eventGroup string
  - reason string
  - environmentName string
  - event object
    
    eventType string
    
    data object
    
    address string
    
    dob string
    
    documentNumber string
    
    expirationDate string
    
    firstName string
    
    surName string
    
    fullName string
    
    parsedAddress object
    
    referenceId string
    
    customerUserId number
    
    message string
- uuid string
The value will be undefined for events other than DOCUMENTS_UPLOADED.
- challenge string
- credentialStatusObject object
  - detailStatus string
  - rawStatus object
  - challenge string
  - credId string
  - userId string

Output Example

 { "rawResponse" :
  { "id" : "efgh2345-6fg7-89h0-12ij-3k4567l890n",
   "origId" : "af096ad4-b9ba-4935-a148-61837aa535c4",
   "eventGroup" : "DocvNotification",
   "reason" : "DOCUMENTS_UPLOADED",
   "environmentName" : "production",
   "event" :
   { "eventType" : "DOCUMENTS_UPLOADED",
    "data" :
    { "address" : "965 Maxwell Street Petty, TX 75470",
     "dob" : "1979-05-07",
     "documentNumber" : "SOC86753099",
     "expirationDate" : "2022-10-13",
     "firstName" : "John",
     "surName" : "Smith",
     "fullName" : "John Smith",
     "parsedAddress" :
     {  } },
    "referenceId" : "abcd1234-5ef6-78g9-01hi-2j3456k7890m",
    "customerUserId" : 121212,
    "message" : "Documents Upload Successful" } },
  "challenge" : "66680a42-2d4d-408f-aa64-f40c8dd752d0",
  "credentialStatusObject" :
  { "detailStatus" : "VERIFICATION_COMPLETED",
   "rawStatus" :
   {  },
   "challenge" : "66680a42-2d4d-408f-aa64-f40c8dd752d0",
   "credId" : "6d9vb6l0p2e56jgfsha7oke318akm556",
   "userId" : "1f9cd66c12e46eaf15c7e2e318a7c5d3" } }

Get an ID+ Score

Get a Socure ID+ score for a user based on the ID+ modules that you select. The result is a number between 0 and 1, with a higher value indicating higher probability of fraud.

Show details

Properties
Input Schema
Output Schema

modules dropDownMultiSelect
First Name textField
Sur Name textField
Email textField
Country textField
Physical Address textField
Physical Address 2 textField
City textField
State textField
Zip textField
Mobile Number textField
Geocodes (lat long) textField
National ID textField
Date of Birth textField
Company Name textField
Document UUID textField
Order Amount textField
Account Creation Date textField
Submission Date textField
Previous Order Count textField
Last Order Date textField
Order Channel textField
Customer User ID textField: The unique identifier for the user, such as "123".
Watchlist Filters textField
Recipient Country textField
Payment Type textField
Disbursement Type textField
Operation System textField
Device Type textField
Device Session ID textField
Device Interface textField

login object
- properties object
  - baseUrl string required
  - apiKey string required
  - modules array required
- ip string
- userAgent string

output object
- rawResponse object
  - referenceId string
  - nameAddressCorrelation object
    
    reasonCodes array
    
    score number
  - namePhoneCorrelation object
    
    reasonCodes array
    
    score number
  - fraud object
    
    reasonCodes array
    
    scores array
  - kyc object
    
    reasonCodes array
    
    cvi integer
    
    correlationIndices object
    
    nameAddressPhoneIndex integer
    
    nameAddressSsnIndex integer
    
    decision object
    
    modelName string
    
    modelVersion string
    
    status string
    
    fieldValidations object
    
    firstName number
    
    surName number
    
    streetAddress number
    
    city number
    
    state number
    
    zip number
    
    mobileNumber number
    
    dob number
    
    ssn number
  - addressRisk object
    
    reasonCodes array
    
    score number
  - emailRisk object
    
    reasonCodes array
    
    score number
  - phoneRisk object
    
    reasonCodes array
    
    score number

Output Example

 { "rawResponse" :
  { "referenceId" : "123a456b-789c-1234-567c-9307e6e0a83f",
   "nameAddressCorrelation" :
   { "reasonCodes" :
    [ "I709",
     "I708",
     "I710" ],
    "score" : 0.9096 },
   "namePhoneCorrelation" :
   { "reasonCodes" :
    [ "I621",
     "I622",
     "I618" ],
    "score" : 0.9984 },
   "fraud" :
   { "reasonCodes" :
    [ "I610",
     "I626",
     "I705",
     "I609",
     "I553",
     "I611",
     "I614",
     "I127",
     "I630",
     "I708",
     "I618",
     "I555",
     "I707",
     "I602" ],
    "scores" :
    [
     { "name" : "sigma",
      "version" : "1.0",
      "score" : 0.167 } ] },
   "kyc" :
   { "reasonCodes" :
    [ "I919" ],
    "cvi" : 0,
    "correlationIndices" :
    { "nameAddressPhoneIndex" : 0,
     "nameAddressSsnIndex" : 0 },
    "decision" :
    { "modelName" : "SOCURE_FIX",
     "modelVersion" : "1.0",
     "status" : "REFER" },
    "fieldValidations" :
    { "firstName" : 0.99,
     "surName" : 0.99,
     "streetAddress" : 0.99,
     "city" : 0.99,
     "state" : 0.99,
     "zip" : 0.99,
     "mobileNumber" : 0.99,
     "dob" : 0.99,
     "ssn" : 0.99 } },
   "addressRisk" :
   { "reasonCodes" :
    [ "I610",
     "I705",
     "I720",
     "I708",
     "I707" ],
    "score" : 0.364 },
   "emailRisk" :
   { "reasonCodes" :
    [ "I520",
     "I553",
     "I555" ],
    "score" : 0.133 },
   "phoneRisk" :
   { "reasonCodes" :
    [ "I610",
     "I626",
     "I609",
     "I620",
     "I611",
     "I614",
     "I630",
     "I618",
     "I602" ],
    "score" : 0.122 } } }

Make Custom API Call

Define and invoke custom call to the Socure REST API.

Show details

Properties
Input Schema
Output Schema

Endpoint textField required

The Socure API endpoint, such as /api/3.0/EmailAuthScore.

HTTP Method dropDown required

The HTTP method of the API call.

GET
POST
PUT
DELETE

Query Parameters keyValueList

Define additional query parameters to send to Socure.

Additional Headers keyValueList

Additional headers for the request. Connector automatically adds 'Authorization' and 'Content-Type' headers.

Body codeEditor

The body of the API call.

default object
- properties object
  - apiKey string required
  - endpoint string required
  - method string required
  - queryParams array
  - headers array
  - bodyData object

Input Example

 { "properties" :
  { "endpoint" : "/api/3.0/EmailAuthScore",
   "method" : "POST",
   "bodyData" :
   { "modules" :
    [ "addressrisk" ],
    "firstName" : "John",
    "surName" : "Smith",
    "physicalAddress" : "123 Example Street",
    "physicalAddress2" : "Apt. 5",
    "city" : "New York",
    "state" : "NY",
    "zip" : "10001",
    "country" : "us" } } }

output object
- headers object
- statusCode integer
- rawResponse object

Get a Document Verification URL and QR Code

Get a unique document verification URL and QR code based on a user identifier.

Show details

Properties
Input Schema
Output Schema

Verification Level dropDown required

Set the verification process workflow for the transaction.

Document upload only (Default)
Document upload and document verification
Document upload, document verification, and Phone RiskScore

Customer User ID textField

The unique identifier for the user, such as "123".

Phone Number textField

Used with Verification Level 3

Country textField

Two letter ISO Country

documentVerificationUrl object::

output object
- qrcode string
- url string

Connectors

Socure Connector

Setup

Resources

Requirements

Configuring the Socure connector

Connector configuration

ID+ Key

SDK Key

API URL

Webhook URL

Setting up Socure

Allowing the DaVinci webhook URL in your Socure configuration

Allowing the DaVinci domain in your Socure configuration

Getting your Socure ID+ and SDK keys

Using the connector in a flow

Verify identity documents with a link or QR code

Verify identity documents with an SMS prompt

Getting ID+ scores

Capabilities

Verify a Document

Wait for the Documentation Verification Result

Get an ID+ Score

Make Custom API Call

Get a Document Verification URL and QR Code