Halliday Payments API

openapi: 3.2.0
info:
  title: Halliday API V2 Payments API
  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: Payments
  description: Core payment operations including quotes, confirmation, and status tracking
paths:
  /payments:
    get:
      summary: Get payment status
      description: 'Get the current status of a payment, including progress through onramp/swap/offramp stages.

        '
      operationId: getPaymentStatus
      tags:
      - Payments
      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
  /payments/history:
    get:
      summary: Get payment history
      description: 'Retrieve a paginated list of payment statuses filtered by owner.

        Returns an array of payment status objects and a pagination key for fetching the next page.

        '
      operationId: getPaymentHistory
      tags:
      - Payments
      parameters:
      - name: owner_address
        in: query
        required: false
        description: Owner address to filter payments by
        schema:
          type: string
      - name: pagination_key
        in: query
        required: false
        description: Pagination key from previous response to fetch next page
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return
        schema:
          type: number
      - name: id_query
        in: query
        required: false
        description: Filter payments by ID
        schema:
          type: string
      - name: dest_address
        in: query
        required: false
        description: Filter payments by destination address
        schema:
          type: string
      - name: category
        in: query
        required: false
        description: Filter payments by category
        schema:
          type: string
          enum:
          - ALL
          - NEW_OR_FUNDED
          default: NEW_OR_FUNDED
      - name: label
        in: query
        required: false
        description: Filter payments by label
        schema:
          type: string
      responses:
        '200':
          description: Payment history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - payment_statuses
                - next_pagination_key
                properties:
                  payment_statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentStatus'
                    description: Array of payment status objects
                  next_pagination_key:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Pagination key to fetch the next page of results
                    example: 42ff9b02-037f-4a90-87fb-a4d2ca128565_2025-11-12T22:08:52.517Z
              example:
                payment_statuses:
                - payment_id: <string>
                  status: COMPLETE
                  funded: true
                  created_at: '2025-11-12T20:15:30.000Z'
                  updated_at: '2025-11-12T20:25:45.000Z'
                  initiate_fund_by: '2025-11-12T21:15:30.000Z'
                  completed_at: '2025-11-12T20:25:45.000Z'
                  quoted:
                    output_amount:
                      asset: ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                      amount: '100.00'
                    fees:
                      total_fees: '3.50'
                      conversion_fees: '2.00'
                      network_fees: '1.00'
                      business_fees: '0.50'
                      currency_symbol: USD
                    onramp: stripe
                    onramp_method: credit_card
                    route:
                    - type: ONRAMP
                      net_effect:
                        consume:
                        - account: USER
                          resource:
                            asset: usd
                            property: BALANCE
                          amount:
                            amount: '103.50'
                        produce:
                        - account: PROCESSING_ADDRESS
                          resource:
                            asset: ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                            property: BALANCE
                          amount:
                            amount: '100.00'
                      pieces_info:
                      - type: onramp
                      step_index: 0
                  fulfilled:
                    output_amount:
                      asset: ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                      amount: '100.00'
                    fees:
                      total_fees: '3.50'
                      conversion_fees: '2.00'
                      network_fees: '1.00'
                      business_fees: '0.50'
                      currency_symbol: USD
                    onramp: stripe
                    onramp_method: credit_card
                    route:
                    - status: COMPLETE
                      type: ONRAMP
                      net_effect:
                        consume:
                        - account: USER
                          resource:
                            asset: usd
                            property: BALANCE
                          amount:
                            amount: '103.50'
                        produce:
                        - account: PROCESSING_ADDRESS
                          resource:
                            asset: ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
                            property: BALANCE
                          amount:
                            amount: '100.00'
                      pieces_info:
                      - type: onramp
                      step_index: 0
                      transaction_hash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
                  current_prices:
                    USD: '1.00'
                    ethereum:0x: '4200.00'
                    ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48: '1.00'
                  price_currency: USD
                  processing_addresses:
                  - chain: ethereum
                    address: 0xaddress...
                  owner_address: 0xowner...
                  destination_address: 0xdest...
                next_pagination_key: 42ff9b02-037f-4a90-87fb-a4d2ca128565_2025-11-12T22:08:52.517Z
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: 'Missing required parameter: owner_address'
        '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 access payment history for this address
  /payments/quotes:
    post:
      summary: Get payment quotes
      description: 'Request quotes for payments, supporting both fixed input and fixed output scenarios.

        Returns multiple quote options with pricing, fees, and routing information.


        This endpoint can also be used to requote from an existing payment by providing a payment_id.

        When requoting, input amounts are automatically derived from

        the payment''s current state, but you can optionally override the output asset.

        '
      operationId: getPaymentQuotes
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: Successful quote response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: amount
                  given: '5'
                  limits:
                    min: '10'
                    max: '10000'
                  source: moonpay
                  message: Amount too low. Minimum amount is $10 USD
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: API key missing or invalid
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Your API key does not have permission to create quotes
  /payments/confirm:
    post:
      summary: Confirm a payment
      description: 'Confirm a previously quoted payment and receive deposit instructions.

        Returns information on how to fund the payment (widget URL, contract address, etc.).


        If a payment output is >= $300 USD, the owner address will need to produce a EVM_OWNER

        signature. The response will include a USER_VERIFY next_instruction instead of funding

        details. In this case, prompt the user to sign the verification payloads via signTypedData,

        then submit a ContinueConfirmPaymentRequest to this same endpoint to complete confirmation.

        Once an owner address has produced an EVM_OWNER signature, subsequent payments with that

        owner address will not require the signature again.

        '
      operationId: confirmPayment
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - title: ConfirmPaymentRequest
                description: Initial payment confirmation request.
                type: object
                required:
                - payment_id
                - state_token
                - owner_address
                - destination_address
                properties:
                  payment_id:
                    type: string
                    description: ID of the payment from the quote to confirm
                  state_token:
                    type: string
                    description: State token from the quote response
                  owner_address:
                    type: string
                    description: Owner address for the payment. This is the address that the payment will be sent from.
                  destination_address:
                    type: string
                    description: Destination address for the payment. This is the address that the payment will be sent to.
                  client_redirect_url:
                    type: string
                    format: uri
                    description: Optional URL to redirect users to after an onramp flow completes.
                  owner_chain:
                    type: string
                    description: Optional chain for the owner address, needed when the owner operates on a specific chain.
                  client_redirect_after:
                    type: string
                    enum:
                    - COMPLETED
                    - FUNDED
                    default: COMPLETED
                    description: When to redirect the user to the client_redirect_url. COMPLETED waits for the full payment to finish, FUNDED redirects after funding is confirmed.
              - title: ContinueConfirmPaymentRequest
                description: 'Continuation request after a USER_VERIFY instruction. Submit the signed verification

                  payloads to complete the confirmation process.

                  '
                type: object
                required:
                - verification_token
                - signatures
                properties:
                  verification_token:
                    type: string
                    description: Opaque HMAC-signed token from the USER_VERIFY instruction. Pass back unmodified.
                  signatures:
                    type: array
                    description: User-signed payloads, one per verification entry from the USER_VERIFY instruction.
                    items:
                      type: object
                      required:
                      - reason
                      - signature_type
                      - signature
                      properties:
                        reason:
                          type: string
                          enum:
                          - EVM_OWNER
                          - EVM_WITHDRAWAL
                          description: Must match the reason from the corresponding verification entry.
                        signature_type:
                          type: string
                          enum:
                          - EIP712
                          description: Must match the signature_type from the corresponding verification entry.
                        signature:
                          type: string
                          description: The user's signature over the verification payload.
      responses:
        '200':
          description: Payment confirmed 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: Invalid state_token. The quote may have expired.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Authentication failed. Invalid API key.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Access denied. This payment belongs to a different account.
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Payment 'pay_xyz789' not found or has expired
  /payments/withdraw:
    post:
      summary: Return funds to owner or retry payment
      description: 'Request a withdrawal to return funds back to the owner or to a requoted processing address.

        This endpoint should be used when a payment cannot be completed and funds need to be returned.

        '
      operationId: withdrawPayment
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawPaymentAuthorizationRequest'
      responses:
        '200':
          description: Withdrawal initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawPaymentAuthorizationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Missing field 'token_amounts'.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Invalid or missing API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: You are not authorized to withdraw funds from this payment
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Payment 'pay_def456' not found
  /payments/withdraw/confirm:
    post:
      summary: Confirm withdrawal request
      description: 'Submit and execute the signed withdrawal request to return funds back to the owner or to a requoted processing address.

        '
      operationId: withdrawPaymentConfirm
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawPaymentRequest'
      responses:
        '200':
          description: Withdrawal executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawPaymentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Invalid request body
        '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 are not authorized to withdraw funds from this payment
  /payments/balances:
    post:
      summary: Get wallet balances
      description: 'Retrieve balances for the wallets associated with a payment. You can optionally supply additional

        wallet and token pairs to check alongside the payment''s primary wallet.

        '
      operationId: getPaymentBalances
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestForPaymentBalances'
            example:
              payment_id: pay_abc123
              custom_queries:
              - address: '0xabc1234567890abcdef1234567890abcdef1234'
                token: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
              - address: '0xdef1234567890abcdef1234567890abcdef5678'
                token: arbitrum:0xfffFFFFFfFFfffFFfFffffFffFFfFFfFFfFFf
      responses:
        '200':
          description: Wallet balances retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentBalancesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Invalid wallet address format
        '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 query payment balances
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                - kind: other
                  message: Payment 'pay_abc123' not found
