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

# List payments or find by order ID

> With orderId returns one transaction or 404. Otherwise returns newest first by created_at and ID; use next_cursor as starting_after. Merchant and live/test mode come only from the API key. All money is decimal-string major units.



## OpenAPI

````yaml /openapi.json get /v1/payment
openapi: 3.1.0
info:
  contact:
    name: OrsunPay
  description: >-
    Server-to-server merchant payments. Money is always a decimal string in
    major units.
  title: OrsunPay Merchant API
  version: '1.0'
servers: []
security: []
tags:
  - description: Poll stored merchant transaction status
    name: Transactions
  - description: Create merchant sales and payouts
    name: Payments
  - description: Request refunds and read stored refund outcomes
    name: Refunds
  - description: Signed merchant event deliveries
    name: Webhooks
  - description: Create, list and deactivate shareable merchant payment links
    name: Payment links
paths:
  /v1/payment:
    get:
      tags:
        - Payments
      summary: List payments or find by order ID
      description: >-
        With orderId returns one transaction or 404. Otherwise returns newest
        first by created_at and ID; use next_cursor as starting_after. Merchant
        and live/test mode come only from the API key. All money is
        decimal-string major units.
      operationId: listPayments
      parameters:
        - description: Exact merchant order ID; cannot be combined with list parameters
          in: query
          name: orderId
          required: false
          schema:
            maxLength: 100
            type: string
        - in: query
          name: limit
          required: false
          schema:
            default: 25
            maximum: 100
            minimum: 1
            type: number
        - description: next_cursor from the previous page (transaction ID)
          in: query
          name: starting_after
          required: false
          schema:
            maxLength: 32
            type: string
        - in: query
          name: status
          required: false
          schema:
            enum:
              - CREATED
              - WAIT_APPROVE
              - PROCESSING
              - SUCCESS
              - DECLINED
              - CANCELED
              - EXPIRED
            type: string
        - in: query
          name: action
          required: false
          schema:
            enum:
              - SALE
              - PAYOUT
            type: string
        - description: Inclusive creation time, with timezone
          in: query
          name: created_gte
          required: false
          schema:
            format: date-time
            type: string
        - description: Exclusive creation time, with timezone
          in: query
          name: created_lt
          required: false
          schema:
            format: date-time
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PaymentListResponseDto'
                  - $ref: '#/components/schemas/TransactionStatusResponseDto'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDto'
          description: Invalid query or cursor
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponseDto'
          description: Missing or invalid API key
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionNotFoundResponseDto'
          description: Payment not found for the authenticated merchant and mode
        '429':
          content:
            application/json:
              example:
                error: RATE_LIMITED
                errorCode: RATE_LIMITED
                message: Too many requests. Retry after the indicated delay.
                status: false
                statusCode: 429
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
          description: >-
            RATE_LIMITED: IP, merchant or failed-auth quota exhausted, or
            auth-in-flight concurrency pressure (Retry-After: 1). Wait
            Retry-After seconds and retry with the same Idempotency-Key.
          headers:
            RateLimit:
              description: >-
                Remaining requests (r) and seconds to reset/full refill (t), per
                evaluated policy. Absent when disabled; merchant quota is
                omitted during Redis outages, while IP/auth protection uses
                replica memory.
              schema:
                example: '"merchant";r=37;t=4'
                type: string
            RateLimit-Policy:
              description: >-
                Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q
                is burst quota; w is the full refill window in seconds.
              schema:
                example: '"merchant";q=100;w=5'
                type: string
            Retry-After:
              description: Minimum delay in whole seconds before retrying.
              schema:
                example: 1
                minimum: 1
                type: integer
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
          description: Payment core unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationUnavailableResponseDto'
          description: Authentication temporarily unavailable
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
          description: Payment core deadline exceeded
      security:
        - X-API-Key: []
