Using the Paysafe Identity Verification API

POST /identity/v1/accounts/account_id/identifications

To confirm the identity of a Canadian or American business owner, you must initiate a POST request to the identity endpoint of the Account Management API. This POST request contains an identityId parameter. To get the value for this parameter, you first have to use the Paysafe Identity Verification API to verify the identity of the business owner. A successful response from the Identity Verification API will contain an id parameter – this is the value you need to use for the identityId parameter in the Identity Verification request you send via the Account Management API.

How It Works

When you sign up with Paysafe to use the Account Management API, you will receive a URL for the Identity Verification API, to which you send your requests. The URL for the initial POST looks like this:

https://api.paysafe.com/identity/v1/accounts/account_id/identifications

  • This URL will have an actual value for account_id that will allow you to POST the request to the Identity Verification API.
  • Use your Account Management API key for this request to the Identity Verification API.

The full payload of the request is displayed in the example below. See Identification Request Elements for a description of the elements to include.

Here is a brief overview:

  1. Send an Identity Verification POST request to the Paysafe Identity Verification API, using the URL provided to you by Paysafe and containing identification data provided by the business owner (merchant).
  2. Receive a successful response from Paysafe, which includes Challenge questions.
  3. Present the Challenge questions to your merchant.
  4. Your merchant answers Challenge questions.
  5. Send a Challenge PUT request to the Paysafe Identity Verification API, containing your merchant's responses.
  6. Receive a successful response from Paysafe, which contains an id.
  7. Use this id value as the identityId in the business owner identity request you POST to the identity endpoint in the Account Management API.
  8. Receive a response from the Paysafe Account Management API indicating that the merchant identity was successfully confirmed.

Business Owner Identity Work Flow

Sending an Identity Verification Request

Request Example
curl -X POST https://api.test.paysafe.com/identity/v1/accounts/1001374444/identifications \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
  -d ' {
    "merchantRefNum": "MerchantRef12345678",
    "profile": {
        "firstName": "Jane",
        "middleName": "Alice",
        "lastName": "Todd",
        "ssn": "123456789",
        "email": "jane.todd@email.com",
        "billingDetails": {
            "street": "155 Elmdale Ave",
            "city": "Boulder City",
            "zip": "90256",
            "state": "CA",
            "country": "US"
        },
        "dateOfBirth": {
            "day": 25,
            "month": 8,
            "year": 1985
        }
    },
    "customerIp": "123.123.123.123"
}'

Prior to trying the example above, you should:

  • Replace the account number (1001374444) in the URL with the Test account number you received.
  • Replace the API key (after the -u) with the API key you have received

For Canadian merchants, see Identification Request Test Values for Canadian Merchants for the values to use for the Identity Verification request in the Test environment.

For US merchants, please contact our Integrations team for the values to use for the Identity Verification request in the Test environment.

The Test account number used here for the Identity Verification API is not the same as the Test account number you use for the Account Management API.

Successful Response Example with Challenge Questions
{
	"links": [{
		"rel": "self",
		"href": "https://api.test.paysafe.com/identity/v1/accounts/1001374444/identifications/1076320"
	}, {
		"rel": "followupQuestions",
		"href": "https://api.test.paysafe.com/identity/v1/accounts/1001374444/identifications/1076320/challengeQuestions/247"
	}],
	"id": "1076320",
	"status": "PASS",
	"followupQuestions": {
		"questionSetId": "247",
		"questionType": "CHALLENGE",
		"questions": {
			"1": {
				"question": "In which country have you lived?",
				"answers": {
					"A": "CANADA",
					"B": "NAMIBIA",
					"C": "HUNGARY",
					"D": "None of the above"
				},
				"2": {
					"question": "At which of the following address have you lived?",
					"answers": {
						"A": "3 CRESSING ST",
						"B": "113 BIRCH DR",
						"C": "510 ADAMS RD",
						"D": "None of the above"
					},
					"links": [{
						"rel": "self",
						"href": "https://api.test.paysafe.com/identity/v1/accounts/1001374444/identifications/1076320"
					}, {
						"rel": "followupQuestions",
						"href": "https://api.test.paysafe.com/identity/v1/accounts/1001374444/identifications/1076320/challengeQuestions/247"
					}]
				}
			}
		}
	}
}

In this example, the merchant identification request came back with the status = PASS. However, the merchant must answer additional Challenge questions to prove their identity.

  • 1001374444 is the account number used in the Challenge request, provided by Paysafe.
  • 1076320 is the response ID.
  • 247 is the question set to present to the merchant.
  • 1 and 2 are the Challenge questions for you to present to the merchant to answer.

Sending a Challenge Question Request

Once you receive the merchant's answers to the Challenge questions (see Successful Response Example with Challenge Questions above) you submit a PUT request containing those answers to the Identity Verification API.

There is a time limit of 4 minutes to send the Challenge Question request – containing the correct answers – once you have received the Challenge questions in the response from the Identity Verification API. If you take longer than 4 minutes, you will receive a time out error in the response and you will have to initiate the process again with a new Identity Verification request.

The URL for the PUT looks like this:

https://api.paysafe.com/identity/v1/accounts/account_id/identifications/response_id/challengeQuestions/question_set_id

Request Example
curl -X PUT https://api.test.paysafe.com/identity/v1/accounts/1001374444/identifications/1076320/challengeQuestions/247 \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
  -d ' {
    "1": "B",
    "2": "A"
}'

In this request:

  • 1001374444 is the account number used in the Challenge request, provided by Paysafe.
  • 1076320 is the response ID from the first Identification request.
  • 247 is the ID of the question set presented to the merchant.
  • B and A are the answers provided by the merchant for questions 1 and 2, respectively.

For Canadian merchants, see Identification Request Test Values for Canadian Merchants for more information on answers to use in the Test environment.

For US merchants, please contact our Integrations team for more information on answers to use in the Test environment.

Response Example
{
	"id": "1076320",
	"status": "PASS",
	"links": [{
		"rel": "self",
		"href": "https: //api.test.paysafe.com/identity/v1/accounts/1001374444/identifications/1076320"
	}]
}

In this example, the merchant identification request passed (status = PASS), and the response contains the id value of 1076320. Now that the business owner has successfully answered the Challenge questions, you can use this value as the identityId in the Identity Verification request in the Account Management API.

See Identity Verification API Errors for a list of errors you could encounter when sending requests to the Identity Verification API.

Did you find this page useful?