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

# Get payment status

> Get the current status of a payment, including progress through onramp/swap/offramp stages.




## OpenAPI

````yaml /public/openapi.yaml get /payments
openapi: 3.1.0
info:
  title: Halliday API V2
  description: >
    API V2 for Halliday's payment infrastructure, supporting onramps, swaps, and
    offramps.


    This API provides a unified interface for cryptocurrency payments, allowing
    developers to:

    - Quote payments across multiple providers

    - Execute payments with onramps, swaps, and offramps

    - Track payment status and history


    ## Authentication


    API key authentication is required for all endpoints.
  version: 2.0.0
  contact:
    name: Contact Halliday
    url: https://halliday.xyz
    email: support@halliday.xyz
servers:
  - url: https://v2.prod.halliday.xyz
    description: Base domain
security:
  - ApiKeyAuth: []
tags:
  - name: Chains
    description: Blockchain network information and configuration
  - name: Assets
    description: Asset information, discovery, and supported asset pairs
  - name: Payments
    description: >-
      Core payment operations including quotes, confirmation, and status
      tracking
  - name: Webhooks
    description: >
      Register HTTPS endpoints to receive signed notifications when a workflow
      reaches a terminal

      state, instead of polling for status. You subscribe to one or more event
      types per webhook.


      | Event type | Fires when a workflow's status becomes |

      | --- | --- |

      | `WORKFLOW_COMPLETED` | `COMPLETE` |

      | `WORKFLOW_FAILED` | `FAILED` |


      All management endpoints live under `/orgs/webhooks` and authenticate with
      a secret API key

      (passed as a bearer token) that has webhook access. Publishable keys
      cannot manage webhooks.


      **Integration checklist**


      - Receiver is a public HTTPS endpoint (no private IPs).

      - Save the `signing_secret` when you create the webhook — it is shown only
      once.

      - Verify `X-Halliday-Signature` against the raw body, accepting any of its
      comma-separated signatures.

      - Respond `2xx` quickly and do the real work afterward.

      - Skip deliveries whose `id` you have already handled.