components:
  schemas:
    Quote:
      allOf:
      - $ref: '#/components/schemas/QuotedEntry'
      - type: object
        properties:
          payment_id:
            type: string
            description: Unique payment identifier
      required:
      - payment_id
    WithdrawPaymentAuthorizationRequest:
      type: object
      required:
      - payment_id
      - token_amounts
      - recipient_address
      properties:
        payment_id:
          type: string
          description: ID of the payment to withdraw
        token_amounts:
          type: array
          items:
            $ref: '#/components/schemas/TokenAmount'
          description: List of token amounts to withdraw back to the owner or to a requoted processing address
        recipient_address:
          type: string
          description: On-chain address to withdraw the funds to. The assets will go to the address on the same chain the assets are on.
        withdraw_account:
          type: string
          enum:
          - INTENT
          - SPW
          default: SPW
          description: Type of account to withdraw from.
    ProviderIssue:
      type: object
      required:
      - kind
      - message
      properties:
        kind:
          type: string
          enum:
          - provider
        message:
          type: string
    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'
    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
    FailureContent:
      type: object
      required:
      - service_ids
      - latency_seconds
      properties:
        service_ids:
          type: array
          description: Providers that failed to return quotes.
          items:
            type: string
        latency_seconds:
          type: number
          format: float
          description: Time taken for the failed quote attempt.
        issues:
          type: array
          description: Optional list of structured issues describing the failure.
          items:
            $ref: '#/components/schemas/Issue'
    EffectAmount:
      type: object
      required:
      - consume
      - produce
      properties:
        consume:
          type: array
          items:
            $ref: '#/components/schemas/ChangeAmount'
        produce:
          type: array
          items:
            $ref: '#/components/schemas/ChangeAmount'
    RequestForPaymentBalances:
      type: object
      properties:
        payment_id:
          type: string
          format: uuid
          description: Payment identifier whose associated wallets should be queried.
          example: 41b16a6f-704e-44ba-9964-2b66df8a73e8
        custom_queries:
          type: array
          description: Additional wallet and token combinations to query.
          items:
            type: object
            required:
            - address
            - token
            properties:
              address:
                type: string
                description: Wallet address to query.
                example: '0xabc1234567890abcdef1234567890abcdef1234'
              token:
                $ref: '#/components/schemas/Token'
                description: Token identifier to query at the wallet address.
                example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    Resource:
      type: object
      required:
      - asset
      - property
      properties:
        asset:
          type: string
        property:
          type: string
          enum:
          - APPROVAL
          - BALANCE
          - SIDE_EFFECT
    PieceInfo:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - user_fund
          - onramp
          - poll
          - bridge
          - rev_share
          - transfer_out
          - convert
          - custom_call
    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: '#/components/schemas/OnrampOrTransferInInstruction'
          TRANSFER_IN: '#/components/schemas/OnrampOrTransferInInstruction'
          USER_VERIFY: '#/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
    PaymentBalancesResult:
      type: object
      required:
      - address
      - token
      - account
      - value
      properties:
        address:
          type: string
          description: Wallet address that was queried.
          example: '0xabc1234567890abcdef1234567890abcdef1234'
        token:
          $ref: '#/components/schemas/Token'
          description: Token identifier that was queried.
          example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
        account:
          type: string
          description: Account type for the balance.
          enum:
          - INTENT
          - SPW
        value:
          oneOf:
          - type: object
            required:
            - kind
            - amount
            - withdrawal_fee
            properties:
              kind:
                type: string
                enum:
                - amount
              amount:
                type: string
                description: Balance amount as a decimal string.
              withdrawal_fee:
                type: string
                nullable: true
                description: Withdrawal fee amount, or null if not applicable.
          - type: object
            required:
            - kind
            properties:
              kind:
                type: string
                enum:
                - error
          discriminator:
            propertyName: kind
    Token:
      type: string
      description: Token identifier in the format "chain:address"
      pattern: ^[a-z]+:0x[a-fA-F0-9]+$
      example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    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:
  

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/halliday/refs/heads/main/openapi/halliday-payments-api-openapi.yml