API Reference

FAQ

1. How to get started with the documentation?

Answer: If you're unsure where to begin with the documentation, we recommend familiarizing yourself with this document: https://api.vault.ist/docs/getting-started

2. How to retrieve your x-request-id?

Answer: After executing the request, you need to click the Headers button in the response body. This will display all information about the request, including the x-request-id.

Example

After the request is executed, the user receives a response. The response status code indicates that the request was successfully processed.


{
  "result": "ok"
}

To obtain additional information about the RESPONSE, you need to click on the Headers button.

3. How to properly compose a support request?

Answer: In your Slack chat, you should compose the request in the following format:

Issue with executing endpoint POST /v2/mobile/phone/confirm

**Request Details:**
- x-request-id: 097d32224c768658ce90860ab082735d
- Date: Mon, 15 Apr 2024 10:54:05 GMT

**Request Body:**
```cURL
curl --request POST \
     --url https://api.vault.sandbox.testessential.net/v2/mobile/phone/confirm \
     --header 'X-Merchant-ID: bece038f-2e46-49f4-b25e-89cd38d6dc16' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "phone": "+447871234567",
  "smsCode": "1234",
  "fingerprint": "12344444"
}
' 

**Error Response Body**:
{  
  "message": "Sorry for inconvenience. We're fixing the issue. If you have urgent questions, contact support",  
  "errorId": 0,  
  "systemId": "core",  
  "error": "COMMON"  
}
4. What to do if KYC verification is rejected?

Answer: If your KYC verification attempt is rejected, follow these steps:

  1. Check Documentation: Ensure that all provided documentation meets the specified requirements outlined in the KYC process.
  2. Review Information: Double-check the accuracy of all submitted information, including personal details and uploaded documents.
  3. Additional Information: Additional details regarding the reasons for verification rejection can be obtained using the endpoint GET /v2/customer/kyc/data with the parameters "reason" and "rejectFormattedMessage".

Common Reasons for KYC Rejection

Here are some common reasons for KYC rejection, depending on the level you are attempting to pass:

CodeMessageKYC
DOCUMENT_UNSUPPORTED_TYPE"We regret to inform you that your recent attempt to complete the verification process has been declined because the submitted document can not be accepted as a valid proof of residence according to our internal rules. To ensure the completion of your account verification, we kindly request you to re-submit a valid document.

Here are the specific requirements for an acceptable proof of residence:

1. The document must be issued in Latin characters or include a translation into English.
2. It should be issued within the last 3 months.
3. Clearly display your name, postal address, and date of issue.
4. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
5. Any online copy must be verified (stamped) by the issuing institution.
6. PO box addresses cannot be accepted as proof of residence. If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
DOCUMENT_CROPPEDWe regret to inform you that your recent attempt to complete the verification process has been declined because the document you submitted is severely cropped and does not meet our requirements.

To ensure a successful verification, we kindly request that you re-submit a document adhering to the following guidelines:
1.The document must fit into the provided photo frame, ensuring all four corners are visible;
2. The document must be issued in Latin characters or include a translation into English.
3. It should be issued within the last 3 months.
4. Clearly display your name, postal address, and date of issue.
5. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
6. Any online copy must be verified (stamped) by the issuing institution.
7. PO box addresses cannot be accepted as proof of residence.

If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
DOCUMENT_NOT_IN_ENGLISHWe regret to inform you that your recent attempt to complete the verification process has been declined because the document you submitted is not in Latin characters, and as per our guidelines, it can not be accepted.

To ensure a successful verification, we kindly request that you re-submit a document adhering to the following guidelines:

1. The document must be issued in Latin characters or include a translation into English.
2. It should be issued within the last 3 months.
3. Clearly display your name, postal address, and date of issue.
4. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
5. Any online copy must be verified (stamped) by the issuing institution.
6. PO box addresses cannot be accepted as proof of residence. If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
NAME_MISMATCHWe regret to inform you that your recent attempt to complete the verification process has been declined due to a name mismatch with the details on your account.

To proceed with residence verification, we kindly request you to re-submit a document that meets the following criteria:

1. The document must be issued in Latin characters or include a translation into English.
2. It should be issued within the last 3 months.
3. Clearly display your name, postal address, and date of issue.
4. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
5. Any online copy must be verified (stamped) by the issuing institution.
6. PO box addresses cannot be accepted as proof of residence. If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
DOCUMENT_BAD_QUALITYWe regret to inform you that your recent attempt to complete the verification process has been declined due to unclear visibility. To proceed with residence verification, we kindly request you to re-submit a new, high-quality photo of your document.
Here are some guidelines to ensure a successful submission:- Capture the photo in proper lighting for better visibility.- Ensure the image is clear and all details are visible.
If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
DOCUMENT_EXPIREDWe regret to inform you that the document you previously submitted for proof of residence has been deemed outdated.

To ensure the successful completion of your account verification, we kindly request that you submit a new document meeting the following criteria:

1. The document must be issued in Latin characters or include a translation into English.
2. It should be issued within the last 3 months.
3. Clearly display your name, postal address, and date of issue.
4. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
5. Any online copy must be verified (stamped) by the issuing institution.
6. PO box addresses cannot be accepted as proof of residence. If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
DOCUMENT_WITHOUT_DATEWe regret to inform you that the document you previously submitted as proof of residence lacks a visible date.

To complete the account verification process, we kindly request you to submit a new document adhering to the following criteria:

1. The document must be issued in Latin characters or include a translation into English.
2. It should be issued within the last 3 months.
3. Clearly display your name, postal address, and date of issue.
4. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
5. Any online copy must be verified (stamped) by the issuing institution.
6. PO box addresses cannot be accepted as proof of residence. If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
DOCUMENT_WITHOUT_ADDRESSWe regret to inform you that the document you previously submitted as proof of residence does not contain your postal address.

To proceed with the account verification process, we kindly ask you to submit a new document adhering to the following criteria:

1. The document must be issued in Latin characters or include a translation into English.
2. It should be issued within the last 3 months.
3. Clearly display your name, postal address, and date of issue.
4. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
5. Any online copy must be verified (stamped) by the issuing institution.
6. PO box addresses cannot be accepted as proof of residence. If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!"		KYC_2
NO_DOCUMENTWe regret to inform you that your recent attempt to complete the verification process has been declined because the submitted photo does not contain a valid document for proof of residence.

To ensure a successful completion of residence verification, we kindly ask you to re-submit a document that meets the following criteria:

1. The document must be issued in Latin characters or include a translation into English.
2. It should be issued within the last 3 months.
3. Clearly display your name, postal address, and date of issue.
4. Acceptable issuers are government authorities, financial institutions, or utility companies (mobile operator invoices can not be accepted).
5. Any online copy must be verified (stamped) by the issuing institution.
6. PO box addresses cannot be accepted as proof of residence. If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_2
PartOfDocumentIsCoveredWe regret to inform you that your recent attempt to complete the verification process has been declined because a part of the document you provided is not visible.
To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. Please ensure that your document is fully visible, undamaged, and that the image is of good quality. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.

If you have any questions or encounter difficulties during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
PoorPhotoQualityWe regret to inform you that your recent attempt to complete the verification process has been declined due to poor photo quality.

To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. Please ensure that your document is fully visible, undamaged, and that the image is of good quality. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.

If you have any questions or encounter difficulties during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
PossibleFraudAttemptUnfortunately, we must inform you that your recent attempt to complete the verification process has been declined. After careful review, our Compliance team has identified serious inconsistencies in the submitted data.
Regrettably, this means we must proceed with the closure of your account. We understand the significance of this decision and apologize for any inconvenience it may cause.

If you have any questions or need further clarification, please don`t hesitate to reach out to our support team. We appreciate your understanding.		KYC_1
ProhibitedCountryOrStateUnfortunately, we regret to inform you that your verification request has been declined. According to our internal rules, your account will be closed. We understand the significance of this decision and apologize for any inconvenience it may cause.
If you have any questions or need further clarification, please don`t hesitate to reach out to our support team. We appreciate your understanding.		KYC_1
UnrelatedPhotoSubmitWe regret to inform you that your recent attempt to complete the verification process has been declined. The image of your document has not been uploaded successfully.

To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. Please ensure that your document is fully visible, undamaged, and that the image is of good quality. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you have any questions or encounter difficulties during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
FacePhotoUploadFormatWe regret to inform you that your recent attempt to complete the verification process has been declined. After careful review, we found that the provided photos do not meet the necessary criteria outlined in our internal rules.
To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Photos of screens cannot be accepted.
If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
DuplicatedInfoWe regret to inform you that your recent attempt to complete the verification process has been declined due to a technical issue. We kindly ask you to retry the process and apologize for the inconvenience.
To proceed with identity verification, kindly reupload a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
Should you have any questions or need assistance during this process, please feel free to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
DocumentFromScreenWe regret to inform you that your recent attempt to complete the verification process has been declined. After careful review, we found that the provided photos do not meet the necessary criteria outlined in our internal rules.
To proceed with identity verification, kindly reupload a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Photos of screens cannot be accepted.
If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
SelfieHasNoFaceWe regret to inform you that your recent attempt to complete the verification process has been declined because your selfie is not clearly visible.
To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. Please ensure that your document is fully visible, undamaged, and that the image is of good quality. The document must be issued in Latin characters with a validity period of at least 3 months.
Please note that photos of screens cannot be accepted.
If you have any questions or encounter difficulties during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
MoreThanOnePersonWe regret to inform you that your recent attempt to complete the verification process has been declined. The identification procedure must be performed without other people participating in the process.
To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
Should you have any questions or need assistance during this process, please feel free to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
DocumentNotAcceptedWe regret to inform you that your recent attempt to complete the verification process has been declined because the submitted document can not be accepted as a valid proof of identity according to our internal rules.
To proceed with identity verification, kindly reupload a clear image of the passport without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you have any questions or encounter difficulties during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
DataNotMatchWe regret to inform you that your verification attempt has been declined. Our system has detected a mismatch between your personal data and the submitted document. Please ensure that your name and surname in your profile are correct and written in Latin characters.
To proceed with identity verification, kindly reupload a clear image of the actual document issued in Latin characters, with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you encounter any challenges or have questions, please feel free to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
DocumentIsExpiredWe regret to inform you that your recent attempt to complete the verification process has been declined because the document you provided has expired.
To proceed with identity verification, kindly reupload an image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you have any questions or require assistance during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
DocumentWithNonLatinCharactersWe regret to inform you that your recent attempt to complete the verification process has been declined because the submitted document can not be accepted as a valid proof of identity. We can only accept documents issued in Latin characters.
To proceed with identity verification, kindly reupload a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
MiscellaneousWe regret to inform you that your recent attempt to complete the verification process has been declined. After careful review, we found that the provided photos do not meet the necessary criteria outlined in our internal rules.
To proceed with identity verification, kindly reupload a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
Should you have any questions or need assistance during this process, please feel free to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
FacesNotMatchWe regret to inform you that your recent attempt to complete the verification process has been declined due to a mismatch between your selfie and the document picture. We kindly ask you to repeat the identification process.
To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
MissingPersonPhotoWe regret to inform you that your recent attempt to complete the verification process has been declined. Unfortunately, your selfie has not been uploaded.
To proceed with identity verification, kindly reupload your selfie and a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
MissingDocumentPhotoWe regret to inform you that your recent attempt to complete the verification process has been declined. Unfortunately, the image of your document has not been uploaded.To proceed with identity verification, kindly reupload a clear image of the actual identification document without a cover. The document must be issued in Latin characters with a validity period of at least 3 months. Please note that photos of screens cannot be accepted.
If you encounter any difficulties or have questions during this process, please do not hesitate to reach out to our support team. Your prompt attention to this matter is appreciated.
Thank you for your cooperation!		KYC_1
5. Why can't I confirm my email?

Answer: The email confirmation feature is currently not operational. This is due to the lack of implementation of the mail service function in the sandbox environment. However, everything functions as expected in the production environment.

6. What should I do if I don't know which data to enter when submitting a request?

Answer: To do this, follow these steps:

  1. On the right side of the screen, find the dropdown menu labeled Examples.

  1. Open the Example menu and select Request Example. This will display a sample request.

  2. In the Body field, enter your data following the structure and format of the example. Replace the example values with your actual data. Make sure all required fields are filled in correctly.


7. What should I do if the Guides don't contain the necessary information?

Answer: If the Guides don't contain the necessary information, follow these steps:

  1. Select the relevant article:

    • Navigate to the article in the Guides that is closest to your query or the topic you need information on.

  2. Click the Suggest Edits button:

    • Find the Suggest Edits button on the article page and click it. This will allow you to propose changes or add information.

  3. Enter the necessary information:

    • In the window that opens, enter the information you believe is useful and necessary to add to the article. Be as precise and specific as possible.

  4. Click the Suggest button:

    • Once you have entered all the necessary information, click the Suggest button to submit your proposal for review.

  5. Wait for a response:

    • Your edit request will be sent to the technical writer. Wait for a response — the technical writer will review your proposal and incorporate the changes if they are approved.

By following these steps, you can help improve the Guides and make them more informative for all users.

8. How to top up my wallet?

Answer:

If you need to top up your cryptocurrency wallet, please contact our technical team providing the following information:

  1. Phone number: Provide your contact phone number for communication purposes.

  2. Currency: Specify the cryptocurrency you want to top up on your wallet.

  3. Required amount: Indicate the amount you wish to be credited to your wallet.

❗️

Before topping up, you need to create a wallet with the required currency using the endpoint POST /v2/wallets

Our technical support team will process your request and credit the required amount to your wallet in the specified cryptocurrency.

Additionally, you can top up your wallet from the testnet blockchains.

Our current testnets are:

  • Bitcoin: testnet3
  • Ethereum: holesky
9. What statuses are for requests and cards?

Answer:

Request Statuses:

  • IN_PROGRESS: The request is currently being processed.
  • SUPPORT: The request requires intervention from the support team.
  • ACTIVATION: The request is for card activation.
  • COLLECTION: The request is for collecting necessary data or documents.
  • NEW: A new request that has not yet been processed.
  • ACTION_NEEDED: Action is needed from the user or operator.

Card Statuses:

  • HARD_BLOCKED: The card is blocked for serious reasons (e.g., fraud).
  • BLOCKED: The card is blocked but can be unblocked.
  • ACTIVE: The card is active and ready for use.

Additional Request Statuses for VISA Card Program:

  • CANCELED: The request was canceled by the user or system.
  • SUPPORT: The request requires intervention from the support team (same as the wallet status).
  • ACTIVE: The request is active and being processed.
  • PAYMENT_CANCELED: The payment associated with the request was canceled.
  • COLLECTION: The request is for collecting data or documents.
  • KYC_FORBIDDEN_COUNTRY: The request was rejected because the user is from a country forbidden for KYC (Know Your Customer).

Status Application:

Requests: When a card request is made, it can go through several statuses depending on the processing stage. For example, a request might start as NEW, then move to IN_PROGRESS, and if additional data is needed, to COLLECTION. If an issue arises, the request can move to SUPPORT or ACTION_NEEDED. Upon completion, the request might have the status ACTIVATION (if the card is ready for activation) or CANCELED (if the request is canceled).

Cards: Existing cards have statuses that reflect their current state. For example, a new card will start as INACTIVE and then move to ACTIVE after activation. If the card is lost or suspected of fraud, it can be marked as BLOCKED or HARD_BLOCKED. Closed cards receive the status CLOSED.

10. How to Order a Card in the VISA Card Program?

Answer: To order a card in the VISA Card program, follow the instructions available at the following link: Ordering a VISA Card .

11. Do internal transfers require gas?

Answer: All internal transfers are processed off-chain, so they do not require gas.

12. How to Calculate Transaction Limits?

Answer: Transaction limits are calculated based on the total amount of all fiat transactions made by the user, including both cryptocurrency purchases with fiat (onramp) and cryptocurrency sales with fiat withdrawal (offramp) operations. For each transaction, the deduction from the limit is determined by the maximum value between the purchase amount and the sale amount.

For example, if a user buys cryptocurrency for 1000 EUR and then sells it for 700 EUR, their remaining limit will be reduced by 1000 EUR.

Counters for the total sum of all fiat transactions are updated with each new operation, and their values are used to determine the remaining user limit.

13.How to obtain and use a public key for interacting with the Vault API?

Answer: For detailed instructions on obtaining and using a public key, refer to the Card Information Management documentation.

Here, you will find steps on generating a key pair, encrypting data, and sending requests using the public key to access card details.

14.How to Refresh Your Access Token Using a Refresh Token?

Answer: To refresh your access_token using a refresh_token, follow these steps:

  1. Navigate to the endpoint: SignIn
  2. Enter the parameters in your request:
    • grant_type: Set the value to refresh_token.
    • refresh_token: Enter your current refresh_token.

Upon successful completion of the request, you will receive a new access_token that can be used to authenticate your subsequent requests.

Possible Errors:

  • Invalid refresh_token: Ensure you are using the correct and valid refresh_token.
  • Expired refresh_token: If your refresh_token has expired, you will need to re-authenticate to obtain a new refresh_token.

📘

Refresh token expires in a year

If you encounter any issues or have any questions, please contact support.