Start Instrument Verification Session
POST/profile/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.
Тhe status of the session can be tracked using Get Instrument Verification API.
Request
Header Parameters
Default value: application/json
application/json
- application/json
Body
Possible values: [SEPA_BANK_ACCOUNT
, UK_BANK_ACCOUNT
, US_BANK_ACCOUNT
, CCI_BANK_ACCOUNT
, CARD
]
Instrument type.
| 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 |
It is URL to which users must be redirected after competing the required activities in Paysafe hosted UI.
Responses
- 200
- 400
- 500
The instrument verification session object, that contains a redirect URL where the User should be redirected to, to complete the payment instrument verification process.
- application/json
- Schema
- Example (from schema)
- ADD_US_BANK_ACCOUNT_RESPONSE
Schema
- ACTIVE - is 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 eitherUNVERIFIED
or inREJECTED
status. - 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.
Possible values: [SEPA_BANK_ACCOUNT
, UK_BANK_ACCOUNT
, US_BANK_ACCOUNT
, CCI_BANK_ACCOUNT
, CARD
]
Instrument type.
| 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 |
It is URL to which users must be redirected after competing the required activities in Paysafe hosted UI.
Instrument verification session Id
Redirect URL where the User should be redirected to to complete some action.
Represents RFC 3339, section 5.6 date-time.
Represents RFC 3339, section 5.6 date-time.
instrument
object
Represents a reference to Payment Instrument, used for Deposit or Withdrawal.
Instrument identifier.
Possible values: [SEPA_BANK_ACCOUNT
, UK_BANK_ACCOUNT
, US_BANK_ACCOUNT
, CCI_BANK_ACCOUNT
, CARD
]
Instrument type.
| 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 |
Possible values: [ACTIVE
, ONGOING_VERIFICATION
, AWAITING_USER_INPUT
, COMPLETED
, FAILED
]
Instrument verification session status reflects the current status of the session.
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 customer verification session failure reason. It helps determine the next course of action.
{
"instrumentType": "CARD",
"returnUrl": "https://some-process.paysafe.com/",
"id": "2cb56b2749af52d6b257054ef3de0",
"redirectUrl": "https://some-process.paysafe.com/",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T17:54:12Z",
"instrument": {
"id": "1001",
"instrumentType": "CARD"
},
"sessionStatus": "ACTIVE",
"statusReason": "UNSUPPORTED_BANK"
}
{
"instrumentType": "US_BANK_ACCOUNT",
"id": "2cb56b2749af52d6b257054ef",
"redirectUrl": "https://pi-verify.eu-mprod.sandbox.dw-cloud.net/instruments/verifications/fa2830cb8ea46b43577a7b8ded0ed9b945e648a42ebdf82c3c8e05ff30f293a3/initiate",
"creationTime": "2021-07-15T17:54:12Z",
"expirationTime": "2021-07-15T20:54:12Z",
"sessionStatus": "ACTIVE",
"returnUrl": "https://merchantsite.com/paymentinstruments"
}
Validation failed.
- application/json
- Schema
- Example (from schema)
- Instrument type validation
- Bank account limit validation
Schema
Array [
]
error
object
Additional details about an error
The error code.
A description of the error.
Details of any parameter value errors.
fieldErrors
object[]
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "DW-INVALID-INSTRUMENT-TYPE-FOR-VERIFICATION",
"message": "The provided instrument type is not supported for instrument verification.",
"details": [
"The provided instrument type is not supported for instrument verification."
]
}
}
{
"error": {
"code": "DW-BANK-ACCOUNT-LIMIT-EXCEEDED",
"message": "Customer has reached the limit number of verified bank accounts and open payment instrument verification sessions.",
"details": [
"Customer has reached the limit number of verified bank accounts and open payment instrument verification sessions."
]
}
}
Internal Server Error
- application/json
- Schema
- Example (from schema)
- Example 1
Schema
Array [
]
error
object
Additional details about an error
The error code.
A description of the error.
Details of any parameter value errors.
fieldErrors
object[]
Identifies the JSON request field.
The problem associated with the field.
{
"error": {
"code": "string",
"message": "string",
"details": [
"string"
],
"fieldErrors": [
{
"field": "string",
"error": "string"
}
]
}
}
{
"error": {
"code": "1000",
"message": "Internal Error",
"details": [
"An internal error occurred."
]
}
}