components:
  schemas:
    PaymentListResponseDto:
      properties:
        data:
          items:
            $ref: '#/components/schemas/MerchantTransactionDto'
          type: array
        has_more:
          example: false
          type: boolean
        next_cursor:
          anyOf:
            - description: Pass as starting_after for the next page
              example: null
              type: string
            - type: 'null'
        status:
          example: true
          type: boolean
      required:
        - status
        - data
        - has_more
        - next_cursor
      type: object
    TransactionStatusResponseDto:
      properties:
        status:
          example: true
          type: boolean
        transaction:
          $ref: '#/components/schemas/MerchantTransactionDto'
      required:
        - status
        - transaction
      type: object
    ValidationErrorResponseDto:
      properties:
        error:
          example: Bad Request
          type: string
        message:
          example:
            - >-
              amount must be a decimal string in major units, e.g. "12.30"; JSON
              numbers are not accepted for money (got 12.3)
          items:
            type: string
          type: array
        statusCode:
          example: 400
          type: number
      required:
        - statusCode
        - error
        - message
      type: object
    UnauthorizedErrorResponseDto:
      properties:
        error:
          example: Unauthorized
          type: string
        errorCode:
          description: Stable authentication error code when available
          example: API_KEY_ROTATION_REQUIRED
          type: string
        message:
          example: Invalid API key
          type: string
        statusCode:
          description: HTTP status when included by the error handler
          example: 401
          type: number
      required:
        - message
      type: object
    TransactionNotFoundResponseDto:
      properties:
        error:
          example: Not Found
          type: string
        message:
          example: Transaction not found
          type: string
        statusCode:
          example: 404
          type: number
      required:
        - statusCode
        - error
        - message
      type: object
    ApiErrorResponseDto:
      properties:
        error:
          description: Same as errorCode
          example: DUPLICATE_ORDER_ID
          type: string
        errorCode:
          description: >-
            Machine-readable, extensible code. Known values: ADYEN_REFUSED,
            CARD_DATA_NOT_ACCEPTED, RATE_LIMITED, PAYMENT_LINK_INVALID_AMOUNT,
            PAYMENT_LINK_UNSUPPORTED_CURRENCY, PAYMENT_LINK_INVALID_EXPIRY,
            PAYMENT_LINK_INVALID_MAX_USES,
            PAYMENT_LINK_REDIRECT_URL_NOT_ALLOWED,
            PAYMENT_LINK_METADATA_TOO_LARGE, PAYMENT_LINK_INVALID_TEXT,
            PAYMENT_LINK_NOT_FOUND, PAYMENT_LINK_INVALID_LIMIT,
            PAYMENT_LINK_INVALID_CURSOR, API_KEY_ROTATION_REQUIRED,
            ORDER_ID_RESERVED, NO_CREDENTIALS_FOR_MODE, LIVEMODE_MISMATCH,
            PSP_OUTCOME_UNKNOWN, PAYMENT_METHOD_REQUIRED,
            PAYMENT_METHOD_INPUT_WITHOUT_METHOD, NO_PAYMENT_METHODS,
            IDEMPOTENCY_KEY_INVALID, DUPLICATE_ORDER_ID,
            IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED, UPSTREAM_ERROR,
            UPSTREAM_UNAVAILABLE, UPSTREAM_TIMEOUT, REFUND_INVALID_AMOUNT,
            REFUND_INVALID_REASON, REFUND_INVALID_METADATA,
            REFUND_INPUT_INVALID, REFUND_EXCEEDS_AMOUNT,
            TRANSACTION_NOT_REFUNDABLE, REFUND_NOT_FOUND, REFUND_NOT_SUPPORTED,
            IDEMPOTENCY_LEASE_LOST, REFUND_SERVICE_UNAVAILABLE. New codes may be
            added; clients must handle unknown values.
          example: DUPLICATE_ORDER_ID
          type: string
        existingTransactionId:
          description: >-
            DUPLICATE_ORDER_ID only: the transaction that already uses this
            orderId
          example: tr_x8k2p0q5scocndpejk0nud75q
          type: string
        fields:
          description: >-
            Invalid or missing buyer contact fields for
            CUSTOMER_CONTACT_REQUIRED
          example:
            - customer.email
            - customer.country
          items:
            type: string
          type: array
        idempotencyKey:
          description: IDEMPOTENCY_* errors only
          example: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10
          type: string
        message:
          example: A transaction with orderId "A-1001" already exists for this merchant
          type: string
        orderId:
          description: DUPLICATE_ORDER_ID only
          example: A-1001
          type: string
        status:
          example: false
          type: boolean
        statusCode:
          example: 409
          type: number
      required:
        - status
        - statusCode
        - errorCode
        - error
        - message
      type: object
    AuthenticationUnavailableResponseDto:
      properties:
        error:
          example: Service Unavailable
          type: string
        message:
          example: API_KEY_VALIDATION_UNAVAILABLE
          type: string
        statusCode:
          example: 503
          type: number
      required:
        - statusCode
        - error
        - message
      type: object
    MerchantTransactionDto:
      properties:
        action:
          description: Transaction action type
          enum:
            - SALE
            - PAYOUT
            - AUTHORIZE
            - REFUND
            - CHARGEBACK
          example: SALE
          type: string
        amount:
          description: >-
            Transaction amount in `currency`. Decimal string in major units,
            padded to the currency exponent ("10.00" EUR, "5000" JPY). Parse
            with a decimal library, never with parseFloat.
          example: '10.00'
          pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$
          type: string
        createdAt:
          description: Transaction creation timestamp
          example: '2023-12-25T10:00:00.000Z'
          format: date-time
          type: string
        currency:
          description: Transaction currency
          enum:
            - AED
            - AFN
            - ALL
            - AMD
            - ANG
            - AOA
            - ARS
            - AUD
            - AWG
            - AZN
            - BAM
            - BBD
            - BDT
            - BGN
            - BHD
            - BIF
            - BMD
            - BND
            - BOB
            - BRL
            - BSD
            - BTN
            - BWP
            - BYN
            - BZD
            - CAD
            - CDF
            - CHF
            - CLF
            - CLP
            - CNY
            - COP
            - CRC
            - CUC
            - CUP
            - CVE
            - CZK
            - DJF
            - DKK
            - DOP
            - DZD
            - EGP
            - ERN
            - ETB
            - EUR
            - FJD
            - FKP
            - GBP
            - GEL
            - GHS
            - GIP
            - GMD
            - GNF
            - GTQ
            - GYD
            - HKD
            - HNL
            - HRK
            - HTG
            - HUF
            - IDR
            - ILS
            - INR
            - IQD
            - IRR
            - ISK
            - JMD
            - JOD
            - JPY
            - KES
            - KGS
            - KHR
            - KMF
            - KPW
            - KRW
            - KWD
            - KYD
            - KZT
            - LAK
            - LBP
            - LKR
            - LRD
            - LSL
            - LYD
            - MAD
            - MDL
            - MGA
            - MKD
            - MMK
            - MNT
            - MOP
            - MRU
            - MUR
            - MVR
            - MWK
            - MXN
            - MYR
            - MZN
            - NAD
            - NGN
            - NIO
            - NOK
            - NPR
            - NZD
            - OMR
            - PAB
            - PEN
            - PGK
            - PHP
            - PKR
            - PLN
            - PYG
            - QAR
            - RON
            - RSD
            - RUB
            - RWF
            - SAR
            - SBD
            - SCR
            - SDG
            - SEK
            - SGD
            - SHP
            - SLL
            - SOS
            - SRD
            - SSP
            - STN
            - SVC
            - SYP
            - SZL
            - THB
            - TJS
            - TMT
            - TND
            - TOP
            - TRY
            - TTD
            - TWD
            - TZS
            - UAH
            - UGX
            - USD
            - UYU
            - UZS
            - VES
            - VND
            - VUV
            - WST
            - XAF
            - XAG
            - XAU
            - XCD
            - XDR
            - XOF
            - XPF
            - YER
            - ZAR
            - ZMW
            - ZWL
          example: USD
          type: string
        errorCode:
          anyOf:
            - description: >-
                Payment error/outcome reason. LIVEMODE_MISMATCH means the
                transaction was DECLINED before PSP dispatch; creation still
                returns HTTP 201 with status: true. PSP_OUTCOME_UNKNOWN means
                reconcile or poll; do not create another order.
                PSP_INPUT_INVALID identifies local legacy-submit
                serialization/codec failures; PSP_REQUEST_REJECTED identifies a
                definitive upstream rejection.
              example: PSP_OUTCOME_UNKNOWN
              type: string
            - type: 'null'
        id:
          description: Transaction ID
          example: tr_xv0p2q5scocndpejk0nud75q
          type: string
        livemode:
          description: >-
            True for live payments; false for sandbox payments. Derived from the
            authenticated API key.
          example: true
          type: boolean
        orderId:
          description: Order ID from merchant system
          example: transaction_123
          type: string
        processingAmount:
          anyOf:
            - description: >-
                Amount in `processingCurrency`. Decimal string in major units,
                padded to the currency exponent ("10.00" EUR, "5000" JPY). Parse
                with a decimal library, never with parseFloat.
              example: '9.57'
              pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$
              type: string
            - type: 'null'
        processingCurrency:
          description: Currency the PSP is charged in (differs from `currency` with DCC)
          enum:
            - AED
            - AFN
            - ALL
            - AMD
            - ANG
            - AOA
            - ARS
            - AUD
            - AWG
            - AZN
            - BAM
            - BBD
            - BDT
            - BGN
            - BHD
            - BIF
            - BMD
            - BND
            - BOB
            - BRL
            - BSD
            - BTN
            - BWP
            - BYN
            - BZD
            - CAD
            - CDF
            - CHF
            - CLF
            - CLP
            - CNY
            - COP
            - CRC
            - CUC
            - CUP
            - CVE
            - CZK
            - DJF
            - DKK
            - DOP
            - DZD
            - EGP
            - ERN
            - ETB
            - EUR
            - FJD
            - FKP
            - GBP
            - GEL
            - GHS
            - GIP
            - GMD
            - GNF
            - GTQ
            - GYD
            - HKD
            - HNL
            - HRK
            - HTG
            - HUF
            - IDR
            - ILS
            - INR
            - IQD
            - IRR
            - ISK
            - JMD
            - JOD
            - JPY
            - KES
            - KGS
            - KHR
            - KMF
            - KPW
            - KRW
            - KWD
            - KYD
            - KZT
            - LAK
            - LBP
            - LKR
            - LRD
            - LSL
            - LYD
            - MAD
            - MDL
            - MGA
            - MKD
            - MMK
            - MNT
            - MOP
            - MRU
            - MUR
            - MVR
            - MWK
            - MXN
            - MYR
            - MZN
            - NAD
            - NGN
            - NIO
            - NOK
            - NPR
            - NZD
            - OMR
            - PAB
            - PEN
            - PGK
            - PHP
            - PKR
            - PLN
            - PYG
            - QAR
            - RON
            - RSD
            - RUB
            - RWF
            - SAR
            - SBD
            - SCR
            - SDG
            - SEK
            - SGD
            - SHP
            - SLL
            - SOS
            - SRD
            - SSP
            - STN
            - SVC
            - SYP
            - SZL
            - THB
            - TJS
            - TMT
            - TND
            - TOP
            - TRY
            - TTD
            - TWD
            - TZS
            - UAH
            - UGX
            - USD
            - UYU
            - UZS
            - VES
            - VND
            - VUV
            - WST
            - XAF
            - XAG
            - XAU
            - XCD
            - XDR
            - XOF
            - XPF
            - YER
            - ZAR
            - ZMW
            - ZWL
          example: EUR
          type: string
        status:
          description: Transaction status
          enum:
            - CREATED
            - WAIT_APPROVE
            - PROCESSING
            - CANCELED
            - DECLINED
            - SUCCESS
            - EXPIRED
          example: PROCESSING
          type: string
      required:
        - livemode
        - id
        - orderId
        - status
        - action
        - amount
        - currency
        - createdAt
      type: object
  securitySchemes:
    X-API-Key:
      in: header
      name: x-api-key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.