Skip to content

Additional Steps

Add customer evidence collection to a wallet verification flow

Additional steps let you request supporting information in the same customer journey as wallet ownership verification. They have their own statuses and do not change the result of the wallet ownership check.

The currently supported type is SOURCE_OF_FUNDS_WEALTH, a combined Source of Funds / Source of Wealth document request. The model is extensible, and more additional-step types may be added later.

Create a Verification with Additional Steps

Add additionalSteps when you create the wallet verification:

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification' \
--header 'X-Api-Key: $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "asset": "ETH",
  "blockchain": "Ethereum",
  "address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
  "metadata": "customer-123",
  "allowedFlows": ["SIGNATURE_PROOF", "VISUAL_PROOF"],
  "origin": "https://app.example.com",
  "additionalSteps": [
    { "type": "SOURCE_OF_FUNDS_WEALTH" }
  ]
}'
Always double-check you are using the correct environment when integrating. Using the wrong base URL or API key will result in authentication errors.

Each create item contains only type. Do not provide status or files in the create request. Step types must be unique. CryptoSwift initializes every requested step to PENDING.

Example returned wallet verification:

{
  "id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "url": "https://wallet-dev.cryptoswift.eu/?token=eyJhbGciOiJIUzI1NiIs...",
  "asset": "ETH",
  "blockchain": "Ethereum",
  "address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
  "metadata": "customer-123",
  "status": "PENDING",
  "flow": null,
  "allowedFlows": ["SIGNATURE_PROOF", "VISUAL_PROOF"],
  "additionalSteps": [
    {
      "type": "SOURCE_OF_FUNDS_WEALTH",
      "status": "PENDING"
    }
  ],
  "reuse": null,
  "createdAt": "2026-09-03T09:00:00.000Z",
  "expiresAt": "2026-09-05T09:00:00.000Z"
}

Statuses

Every item in additionalSteps has an independent lifecycle:

StatusMeaning
PENDINGThe customer still needs to submit the requested evidence.
ACTION_REQUIREDEvidence was submitted and requires manual review.
VERIFIEDThe submitted evidence was reviewed and accepted.
DECLINEDThe submitted evidence was reviewed and rejected.

The top-level status is the wallet ownership verification status. It is independent from every additionalSteps[].status. Submitting, accepting, or declining an additional step does not update the top-level status. For example, a wallet verification can have status: "VERIFIED" while its Source of Funds / Source of Wealth step has status: "ACTION_REQUIRED".

Widget Flow

The Wallet Verification Widget handles requested additional steps automatically:

  1. The customer completes the normal wallet ownership interaction first.
  2. The widget opens each additional step whose status is PENDING.
  3. Submitting the current step changes its status to ACTION_REQUIRED, then the widget continues to the next PENDING step.
  4. When no additional step remains PENDING, the widget shows the final confirmation. Selecting Done/Close completes the redirect or fires onComplete for the web component.

The widget does not wait for manual review before onComplete: ACTION_REQUIRED means the customer submission is complete and reviewer action is now required.

Submit Source of Funds / Source of Wealth Evidence

For a direct API integration, submit one or more files as repeated files fields in multipart/form-data:

POST {{apiBaseUrl}}/wallet-verification/{id}/additional-steps/SOURCE_OF_FUNDS_WEALTH

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/9f3dc458-a2be-4a34-bcb7-f1f677a0864c/additional-steps/SOURCE_OF_FUNDS_WEALTH' \
--header 'X-Api-Key: $API_KEY' \
--form 'files=@source-of-funds.pdf' \
--form 'files=@bank-statement.pdf'

SOURCE_OF_FUNDS_WEALTH accepts up to 10 documents of up to 50 MB each. Supported formats are pdf, doc, docx, xls, xlsx, ppt, pptx, txt, rtf, and csv.

The step must currently be PENDING. The response is the updated wallet verification object, with the submitted step set to ACTION_REQUIRED. Submitted storage paths are not included in that object.

Retrieve Submitted Files

Retrieve short-lived signed URLs for the submitted files:

GET {{apiBaseUrl}}/wallet-verification/{id}/additional-steps/{type}/signed-urls

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/9f3dc458-a2be-4a34-bcb7-f1f677a0864c/additional-steps/SOURCE_OF_FUNDS_WEALTH/signed-urls' \
--header 'X-Api-Key: $API_KEY'

Example response:

{
  "urls": [
    "https://storage.googleapis.com/example/signed-document-url"
  ]
}

Raw storage object paths are not returned.

Manual Review

When the submitted step is ACTION_REQUIRED, a reviewer can load its documents and accept or decline it in the CryptoSwift Dashboard. The Dashboard updates the step through:

PATCH {{apiBaseUrl}}/wallet-verification/{id}/additional-steps/{type}

with one of these decision bodies:

{ "status": "VERIFIED" }

{ "status": "DECLINED" }

The endpoint accepts any supported additional-step status and returns the updated wallet verification object. Changing the step status does not change the top-level wallet ownership status. Additional-step submission and status changes emit wallet-verification webhook notifications.

Next Steps