Create a KYC session
POST/kyc/customers/:customerId/sessions
Merchant creates a KYC session for their customer
Request
Path Parameters
Merchant's Paysafe wallet customer id
- application/json
Body
required
Possible values: <= 255 characters
This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request and allows cross referencing objects from merchant system to embedded wallet objects.
The return URL to which users must be redirected after competing the required activities in Paysafe hosted UI.
Renders content for the merchant customer in the specified language. If not provided, the application will default to 'en'. Supported values are:
en
en-GB
cs-CZ
de-DE
el-GR
en-US
es-ES
es-US
fr-FR
it-IT
ko-KR
pl-PL
pt-BR
pt-PT
ru-RU
tr-TR
zh-CN
Responses
- 201
- 400
- 404
- 500
Created
- application/json
- Schema
- Example (from schema)
- Example 1
Schema
Array [
]
Array [
]
Array [
Array [
]
]
Possible values: <= 255 characters
This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request and allows cross referencing objects from merchant system to embedded wallet objects.
The return URL to which users must be redirected after competing the required activities in Paysafe hosted UI.
Renders content for the merchant customer in the specified language. If not provided, the application will default to 'en'. Supported values are:
en
en-GB
cs-CZ
de-DE
el-GR
en-US
es-ES
es-US
fr-FR
it-IT
ko-KR
pl-PL
pt-BR
pt-PT
ru-RU
tr-TR
zh-CN
Generated sessionId
Possible values: <= 40 characters
Merchant's Paysafe wallet customer id
Possible values: non-empty
and <= 40 characters
Customer identifier used in Partner system.
Session creation time
Represents RFC 3339, section 5.6 date-time.
Session expiration time
Represents RFC 3339, section 5.6 date-time.
Possible values: [CREATED
, INITIATED
, CANCELLED
, FAILED
, ABANDONED
, EXPIRED
, COMPLETE
]
CREATED
: Initial status given upon session creation.
INITIATED
: Once the end customer exchanges their code and enters the KYC flow
COMPLETE
: Customer successfully completes their session.
CANCELLED
: Customer has decided not to complete their session.
ABANDONED
: Customer has not started the KYC flow after session creation.
EXPIRED
: Customer did not complete their verification in time and their session has expired.
Redirect URL where the user should be redirected to in order to complete some action.
sessionEvents
object[]
Significant events that have occured during the KYC session. These will reflect when a customer starts a session with a provider or provides consent in a scenario where one is needed. Main purpose of this is so the merchant can have traceability over the customer journey.
Possible values: [BIOMETRIC_CONSENT
, PROVIDER_SESSION_INITIATED
, PROVIDER_SESSION_END
, SSN_ATTESTATION
]
Name of the session event.BIOMETRIC_CONSENT
- Customer has given consent to use biometric data for verification.
PROVIDER_SESSION_INITIATED
- Customer has started the verification process with a provider.
PROVIDER_SESSION_END
- Customer has completed the verification process with a provider.
SSN_ATTESTATION
- The attestation is collected during the verification process and customer has certified that all the information they have entered, including, without limitation, their social security number, is current, accurate, and complete, and it may be relied upon.
kycProviderDetails
object
Details on the kyc provider
name of the provider
verificationDocuments
object[]
All documents uploaded during current KYC Session
Possible values: [ADDRESS
, IDENTITY
, ADDITIONAL_VERIFICATION
]
This will represent what is the category of the document. Identity documents are typically passports, Id cards or driver's lincences. Address documents may be bank statments, utility bills and more...
Possible values: [ID_CARD
, PASSPORT
, DRIVING_LICENSE
, VISA
, CC
, BS
, IC
, UB
, CAAP
, CRC
, CCS
, LAG
, LOAP
, MOAP
, TR
, VT
, VC
, STUC
, HCC
, CB
, SENC
, MEDC
, BC
, WWCC
, SS
, TAC
, SEL
, PB
, SSC
, CUSTOM
, CUS_HI
, CUS_LTC
, CUS_CD
, CUS_PD
, CUS_ADDR
, OTHER
]
Type of the document. ID Document types are
ID_CARD - ID Card
PASSPORT - Passport
DRIVING_LICENSE - Driving License
VISA - Visa
Address Document Types are
CC - Credit Card
CC - Credit card, front and back side
BS - Bank statement, front side
IC - Insurance card, front side
UB - Utility bill, front side
CAAP - Cash advance application, front and back side
CRC - Corporate resolution certificate, front and back side
CCS - Credit card statement, front and back side
LAG - Lease agreement, front and back side
LOAP - Loan application, front and back side
MOAP - Mortgage application, front and back side
TR - Tax return, front and back side
VT - Vehicle title, front side
VC - Voided check, front side
STUC - Student card, front side
HCC - Health care card, front side
CB - Council bill, front side
SENC - Seniors card, front side
MEDC - Medicare card, front side
BC - Birth certificate, front side
WWCC - Working with children check, front side
SS - Superannuation statement, front side
TAC - Trade association card, front side
SEL - School enrolment letter, front side
PB - Phone bill, front side
SSC - Social security card, front side
CUSTOM - Custom document.
CUS_HI - Custom Holding ID
CUS_LTC - Custom lease tenant agreement
CUS_CD - Court Document
CUS_PD - Custom pendion document
CUS_ADDR - Custom Address document
OTHER - Uncategorised document
Possible values: [VISA
, TAX_ID
, STUDENT_ID
, SOCIAL_SECURITY_ID
, SERVICES_ID
, RESIDENT_PERMIT_ID
, REGULAR_DRIVING_LICENSE
, PUBLIC_SAFETY_ID
, PROFESSIONAL_ID
, PASSPORT_CARD_ID
, OTHER_ID
, NATIONAL_ID
, MULTI_PURPOSE_ID
, MILITARY_ID
, LEARNING_DRIVING_LICENSE
, HEALTH_ID
, E_PASSPORT
, ELECTORAL_ID
, CUS_PD
, CUS_LTC
, CUS_HI
, CUS_CD
, CUS_ADDR
, CONSULAR_ID
, CITIZENSHIP_ID
]
Some documents may have a subtype of the document. Most often those will be under type ID_CARD.
VISA - Visa
TAX_ID - Tax ID
STUDENT_ID - Student ID
SOCIAL_SECURITY_ID - Social Security ID
SERVICES_ID - Services ID
RESIDENT_PERMIT_ID - Resident Permit ID
REGULAR_DRIVING_LICENSE - Regular Driving License
PUBLIC_SAFETY_ID - Public Safety ID
PROFESSIONAL_ID - Professional ID
PASSPORT_CARD_ID - Passport Card ID
OTHER_ID - Other, not categorized ID
NATIONAL_ID - National ID
MULTI_PURPOSE_ID - Multi Purpose ID
MILITARY_ID - Military ID
LEARNING_DRIVING_LICENSE - Learning Driving License
HEALTH_ID - Health ID
E_PASSPORT - E-Passport
ELECTORAL_ID - Electoral ID
CUS_PD - Custom pendion document, subtype to the CUSTOM ID type
CUS_LTC - Custom lease tenant agreement, subtype to the CUSTOM ID type
CUS_HI - Custom Holding ID, subtype to the CUSTOM ID type
CUS_CD - Court Document, subtype to the CUSTOM ID type
CUS_ADDR - Custom Address document, subtype to the CUSTOM ID type
CONSULAR_ID - Consular ID
CITIZENSHIP_ID - Citizenship ID
Possible values: [APPROVED
, DECLINED
, UPLOADED
, IN_REVIEW
, CLOSED
]
The status of the verification document.
Possible values: [BLURRY
, NAME_MISMATCH
, DOB_MISMATCH
, FACE_MISMATCH
, MISSING_SIDE
, BLOCKED_INFO
, EXPIRED
, CROPPED
, HIGH_CONTRAST
, INVALID_TYPE
, DOCUMENT_NOT_PROVIDED
, NO_DOB_ON_DOC
, UNDERAGE
, FULL_CC
, COUNTRY_MISMATCH
, SELFIE_NOT_PROVIDED
, 90_DAY_OLD
, ALTERED
, ENVELOPE
, MOBILE_BILL
, ENTITY_MISMATCH
, DIFFERENT_OR_NO_NAME
, ADDRES_MISMATCH
, NO_ADDRESS
, THIRD_PARTY_WARNING
]
Reason for the status of a verification document.
BLURRY - The document is blurry and not readable.
NAME_MISMATCH - The name on the document does not match the name of the customer.
DOB_MISMATCH - The date of birth on the document does not match the date of birth of the customer.
FACE_MISMATCH - The face on the document does not match the face of the customer.
MISSING_SIDE - The document is missing a side.
BLOCKED_INFO - The document has blocked information.
EXPIRED - The document is expired.
CROPPED - The document is cropped.
HIGH_CONTRAST - The document has high contrast.
INVALID_TYPE - The document is of invalid type.
DOCUMENT_NOT_PROVIDED - The document was not provided.
NO_DOB_ON_DOC - The document does not have date of birth.
UNDERAGE - The customer is underage.
FULL_CC - Customer has provided a credit card statement containing the full credit card number and cannot be properly stored.
COUNTRY_MISMATCH - The country on the document does not match the country of the customer.
SELFIE_NOT_PROVIDED - The selfie was not provided.
90_DAY_OLD - The document is older than 90 days.
ALTERED - The document has been altered.
ENVELOPE - The document is in an envelope.
MOBILE_BILL - The document is a mobile bill and unusable for vification purposes.
ENTITY_MISMATCH - Country of document ineligible for customer verification.
DIFFERENT_OR_NO_NAME - The name on the document does not match the name of the customer.
ADDRES_MISMATCH - The address on the document does not match the address of the customer.
NO_ADDRESS - The document does not have an address.
THIRD_PARTY_WARNING - The document is a third party warning.
attributes
object
Data extracted from the document via OCR.
First name as it appears on the provided document.
Last name as it appears on the provided document.
Date of birth in the format YYYY-MM-DD as available on the provided document.
Address line as it appears on the provided document.
Country as it appears on the provided document. Should appear in ISO 3166-1 alpha-3 country code format.
City as it appears on the provided document.
Postal code as it appears on the provided document.
Country as it appears on the provided document. Should appear in ISO 3166-1 alpha-3 country code format.
Issue date in the format YYYY-MM-DD as available on the provided document.
Expiry date in the format YYYY-MM-DD as available on the provided document.
Subdivision as it appears on the provided document. (Region, State, Province, Emirate, Department, …)
Indicated whether the customer has a face verification matching the document picture.
kycProviderDetails
object
Details on the kyc provider
name of the provider
electronicVerifications
object[]
All results from electronic verifications during currnet session
kycProviderDetails
object
Details on the kyc provider
name of the provider
results
object[]
A list of all electronic verifications for the customer.
Possible values: [ID_MATCH
, ADDRESS_MATCH
]
Possible values: [VALID
, INVALID
]
{
"merchantRefNum": "4bc2deb3-9766-4598-a08e-a98b60615936",
"returnUrl": "https://some-process.paysafe.com/",
"language": "en",
"id": "2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368",
"customerId": "1003900",
"externalId": "af5c8b52-0afd-4799-85ab-fe659a076932",
"creationTime": "2024-11-12T16:34:38.755Z",
"expirationTime": "2024-11-12T16:34:38.755Z",
"status": "COMPLETE",
"redirectUrl": "https://some-process.paysafe.com/",
"sessionEvents": [
{
"name": "BIOMETRIC_CONSENT",
"kycProviderDetails": {
"kycProvider": "string"
}
}
],
"verificationDocuments": [
{
"category": "IDENTITY",
"type": "ID_CARD",
"subtype": "VISA",
"status": "APPROVED",
"statusReason": "BLURRY",
"attributes": {
"firstName": "string",
"lastName": "string",
"dob": "string",
"addressLine": "string",
"country": "string",
"city": "string",
"postalCode": "string",
"issuingCountry": "string",
"issueDate": "string",
"documentExpiry": "string",
"subdivision": "string",
"faceMatch": true
},
"kycProviderDetails": {
"kycProvider": "string"
}
}
],
"electronicVerifications": [
{
"kycProviderDetails": {
"kycProvider": "string"
},
"results": [
{
"name": "ID_MATCH",
"value": "VALID"
}
]
}
]
}
{
"merchantRefNum": "ewre3424erfsfds3242",
"returnUrl": "https://some-process.paysafe.com/",
"language": "en-GB",
"id": "2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368",
"customerId": "1003900",
"externalId": "af5c8b52-0afd-4799-85ab-fe659a076932",
"creationTime": "2019-08-24T14:15:22Z",
"expirationTime": "2019-08-24T14:15:22Z",
"status": "COMPLETE"
}
Bad Request. Provided data is invalid.
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
error
object
Represents details of an error.
The error code.
The description of the error.
Details for the errors of any parameter value.
fieldErrors
object[]
List of field errors associated with the main error.
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
Not Found
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
error
object
Represents details of an error.
The error code.
The description of the error.
Details for the errors of any parameter value.
fieldErrors
object[]
List of field errors associated with the main error.
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
Internal Server Error
- application/json
- Schema
- Example (from schema)
Schema
Array [
]
error
object
Represents details of an error.
The error code.
The description of the error.
Details for the errors of any parameter value.
fieldErrors
object[]
List of field errors associated with the main error.
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}