> ## Documentation Index > Fetch the complete documentation index at: https://docs.hypermid.io/llms.txt > Use this file to discover all available pages before exploring further. # Read a payment session > The merchant view of a session: current status, amounts, settlement hashes and fee snapshot. Scoped to your partner account — another partner's session id returns 404, not 403. Polling this is a fallback, not the intended integration. Prefer the completion webhook; it fires as soon as funds land. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/payments/{id} openapi: 3.1.0 info: title: Hypermid API description: >- Price and execute cross-chain swaps, read reference data and payer balances, and quote the fiat on-ramp. Quotes return an executable `transactionRequest` your frontend submits directly, so Hypermid never custodies the funds. Payments — `checkout`, `deposit`, and `withdrawal` sessions — and payment-link management are available through these merchant REST endpoints and the [`@hypermid/sdk`](https://docs.hypermid.io/sdk/payments) package. Payer-facing routes are intentionally omitted. version: 0.2.0 contact: {} servers: - url: https://server.hypermid.io description: Production — live keys (sk_live_…) - url: https://server.hypermid.io description: Sandbox — test keys (sk_test_…), testnets only security: [] tags: - name: payments description: >- Create and read payment sessions, manage webhooks, and configure payout addresses with a secret partner key. - name: payment links description: >- Create, read, version, and revoke reusable checkout payment links with a secret partner key. - name: quote description: >- Route pricing for the orchestration product. Returns an executable `transactionRequest` your frontend submits directly, so Hypermid never custodies the funds. - name: status description: >- Resolve the state of a submitted swap or transfer. Two endpoints with different audiences — see each one's description before choosing. - name: catalog description: >- Reference data an integration needs to render a picker: supported chains and tokens, prices, routable connections, and fee configuration. A sandbox key sees only testnets here. - name: balances description: Read a payer wallet's token balances across supported chains. - name: onramp description: >- The fiat rail — card and bank payment for crypto, quoted and settled through our onramp partner. Requires per-partner onramp credentials on your account. - name: webhooks description: >- Events Hypermid sends TO you when a session completes. These are requests we make to your server, not endpoints you call. paths: /v1/payments/{id}: get: tags: - payments summary: Read a payment session description: >- The merchant view of a session: current status, amounts, settlement hashes and fee snapshot. Scoped to your partner account — another partner's session id returns 404, not 403. Polling this is a fallback, not the intended integration. Prefer the completion webhook; it fires as soon as funds land. operationId: PaymentController_getById parameters: - name: id required: true in: path schema: type: string responses: '200': description: Merchant payment-session view. content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/PaymentMerchantViewDto' '401': description: Missing, invalid, or non-secret partner key (`UNAUTHORIZED`). content: application/json: schema: $ref: '#/components/schemas/PaymentErrorResponseDto' '403': description: >- Key or operation forbidden (`FORBIDDEN` or `RECIPIENT_NOT_ALLOWLISTED`). content: application/json: schema: $ref: '#/components/schemas/PaymentErrorResponseDto' '404': description: >- Checkout, webhook, or configured capability not found (`PAYMENT_NOT_FOUND`, `NOT_FOUND`, or `NOT_CONFIGURED`). content: application/json: schema: $ref: '#/components/schemas/PaymentErrorResponseDto' '500': description: Unexpected server error (`INTERNAL_ERROR`). content: application/json: schema: $ref: '#/components/schemas/PaymentErrorResponseDto' security: - bearer: [] components: schemas: ApiEnvelope: type: object properties: traceId: type: string description: W3C trace id of the request — correlate with logs/traces in SigNoz. example: 4bf92f3577b34da6a3ce929d0e0e4736 code: type: string enum: - OK - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - PAYLOAD_TOO_LARGE - UNSUPPORTED_CHAIN - INTERNAL_ERROR - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - SERVICE_UNAVAILABLE - KILL_SWITCH_ACTIVE - CIRCUIT_BREAKER_OPEN - NO_QUOTE_AVAILABLE - QUOTE_STALE - SIMULATION_REVERTED - INVALID_PARAMS - AMOUNT_OUT_OF_BOUNDS - PAYOUT_TOKEN_NOT_ALLOWED - RECIPIENT_NOT_ALLOWLISTED - PAYMENT_EXPIRED - PAYMENT_NOT_FOUND - NOT_CONFIGURED - INSUFFICIENT_LIQUIDITY - ROUTE_TEMPORARILY_UNAVAILABLE - UNSUPPORTED_ROUTE - OVER_DELIVERY_CAP description: >- Domain error code. `OK` on success; non-OK values come with a non-null `error`. example: OK error: type: - string - 'null' description: Human-readable error message. `null` on success. example: null data: type: - object - 'null' description: Endpoint-specific payload. `null` on error. required: - traceId - code - error - data PaymentMerchantViewDto: type: object properties: id: type: string description: Session id. status: type: string description: Current lifecycle state of the session. mode: type: string description: 'Which product created it: `checkout`, `deposit` or `withdrawal`.' environment: type: string enum: - live - test example: live description: >- The environment the session was created in — matches the key that made it. `test` sessions only accept payment from testnet chains; `live` sessions only from mainnets. merchantName: type: string description: Your display name, shown to the payer on the payment page. destChain: type: number description: Chain id where the funds settle. destToken: type: string description: Destination token contract address on `destChain`. destAmount: type: string description: >- Amount to be delivered. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). `"0"` when open-sized — branch on `openSized` rather than on that sentinel. openSized: type: boolean description: >- True when the payer names the amount (an open deposit or withdrawal). Note the asymmetry with the completion webhook, which OMITS `destAmount` entirely for an open session rather than sending `"0"`. recipient: type: string description: Address that receives the funds. payChain: type: - number - 'null' description: Chain the payer chose to pay from. Null until they choose. payToken: type: - string - 'null' description: Token the payer chose to pay with. Null until they choose. rail: type: string description: >- Settlement rail this session pays over (contract call, deposit address, fiat). depositAddress: type: - string - 'null' description: >- Deposit address for transfer-settled rails. Null on rails that settle by contract call. depositMemo: type: - string - 'null' description: >- Memo/tag that MUST accompany a deposit on chains that require one. Funds sent without it may be unrecoverable — always render it beside the address. minAmount: type: - string - 'null' description: >- Smallest amount this session will accept. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). maxAmount: type: - string - 'null' description: >- Largest amount this session will accept. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). etaSeconds: type: - number - 'null' description: >- Estimated seconds to settle once payment is submitted. Indicative, not a guarantee. expiresAt: type: string format: date-time description: When the session stops accepting payment (ISO 8601). deadlineAt: type: - string - 'null' format: date-time description: Deadline for an in-flight payment to land, on rails that impose one. createdAt: type: string format: date-time description: When the session was created (ISO 8601). completedAt: type: - string - 'null' format: date-time description: When settlement completed. Null until it does. sourceLimits: type: object additionalProperties: true description: >- Per-source-chain min/max limits, keyed by chain. Use it to bound the payer's input before quoting. destDecimals: type: - number - 'null' description: >- Decimals of the destination token, for formatting `destAmount` for display. destSymbol: type: - string - 'null' description: Symbol of the destination token, for display. destPriceUsd: type: - number - 'null' description: >- Indicative USD price of the destination token. For display only — never settle against it. destPrice: description: >- Freshness-bounded decimal USD price. Additive replacement for destPriceUsd. anyOf: - allOf: - $ref: '#/components/schemas/IndicativeTokenPriceDto' - type: 'null' destAmountUsd: type: - number - 'null' description: Indicative USD value of `destAmount`. For display only. payTxHash: type: - string - 'null' description: Hash of the payer's outgoing transaction on the source chain. paidTxHash: type: - string - 'null' description: >- Hash of the settlement transaction on the destination chain. This is the one that proves delivery. paidAmount: type: - string - 'null' description: >- Amount actually delivered. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). Null until settled. crossChainEnabled: type: boolean description: >- Whether this session accepts payment from a chain other than the destination. nearEnabled: type: boolean description: >- Whether the intent-based deposit-address rail is offered — the payer sends funds to an address instead of signing a contract call. fiatEnabled: type: boolean description: >- Whether fiat (card/bank) payment is offered. False unless onramp credentials are configured on your account. fiatSupport: description: >- Rampnow's full live verdict. fiatEnabled remains as a compatibility boolean. allOf: - $ref: '#/components/schemas/FiatAssetSupportDto' fiatCapabilities: description: >- Rampnow's supported currencies and pay-in methods for this partner and session environment. allOf: - $ref: '#/components/schemas/FiatCapabilitiesDto' methodOrder: description: Payment methods in the order the hosted page presents them. type: array items: type: string connectPayTestEcosystems: description: Temporary partner-scoped connect-and-pay test ecosystems. type: array items: type: string deliveryGuarantee: type: string enum: - exact - atLeast description: >- Whether the recipient receives EXACTLY `destAmount` (`exact`) or at least it (`atLeast`). Drives the 'you receive =/≥' copy, and determines whether an overshoot is possible. refundVaultChains: description: Chains on which a refund can be issued if settlement fails. type: array items: type: string depositTarget: type: - string - 'null' description: Resolved on-chain target for a deposit-address payment. minAmountIn: type: - string - 'null' description: >- Minimum the payer must SEND for the route to clear. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). minAmountOut: type: - string - 'null' description: >- Minimum guaranteed to ARRIVE after slippage. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). depositedAmount: type: - string - 'null' description: >- Amount observed at the deposit address so far. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). refundedAmount: type: - string - 'null' description: >- Amount refunded, if any. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). refundReason: type: - string - 'null' description: Why a refund was issued. Null when none was. processingStartedAt: type: - string - 'null' format: date-time description: When settlement began — payment seen, delivery not yet confirmed. settlementStatus: type: string description: >- Coarse settlement phase, for driving a progress UI without interpreting `status`. serverNow: type: string format: date-time description: >- Our clock at response time. Compare countdowns against this rather than the client's clock, which may be wrong. orderId: type: string description: >- Your own reference, supplied at creation. Also the idempotency key for session creation. metadata: type: - object - 'null' additionalProperties: true description: >- Arbitrary JSON you attached at creation. Returned untouched; we never interpret it. paidAmountInternal: type: - string - 'null' description: >- Internal settled amount before display rounding. Decimal string in the token's smallest unit (never a JSON number — parse with a bigint). payerAddress: type: - string - 'null' description: Address the payer paid from, once known. successUrl: type: - string - 'null' description: Where the hosted page sends the payer after success. cancelUrl: type: - string - 'null' description: Where the hosted page sends the payer if they cancel. swapRef: type: - string - 'null' description: Internal cross-chain settlement reference, for support escalation. txHash: type: - string - 'null' description: >- Alias of `paidTxHash` — the settlement transaction. This is the name the `*.completed` webhook uses for the same value (`data.txHash`), so a handler that reconciles a delivery against a session read can compare one field rather than mapping between two spellings. webhookDelivered: type: boolean description: >- Whether the completion webhook has been delivered and acknowledged. False with a completed session means delivery is still being retried. required: - id - status - mode - environment - merchantName - destChain - destToken - destAmount - openSized - recipient - payChain - payToken - rail - depositAddress - depositMemo - minAmount - maxAmount - etaSeconds - expiresAt - deadlineAt - createdAt - completedAt - sourceLimits - destDecimals - destSymbol - destPriceUsd - destPrice - destAmountUsd - payTxHash - paidTxHash - paidAmount - crossChainEnabled - nearEnabled - fiatEnabled - fiatSupport - fiatCapabilities - methodOrder - connectPayTestEcosystems - deliveryGuarantee - refundVaultChains - depositTarget - minAmountIn - minAmountOut - depositedAmount - refundedAmount - refundReason - processingStartedAt - settlementStatus - serverNow - orderId - metadata - paidAmountInternal - payerAddress - successUrl - cancelUrl - swapRef - txHash - webhookDelivered PaymentErrorResponseDto: type: object properties: traceId: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 description: >- Correlation id for this request. Quote it in any support message — it is how we find your call in our logs. code: type: string enum: - OK - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - PAYLOAD_TOO_LARGE - UNSUPPORTED_CHAIN - INTERNAL_ERROR - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - SERVICE_UNAVAILABLE - KILL_SWITCH_ACTIVE - CIRCUIT_BREAKER_OPEN - NO_QUOTE_AVAILABLE - QUOTE_STALE - SIMULATION_REVERTED - INVALID_PARAMS - AMOUNT_OUT_OF_BOUNDS - PAYOUT_TOKEN_NOT_ALLOWED - RECIPIENT_NOT_ALLOWLISTED - PAYMENT_EXPIRED - PAYMENT_NOT_FOUND - NOT_CONFIGURED - INSUFFICIENT_LIQUIDITY - ROUTE_TEMPORARILY_UNAVAILABLE - UNSUPPORTED_ROUTE - OVER_DELIVERY_CAP example: INVALID_PARAMS description: >- Stable machine-readable error code. Branch on this, not on `error`, whose wording may change. error: type: string example: orderId is required description: >- Human-readable explanation. For logs and developers — not intended to be shown to a payer verbatim. data: type: - object - 'null' example: null description: >- Always null on an error. Present so success and error envelopes have the same shape. required: - traceId - code - error - data IndicativeTokenPriceDto: type: object properties: usdPerToken: type: string description: Indicative USD price as a decimal string; never used for settlement. observedAt: type: string format: date-time description: When Hypermid refreshed the catalogue carrying this price. validUntil: type: string format: date-time description: After this instant the client must hide the USD conversion. required: - usdPerToken - observedAt - validUntil FiatAssetSupportDto: type: object properties: supported: type: boolean description: Whether Rampnow can currently buy the payout asset. reason: type: string enum: - chain-unmapped - asset-unlisted - direction-unsupported description: Provider-capability reason when unsupported. min: type: - string - 'null' description: Provider minimum in currency. max: type: - string - 'null' description: Provider maximum in currency. currency: type: - string - 'null' description: Currency that denominates min and max. required: - supported FiatCapabilitiesDto: type: object properties: status: type: string enum: - available - temporarily_unavailable - not_configured description: >- Whether capabilities were read successfully for this partner and session environment. currencies: description: Currencies with the pay-in methods available for each currency. type: array items: $ref: '#/components/schemas/FiatCurrencyCapabilityDto' required: - status - currencies FiatCurrencyCapabilityDto: type: object properties: code: type: string description: ISO 4217 fiat currency code. payinModes: description: Rampnow pay-in method codes supported for this currency. type: array items: type: string required: - code - payinModes securitySchemes: bearer: scheme: bearer bearerFormat: API key type: http description: >- Secret partner API key (`sk_live_…` or `sk_test_…`). Required to create or manage payment sessions. Server-side only — it can move money, so it must never reach a browser bundle. The key's prefix also selects the environment: `sk_test_` is confined to testnets. ````