> ## 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 Status 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/status`


## OpenAPI

````yaml POST /payments/status
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/status:
    post:
      summary: Retrieve Transaction Status
      description: Retrieves the status of a transaction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveStatusRequest'
            examples:
              default:
                value:
                  referenceId: uniqueRefId123
      responses:
        '200':
          description: Successfully retrieved transaction status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveStatusResponse'
              examples:
                default:
                  value:
                    status: PENDING
                    statusReasonInformation: User redirected to bank.
        '400':
          description: 'Invalid Request: Missing required fields.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: 'Unauthorized: Authentication failed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Permission to access this endpoint is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: 'Not Found: Reference ID not recognized.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: 'Internal Server Error: Unexpected server issue.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: The operation was not implemented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
        '503':
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
        '504':
          description: Gateway has timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error504'
components:
  schemas:
    RetrieveStatusRequest:
      type: object
      required:
        - referenceId
      properties:
        referenceId:
          type: string
          description: >-
            Unique identifier for the transaction generated from the Initiate
            Payment API call.
          example: uniqueRefId123
    RetrieveStatusResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: Transaction status.
          enum:
            - PROCESSING
            - SUCCESS
            - INITIATED
            - PENDING
            - PENDING_EXTERNAL_AUTHORIZATION
            - FAILURE_GENERIC
            - FAILURE_PERMISSION_DENIED
            - FAILURE_CANCELED
            - FAILURE_EXPIRED
            - FAILURE_INSUFFICIENT_FUNDS
            - FAILURE_DECLINED
            - SETTLEMENT_IN_PROGRESS
            - SETTLEMENT_COMPLETED
            - SETTLEMENT_INCOMPLETE
            - COMPLETED
            - FAILED
          example: PENDING
          x-enumDescriptions:
            PROCESSING: >-
              The transaction is in process; the final status has not yet been
              received from the bank.
            SUCCESS: >-
              Successful payment initiation has been received from the bank.
              Settlement might not be complete.
            INITIATED: >-
              The transaction was initiated but the result is unknown. This
              status will not be updated further.
            PENDING: >-
              Authorization at the bank is complete; transfer is pending
              redemption (2-step flows).
            PENDING_EXTERNAL_AUTHORIZATION: >-
              User is at the bank to complete authorization; may transition to
              FAILURE_EXPIRED.
            FAILURE_GENERIC: Technical failure with no additional details from the bank.
            FAILURE_PERMISSION_DENIED: User denied authorization at the bank (2-step flows).
            FAILURE_CANCELED: Payment initiation was canceled before execution.
            FAILURE_EXPIRED: Authorization not completed in time; payment expired.
            FAILURE_INSUFFICIENT_FUNDS: Rejected due to insufficient funds.
            FAILURE_DECLINED: Rejected by the bank.
            SETTLEMENT_IN_PROGRESS: Waiting for funds to reach the payee bank.
            SETTLEMENT_COMPLETED: Funds reached the payee bank; reconciliation complete.
            SETTLEMENT_INCOMPLETE: Reconciliation failed; corresponding transaction not found.
            COMPLETED: 'High-level: transaction completed successfully.'
            FAILED: 'High-level: transaction failed.'
        statusReasonInformation:
          type: string
          description: Additional details about the status.
          example: User redirected to bank.
    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
    Error403:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          example: Forbidden
    Error404:
      type: object
      properties:
        message:
          type: string
          example: Journey not found
    Error429:
      type: object
      properties:
        error:
          type: string
          example: Too Many Requests
        message:
          type: string
          example: Rate limit exceeded.
        code:
          type: string
          example: '429'
    Error500:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          example: Internal Server Error
    Error501:
      type: object
      properties:
        error:
          type: string
          example: Not Implemented
        message:
          type: string
          example: The operation was not implemented.
        code:
          type: string
          example: '501'
    Error503:
      type: object
      properties:
        error:
          type: string
          example: Service Unavailable
        message:
          type: string
          example: Service is unavailable.
        code:
          type: string
          example: '503'
    Error504:
      type: object
      properties:
        error:
          type: string
          example: Gateway Timeout
        message:
          type: string
          example: Gateway has timed out.
        code:
          type: string
          example: '504'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from POST /auth. Valid for 60 minutes.

````