> ## Documentation Index
> Fetch the complete documentation index at: https://umbrella-docs.info/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Challenge Deposit Service

> Payment Service API Documentation

For a usage description of the Payment Initiation Service, please refer to the [Payment Services](/essentials/paymentServices) page.

## Endpoint

**POST** `/payments/challenge-deposit`

## Swagger

<a href="/public/downloads/swagger/paymentServices/ChallengeDeposit.postman_collection.json" download="ChallengeDeposit.postman_collection.json">
  <button>⬇️ Download OpenAPI YAML</button>
</a>


## OpenAPI

````yaml POST /payments/challenge-deposit
openapi: 3.1.0
info:
  title: Umbrella API
  version: 1.0.0
  description: >-
    API documentation for Umbrella services including KYB, KYC, AML, payments,
    phone intelligence, onboarding, and address verification.
servers:
  - url: https://api-umbrella.io/api/services
    description: Production
  - url: https://sandbox-umbrella-api.azurewebsites.net/api/services
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /payments/challenge-deposit:
    post:
      summary: Initiate Challenge Deposit
      description: >-
        Initiates a challenge deposit to verify user identity by sending a small
        amount to the bank account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChallengeDepositRequest'
            examples:
              default:
                value:
                  amount: '0.10'
                  currency: EUR
                  description: merchantId19887-65
                  firstName: John
                  lastName: Doe
                  piiToggle: 1
                  nameMatchLogic: fuzzy
      responses:
        '200':
          description: Successfully initiated challenge deposit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeDepositResponse'
              examples:
                default:
                  value:
                    transactionId: e5c81c78-272b-4307-9197-3ace19109fd3
                    description: merchantId19887-65
                    status: OK
                    globalResult:
                      overall: review
                      totalScore: 100
                    nameMatchScore: 85
                    iban: DE44500105175407324931
                    returnedFirstName: John
                    returnedLastName: Doe
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
components:
  schemas:
    ChallengeDepositRequest:
      type: object
      required:
        - amount
        - currency
        - description
        - firstName
        - lastName
        - piiToggle
        - nameMatchLogic
      properties:
        amount:
          type: string
          description: Small amount sent for verification.
          example: '0.10'
          pattern: ^[0-9]+(\.[0-9]{1,2})?$
        currency:
          type: string
          description: Currency code.
          example: EUR
          minLength: 3
          maxLength: 3
        description:
          type: string
          description: >-
            Mandatory, non-blank. Alphanumeric only; hyphens (-) allowed as
            separators. No spaces or other special characters.
          example: merchantId19887-65
          pattern: ^[A-Za-z0-9-]+$
        firstName:
          type: string
          description: First name for identity verification.
          example: John
        lastName:
          type: string
          description: Last name for identity verification.
          example: Doe
        piiToggle:
          type: integer
          description: Determines if PII details should be returned.
          enum:
            - 0
            - 1
          example: 1
        nameMatchLogic:
          type: string
          description: Name matching logic type.
          enum:
            - exact
            - fuzzy
          example: fuzzy
    ChallengeDepositResponse:
      type: object
      required:
        - description
        - status
        - globalResult
        - nameMatchScore
      properties:
        transactionId:
          type: string
          description: Unique identifier for the challenge deposit transaction.
          example: e5c81c78-272b-4307-9197-3ace19109fd3
        description:
          type: string
          description: The description sent in the request.
          example: merchantId19887-65
        status:
          type: string
          description: Status of the challenge deposit.
          enum:
            - OK
            - FAIL
          example: OK
        globalResult:
          type: object
          description: Contains verification score and assessment result.
          required:
            - overall
            - totalScore
          properties:
            overall:
              type: string
              description: Overall assessment.
              enum:
                - review
                - pass
                - fail
              example: review
            totalScore:
              type: integer
              description: Score (0-100) indicating verification quality.
              minimum: 0
              maximum: 100
              example: 100
        nameMatchScore:
          type: integer
          description: Score (0-100) indicating how well names matched.
          minimum: 0
          maximum: 100
          example: 85
        iban:
          type: string
          description: Verified IBAN.
          example: DE44500105175407324931
        returnedFirstName:
          type: string
          description: >-
            First name returned from verification if available and `piiToggle =
            1`.
          example: John
        returnedLastName:
          type: string
          description: >-
            Last name returned from verification if available and `piiToggle =
            1`.
          example: Doe
    Error400:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          example: Invalid request payload
    Error401:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          example: Unauthorized request
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from POST /auth. Valid for 60 minutes.

````