> ## 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 Initiation Service (Upcoming)

> 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/initiate`


## OpenAPI

````yaml POST /payments/initiate
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/initiate:
    post:
      summary: Initiate Payment
      description: Initiates a payment by redirecting the user to a hosted payment page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiatePaymentRequest'
            examples:
              default:
                value:
                  amount: '100.50'
                  currency: EUR
                  referenceId: uniqueRefId123
                  transactionDescription: 'Payment for Order #12345'
                  returnUrl: https://example.com/callback
                  IBAN: DE89370400440532013000
                  storedBIC: BOFIIE2D
                  language: DE
      responses:
        '200':
          description: Payment successfully initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiatePaymentResponse'
              examples:
                default:
                  value:
                    requestId: req123456789
                    redirectUrl: https://example.com/app/req_123456789
        '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:
    InitiatePaymentRequest:
      type: object
      required:
        - referenceId
        - transactionDescription
        - returnUrl
        - IBAN
        - currency
        - amount
      properties:
        referenceId:
          type: string
          description: Unique identifier for the transaction generated by your system.
          example: uniqueRefId123
        transactionDescription:
          type: string
          description: Description of the transaction.
          example: 'Payment for Order #12345'
        returnUrl:
          type: string
          format: uri
          description: >-
            URL to redirect after payment completion – back to the calling app
            or website.
          example: https://example.com/callback
        IBAN:
          type: string
          description: Recipient's IBAN for direct payment.
          example: DE89370400440532013000
        storedBIC:
          type: string
          description: Pre-stored BIC code.
          example: BOFIIE2D
        language:
          type: string
          description: Language code.
          example: DE
        currency:
          type: string
          description: Currency code.
          example: EUR
        amount:
          type: string
          description: Payment amount formatted as a decimal string.
          example: '12.50'
        country:
          type: string
          description: Country code.
          example: DE
    InitiatePaymentResponse:
      type: object
      required:
        - requestId
        - redirectUrl
      properties:
        requestId:
          type: string
          description: >-
            Unique identifier for the request. Will be used to query the
            transfer status in the Retrieve Transaction Status API call.
          example: req123456789
        redirectUrl:
          type: string
          format: uri
          description: URL to redirect the user to the hosted payment page.
          example: https://example.com/app/req_123456789
    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.

````