paths:
  /payments:
    get:
      tags:
        - Payments
      summary: Get payment status
      description: >
        Get the current status of a payment, including progress through
        onramp/swap/offramp stages.
      operationId: getPaymentStatus
      parameters:
        - name: payment_id
          in: query
          required: true
          description: Payment identifier to check
          schema:
            type: string
      responses:
        '200':
          description: Payment status retrieved successfully!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: 'Missing required parameter: payment_id'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: You do not have permission to view this payment
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Payment with payment_id 'pay_abc123' not found
components:
  schemas:
    PaymentStatus:
      type: object
      required:
        - payment_id
        - org_id
        - status
        - funded
        - created_at
        - updated_at
        - initiate_fund_by
        - quoted
        - fulfilled
        - current_prices
        - price_currency
        - processing_addresses
        - owner_chain
        - owner_address
        - destination_address
        - client_redirect_url
        - declaration
      properties:
        payment_id:
          type: string
        org_id:
          type: string
          description: Organization identifier
        status:
          type: string
          enum:
            - PENDING
            - COMPLETE
            - FAILED
            - EXPIRED
            - WITHDRAW_PENDING
            - WITHDRAWN
            - TAINTED
            - UNCONFIRMED
        funded:
          type: boolean
          description: Whether the payment has been funded
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        initiate_fund_by:
          type: string
          format: date-time
          description: Deadline for funding the payment.
        completed_at:
          type: string
          format: date-time
        quote_request:
          $ref: '#/components/schemas/QuoteRequest'
          description: The original quote request.
        quoted:
          $ref: '#/components/schemas/QuotedEntry'
        fulfilled:
          $ref: '#/components/schemas/FulfilledEntry'
        current_prices:
          type: object
          additionalProperties:
            type: string
          description: Mapping of asset symbols to their unit prices
          example:
            USD: '1.00'
            ethereum:0x: '4200'
            ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48: '1.00'
        price_currency:
          $ref: '#/components/schemas/Asset'
          description: Fiat asset used for pricing
        customer_id:
          type: string
          description: ID of the customer who created the payment
        label:
          type: string
          description: Optional payment label
          maxLength: 255
        processing_addresses:
          type: array
          items:
            type: object
            required:
              - chain
              - address
              - factory
            properties:
              chain:
                type: string
                description: Blockchain network
                example: ethereum
              address:
                type: string
                description: Payment processing contract address
              factory:
                type: string
                description: Factory contract address
        owner_chain:
          type: string
          description: Chain identifier for the owner
        owner_address:
          type: string
          description: Address of the owner of the payment
        destination_address:
          type: string
          description: Address of the destination of the payment
        next_instruction:
          $ref: '#/components/schemas/NextInstruction'
          nullable: true
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
          description: Payment validation issues
        parent_payment_id:
          type: string
          format: uuid
          description: Parent payment reference
        client_redirect_url:
          type: string
          nullable: true
          description: Client redirect URL
        declaration:
          type: object
          nullable: true
          description: Declaration object
    ErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
      description: Error response for known errors
    QuoteRequest:
      type: object
      required:
        - request
        - price_currency
      properties:
        request:
          $ref: '#/components/schemas/FixedInputQuoteRequest'
        price_currency:
          type: string
          description: Currency that all prices are denominated in
          example: USD
        onramps:
          type: array
          items:
            type: string
          description: Filter by specific onramp providers
          example:
            - moonpay
            - coinbase
        onramp_methods:
          type: array
          items:
            type: string
            enum:
              - CREDIT_CARD
              - DEBIT_CARD
              - ACH
              - FIAT_BALANCE
              - TOKEN_BALANCE
              - APPLE_PAY
              - PAYPAL
              - VENMO
              - REVOLUT
              - GOOGLE_PAY
              - SEPA
              - FASTER_PAYMENTS
              - PIX
              - UPI
              - WIRE
          description: Filter by onramp payment methods
          example:
            - CREDIT_CARD
            - ACH
            - APPLE_PAY
        customer_ip_address:
          type: string
          description: IP address of the customer
        customer_id:
          type: string
          description: Customer ID for tracking
        parent_payment_id:
          type: string
          description: >-
            Optional parent payment identifier used when creating a quote from
            an existing payment.
        label:
          type: string
          maxLength: 255
          description: Optional label for the payment.
        features:
          type: array
          items:
            type: string
            enum:
              - BETA_EDGES
              - ORG_BETA_EDGES
              - ORG_EDGES
          description: Feature flags to enable for this quote.
        rev_share_name:
          type: string
          description: Revenue share configuration name.
        allow_unsafe_transfer_out:
          type: boolean
          description: Allow unsafe transfer out operations.
        show_all_issues:
          type: boolean
          description: Return all validation issues instead of failing on the first.
        allow_unsafe_slippage:
          type: boolean
          description: Allow quotes with higher than normal slippage.
        allow_exceed_max_input_limit:
          type: boolean
          description: Allow quotes that exceed the maximum input limit.
        use_intent_refund:
          type: boolean
          description: Use intent-based refund flow.
        hops:
          type: array
          items:
            type: string
          description: Intermediate chain hops for routing.
    QuotedEntry:
      type: object
      required:
        - fees
        - output_amount
        - route
      properties:
        output_amount:
          $ref: '#/components/schemas/AssetAmount'
        fees:
          $ref: '#/components/schemas/Fees'
        onramp:
          type: string
          description: Onramp provider name
        onramp_method:
          type: string
          enum:
            - CREDIT_CARD
            - DEBIT_CARD
            - ACH
            - FIAT_BALANCE
            - TOKEN_BALANCE
            - APPLE_PAY
            - PAYPAL
            - VENMO
            - REVOLUT
            - GOOGLE_PAY
            - SEPA
            - FASTER_PAYMENTS
            - PIX
            - UPI
            - WIRE
          description: Payment method
          example: CREDIT_CARD
        route:
          type: array
          items:
            $ref: '#/components/schemas/QuotedRouteItem'
          description: Quoted workflow steps and their effects
    FulfilledEntry:
      type: object
      required:
        - route
      properties:
        output_amount:
          $ref: '#/components/schemas/AssetAmount'
        fees:
          $ref: '#/components/schemas/Fees'
        onramp:
          type: string
          description: Onramp provider name
        onramp_method:
          type: string
          enum:
            - CREDIT_CARD
            - DEBIT_CARD
            - ACH
            - FIAT_BALANCE
            - TOKEN_BALANCE
            - APPLE_PAY
            - PAYPAL
            - VENMO
            - REVOLUT
            - GOOGLE_PAY
            - SEPA
            - FASTER_PAYMENTS
            - PIX
            - UPI
            - WIRE
          description: Payment method
          example: CREDIT_CARD
        route:
          type: array
          items:
            $ref: '#/components/schemas/FulfilledRouteItem'
          description: In-progress workflow steps, statuses, and their effects
    Asset:
      type: string
      description: >-
        Identifier in the token format ("chain:address") or fiat currency code
        ("USD")
      example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    NextInstruction:
      description: >-
        Instruction payload that returns the funding pages if the payment
        requires funding.
      oneOf:
        - $ref: '#/components/schemas/OnrampOrTransferInInstruction'
        - $ref: '#/components/schemas/UserVerifyInstruction'
      discriminator:
        propertyName: type
        mapping:
          ONRAMP:
            $ref: '#/components/schemas/OnrampOrTransferInInstruction'
          TRANSFER_IN:
            $ref: '#/components/schemas/OnrampOrTransferInInstruction'
          USER_VERIFY:
            $ref: '#/components/schemas/UserVerifyInstruction'
      example:
        type: ONRAMP
        payment_id: <string>
        funding_page_url: https://app.halliday.xyz/funding/${payment_id}
        deposit_info:
          - deposit_token: base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
            deposit_amount: '4.8'
            deposit_address: 0xaddress
            deposit_chain: base
    Issue:
      oneOf:
        - $ref: '#/components/schemas/AmountIssue'
        - $ref: '#/components/schemas/AmountDownstreamIssue'
        - $ref: '#/components/schemas/FundingIssue'
        - $ref: '#/components/schemas/OwnerIssue'
        - $ref: '#/components/schemas/GeolocationIssue'
        - $ref: '#/components/schemas/ProviderIssue'
        - $ref: '#/components/schemas/PayinMethodIssue'
        - $ref: '#/components/schemas/OtherIssue'
        - $ref: '#/components/schemas/UnknownIssue'
      discriminator:
        propertyName: kind
    FixedInputQuoteRequest:
      type: object
      required:
        - kind
        - fixed_input_amount
        - output_asset
      properties:
        kind:
          type: string
          enum:
            - FIXED_INPUT
        fixed_input_amount:
          $ref: '#/components/schemas/AssetAmount'
        output_asset:
          $ref: '#/components/schemas/Asset'
        dest_address:
          type: string
          description: Optional destination address for the output tokens.
        custom_actions:
          type: object
          description: Optional custom onchain actions to execute as part of the payment.
          properties:
            actions:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - CallImmediateAction
                  target:
                    type: string
                    description: Target contract address.
                  value:
                    type: string
                    description: Native token value to send.
                  calldata:
                    type: string
                    description: Encoded calldata for the contract call.
            user_estimated_gas:
              type: string
              description: Estimated gas for the custom actions.
    AssetAmount:
      type: object
      required:
        - asset
        - amount
      properties:
        asset:
          $ref: '#/components/schemas/Asset'
        amount:
          type: string
          description: Amount as a string to preserve precision
          example: '1'
    Fees:
      type: object
      required:
        - total_fees
        - conversion_fees
        - network_fees
        - business_fees
        - currency_symbol
      properties:
        total_fees:
          type: string
          description: Total fees amount
        conversion_fees:
          type: string
          description: Ramps + bridge + DEX fees
        network_fees:
          type: string
          description: Blockchain gas fees
        business_fees:
          type: string
          description: Developer integration fees
        currency_symbol:
          type: string
          pattern: ^[a-zA-Z]\w{1,7}$
          description: Fiat currency symbol that the fees are denominated in (e.g., "USD")
          example: USD
    QuotedRouteItem:
      type: object
      required:
        - type
        - net_effect
        - pieces_info
      properties:
        type:
          type: string
          enum:
            - ONRAMP
            - ONCHAIN_STEP
            - USER_FUND
        net_effect:
          $ref: '#/components/schemas/EffectAmount'
        pieces_info:
          type: array
          items:
            $ref: '#/components/schemas/PieceInfo'
        step_index:
          type: number
    FulfilledRouteItem:
      type: object
      required:
        - status
        - type
        - net_effect
        - pieces_info
      properties:
        status:
          type: string
          enum:
            - PENDING
            - COMPLETE
            - UNREACHABLE
            - FAILED
        type:
          type: string
          enum:
            - ONRAMP
            - ONCHAIN_STEP
            - USER_FUND
        net_effect:
          $ref: '#/components/schemas/EffectAmount'
        pieces_info:
          type: array
          items:
            $ref: '#/components/schemas/PieceInfo'
        step_index:
          type: number
        transaction_hash:
          type: string
          description: Blockchain transaction hash for the step
    OnrampOrTransferInInstruction:
      type: object
      required:
        - type
        - payment_id
        - funding_page_url
        - deposit_info
      properties:
        type:
          type: string
          enum:
            - ONRAMP
            - TRANSFER_IN
          description: Discriminator for this instruction type.
        payment_id:
          type: string
          description: The payment this instruction is associated with.
        funding_page_url:
          type: string
          format: uri
          description: URL where the user can complete funding for this payment.
        deposit_info:
          type: array
          description: One or more deposit routes to fund the payment.
          items:
            $ref: '#/components/schemas/DepositInfo'
    UserVerifyInstruction:
      type: object
      required:
        - type
        - verification_token
        - verifications
      properties:
        type:
          type: string
          enum:
            - USER_VERIFY
          description: Discriminator for this instruction type.
        verification_token:
          type: string
          description: Token to submit with verification signatures.
        verifications:
          type: array
          description: List of verifications the user must complete.
          items:
            type: object
            required:
              - reason
              - signature_type
              - payload
            properties:
              reason:
                type: string
                enum:
                  - EVM_OWNER
                  - EVM_WITHDRAWAL
                description: Reason for the verification.
              signature_type:
                type: string
                enum:
                  - EIP712
                  - EIP191
                description: Signature type required.
              payload:
                type: string
                description: Payload to sign.
    AmountIssue:
      type: object
      required:
        - kind
        - asset
        - given
        - limits
        - source
        - message
        - reason
      properties:
        kind:
          type: string
          enum:
            - amount
        asset:
          $ref: '#/components/schemas/Asset'
        given:
          $ref: '#/components/schemas/Amount'
        limits:
          $ref: '#/components/schemas/Limits'
        downstream_limits:
          $ref: '#/components/schemas/Limits'
        source:
          type: string
        message:
          type: string
        reason:
          type: string
          enum:
            - TOO_LOW
            - TOO_HIGH
            - NO_VALID_AMOUNT
            - UNKNOWN
    AmountDownstreamIssue:
      type: object
      required:
        - kind
        - asset
        - given
        - limits
        - source
        - message
        - reason
      properties:
        kind:
          type: string
          enum:
            - amount-downstream
        asset:
          $ref: '#/components/schemas/Asset'
        given:
          $ref: '#/components/schemas/Amount'
        limits:
          $ref: '#/components/schemas/Limits'
        downstream_limits:
          $ref: '#/components/schemas/Limits'
        source:
          type: string
        message:
          type: string
        reason:
          type: string
          enum:
            - TOO_LOW
            - TOO_HIGH
            - NO_VALID_AMOUNT
            - UNKNOWN
    FundingIssue:
      type: object
      required:
        - kind
        - token
        - balance
      properties:
        kind:
          type: string
          enum:
            - funding
        token:
          $ref: '#/components/schemas/Token'
        balance:
          type: string
          description: Current token balance at the funding address.
    OwnerIssue:
      type: object
      required:
        - kind
        - message
        - mitigation
      properties:
        kind:
          type: string
          enum:
            - owner
        message:
          type: string
        mitigation:
          type: string
          enum:
            - change
            - verify
    GeolocationIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - geolocation
        message:
          type: string
    ProviderIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - provider
        message:
          type: string
    PayinMethodIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - payin_method
        message:
          type: string
    OtherIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - other
        message:
          type: string
    UnknownIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - unknown
        message:
          type: string
    EffectAmount:
      type: object
      required:
        - consume
        - produce
      properties:
        consume:
          type: array
          items:
            $ref: '#/components/schemas/ChangeAmount'
        produce:
          type: array
          items:
            $ref: '#/components/schemas/ChangeAmount'
    PieceInfo:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - user_fund
            - onramp
            - poll
            - bridge
            - rev_share
            - transfer_out
            - convert
            - custom_call
    DepositInfo:
      type: object
      required:
        - deposit_token
        - deposit_amount
        - deposit_address
        - deposit_chain
      properties:
        deposit_token:
          $ref: '#/components/schemas/Asset'
        deposit_amount:
          type: string
          description: Amount to deposit, as a decimal string.
          example: '4.8'
        deposit_address:
          type: string
          description: Address to which funds will be deposited.
        deposit_chain:
          type: string
          description: Network on which the deposit will be made (e.g., base, ethereum).
          example: base
    Amount:
      type: string
      description: A decimal amount string.
    Limits:
      type: object
      properties:
        min:
          type: string
          description: Minimum amount as a decimal string.
        max:
          type: string
          description: Maximum amount as a decimal string.
    Token:
      type: string
      description: Token identifier in the format "chain:address"
      pattern: ^[a-z]+:0x[a-fA-F0-9]+$
      example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    ChangeAmount:
      type: object
      required:
        - account
        - resource
        - amount
      properties:
        account:
          type: string
          enum:
            - USER
            - DEST
            - HALLIDAY
            - SPW
            - REV_SHARE
            - BRIDGE
        resource:
          $ref: '#/components/schemas/Resource'
        amount:
          $ref: '#/components/schemas/Amount'
        tx_id:
          type: string
          description: Blockchain transaction hash associated with this change.
    Resource:
      type: object
      required:
        - asset
        - property
      properties:
        asset:
          type: string
        property:
          type: string
          enum:
            - APPROVAL
            - BALANCE
            - SIDE_EFFECT
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY

````