Skip to main content

Start Instrument Verification Session

POST 
/v2/customers/:customerId/instrument-verifications

Creates new instrument verification session. The result of successful verification is a VERIFIED instrument, that can be used for withdrawal or deposit operations.

Required Parameters:

  • instrumentType - Currently US_BANK_ACCOUNT is supported.
  • returnUrl - should contain the location to where the customer must be redirected after completing the required actions in Paysafe hosted UI.

The response contains:

  • id - the session identifier
  • redirectUrl - unique instrument verification redirect url associated with this session. The url contains Paysafe hosted UI, that carries the user through the account selection and verification process.
  • secureCode - unique secure code, that provides authentication for the session. This must be passed as query parameter attached to the redirect link.

Тhe status of the session can be tracked using Get Instrument Verification API.

Request​

Path Parameters

    customerId stringrequired

    The wallet customer id

Body

    instrumentType InstrumentType (string)required

    Possible values: [SEPA_BANK_ACCOUNT, UK_BANK_ACCOUNT, US_BANK_ACCOUNT, CCI_BANK_ACCOUNT, CARD]

    Represents the type of the instrument.

    | Value | Description| |---|---| | SEPA_BANK_ACCOUNT| SEPA Bank account | | UK_BANK_ACCOUNT | UK Bank account | | US_BANK_ACCOUNT | US Bank account | | CCI_BANK_ACCOUNT | CCI Bank account | | CARD | Card |

    returnUrl urlrequired

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

Responses​

The instrument verification session object, that contains a redirect URL where the User should be redirected to, to complete the payment instrument verification process.

Schema

    instrumentType InstrumentType (string)required

    Possible values: [SEPA_BANK_ACCOUNT, UK_BANK_ACCOUNT, US_BANK_ACCOUNT, CCI_BANK_ACCOUNT, CARD]

    Represents the type of the instrument.

    | Value | Description| |---|---| | SEPA_BANK_ACCOUNT| SEPA Bank account | | UK_BANK_ACCOUNT | UK Bank account | | US_BANK_ACCOUNT | US Bank account | | CCI_BANK_ACCOUNT | CCI Bank account | | CARD | Card |

    returnUrl urlrequired

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

    id stringrequired

    Instrument verification session ID

    redirectUrl urlrequired

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

    creationTime date-timerequired

    Represents RFC 3339, section 5.6 date-time.

    expirationTime date-timerequired

    Represents RFC 3339, section 5.6 date-time.

    instrument

    object

    Represents a reference to a Payment Instrument, used for Deposit or Withdrawal.

    id stringrequired

    Instrument identifier.

    instrumentType InstrumentType (string)required

    Possible values: [SEPA_BANK_ACCOUNT, UK_BANK_ACCOUNT, US_BANK_ACCOUNT, CCI_BANK_ACCOUNT, CARD]

    Represents the type of the instrument.

    | Value | Description| |---|---| | SEPA_BANK_ACCOUNT| SEPA Bank account | | UK_BANK_ACCOUNT | UK Bank account | | US_BANK_ACCOUNT | US Bank account | | CCI_BANK_ACCOUNT | CCI Bank account | | CARD | Card |

    sessionStatus Instrument Verification Status (string)required

    Possible values: [ACTIVE, ONGOING_VERIFICATION, AWAITING_USER_INPUT, COMPLETED, FAILED]

    Instrument verification session status reflects the current status of the session.

    • ACTIVE - The initial session status when it gets created
    • AWAITING_USER_INPUT - Awaiting user input in order to continue the verification process.
    • ONGOING_VERIFICATION - Payment instrument is obtained and is being verified against customer details in Paysafe.
    • COMPLETED - Verification process is completed, the instrument should be in VERIFIED status.
    • FAILED - Instrument verification failed. Check statusReason for details. If instrument is present in the session, it could be in either UNVERIFIED or in REJECTED status.
    statusReason Instrument Verification Failed Status Reason (string)

    Possible values: [UNSUPPORTED_BANK, NAME_MISMATCH, INSTRUMENT_NOT_UNIQUE, MISSING_DETAILS, INTERNAL_ERROR, SESSION_EXPIRED, USER_ABANDONED_PROCESS, USER_INTERACTION_ERROR, OTHER]

    Holds information about the customer verification session failure reason. It helps determine the next course of action.

    • UNSUPPORTED_BANK - The verification process does not support the Bank.
    • NAME_MISMATCH - The bank account information does not match the customer information in Embedded Wallet. Account can be verified by manual submission of bank statement to Paysafe support.
    • INSTRUMENT_NOT_UNIQUE - Another customer is using the same instrument. Usually this happens when using shared bank account. Contact Paysafe support to resolve the issue.
    • INTERNAL_ERROR - Technical error in Paysafe system. Try adding instrument through new verification session.
    • SESSION_EXPIRED - Verification session expired. Start new verification session.
    • MISSING_DETAILS - Sufficient information could not be obtained by the bank to prove ownerhip.
    • USER_ABANDONED_PROCESS - The user has abondened the instrument verification process without providing enough details about their bank account.
    • USER_INTERACTION_ERROR - An error occurred when user was trying to select their bank account.
    • OTHER - Unexpected error, unable to classify. Contact Paysafe support to resolve the issue.
    secureCode string

    Base64 encoded string containing the secure code for authentication.

    secureCodeMethod string

    Default value: sha512

    The secure code hashing algorithm.

Loading...