Skip to main content

KycSessionExtended

merchantRefNumMerchantReferenceNumber (string)required

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.

Possible values: <= 255 characters

Example: 4bc2deb3-9766-4598-a08e-a98b60615936
returnUrlurl

The return URL to which users must be redirected after competing the required activities in Paysafe hosted UI.

Example: https://some-process.paysafe.com/
languagestring

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

Example: en
idstring

Generated sessionId

Example: 2cb56b2749af52d6b257054ef3de03d8b1b07b6020e8e8c7c13139e70670d368
customerIdstring

Merchant's Paysafe wallet customer id

Possible values: <= 40 characters

Example: 1003900
externalIdExternalId (string)

Customer identifier used in Partner system.

Possible values: non-empty and <= 40 characters

Example: af5c8b52-0afd-4799-85ab-fe659a076932
creationTimedate-time

Session creation time
Represents RFC 3339, section 5.6 date-time.

expirationTimedate-time

Session expiration time
Represents RFC 3339, section 5.6 date-time.

statusKycSessionStatus (string)

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.

Possible values: [CREATED, INITIATED, CANCELLED, FAILED, ABANDONED, EXPIRED, COMPLETE]

Example: COMPLETE
redirectUrlurl

Redirect URL where the user should be redirected to in order to complete some action.

Example: https://some-process.paysafe.com/
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.

  • Array [
    • namestringrequired

    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.

    Possible values: [BIOMETRIC_CONSENT, PROVIDER_SESSION_INITIATED, PROVIDER_SESSION_END, SSN_ATTESTATION]

    kycProviderDetails object

    Details on the kyc provider

    kycProviderstring

    name of the provider

  • ]
    • verificationDocuments object[]

    All documents uploaded during current KYC Session

  • Array [
    • categoryVerificationDocumentCategory (string)required

    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: [ADDRESS, IDENTITY, ADDITIONAL_VERIFICATION]

    Example: IDENTITY
    typeVerificationDocumentType (string)required

    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: [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]

    subtypeVerificationDocumentSubtype (string)

    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: [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]

    statusVerificationDocumentStatus (string)required

    The status of the verification document.

    Possible values: [APPROVED, DECLINED, UPLOADED, IN_REVIEW, CLOSED]

    statusReasonStatusReason (string)

    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.

    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]

    Example: BLURRY
    attributes object

    Data extracted from the document via OCR.

    firstNamestring

    First name as it appears on the provided document.

    lastNamestring

    Last name as it appears on the provided document.

    dobstring

    Date of birth in the format YYYY-MM-DD as available on the provided document.

    addressLinestring

    Address line as it appears on the provided document.

    countrystring

    Country as it appears on the provided document. Should appear in ISO 3166-1 alpha-3 country code format.

    citystring

    City as it appears on the provided document.

    postalCodestring

    Postal code as it appears on the provided document.

    issuingCountrystring

    Country as it appears on the provided document. Should appear in ISO 3166-1 alpha-3 country code format.

    issueDatestring

    Issue date in the format YYYY-MM-DD as available on the provided document.

    documentExpirystring

    Expiry date in the format YYYY-MM-DD as available on the provided document.

    subdivisionstring

    Subdivision as it appears on the provided document. (Region, State, Province, Emirate, Department, …)

    faceMatchboolean

    Indicated whether the customer has a face verification matching the document picture.

    kycProviderDetails object

    Details on the kyc provider

    kycProviderstring

    name of the provider

  • ]
    • electronicVerifications object[]

    All results from electronic verifications during currnet session

  • Array [
    • kycProviderDetails object

    Details on the kyc provider

    kycProviderstring

    name of the provider

    results object[]

    A list of all electronic verifications for the customer.

  • Array [
    • namestring

    Possible values: [ID_MATCH, ADDRESS_MATCH]

    valuestring

    Possible values: [VALID, INVALID]

  • ]
  • ]
    • KycSessionExtended
    {
      "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-07-29T15:51:28.071Z",
      "expirationTime": "2024-07-29T15:51:28.071Z",
      "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"
            }
          ]
        }
      ]
    }