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

# Start a card purchase

> Checks the buyer's verification first. Not green: answers `status: pending` and no money moves - poll and retry. Green: sets the buyer's profile and creates the purchase, answering the provider-hosted card page to redirect to. Card details are entered there, never on Rheon.

<Note>**Provider sandbox on this deployment.** Our backend targets the card provider's sandbox: no card is charged and no real transfer settles. Known limits: a purchase never reaches `completed` (it stops at `processing`), the settlement asset is the sandbox's, not production's (read `cryptoCurrency` from GET /v1/config), and the EUR window is unpublished (GET /v1/card/limits says `window: unpublished`). Every response says which environment answered in its `environment` field.</Note>


## OpenAPI

````yaml https://backend.rheon.io/openapi.json post /v1/card/purchase
openapi: 3.1.0
info:
  title: Rheon partner API
  version: 1.0.0
  description: >-
    The /v1 surface a partner's backend calls with an API key.


    **Authentication.** Every route takes `Authorization: Bearer <key>`. One
    kind of key: it carries its permissions and limits, and works from your
    server, a page, or this playground alike - where it is called from is not
    checked. Treat it as a secret all the same: anyone holding it acts under its
    permissions until it is rotated.


    **Rate limit.** Counted per key, at the requests-per-second rate configured
    on the key - never per IP, so your users do not throttle each other. Over
    it: `429 rate_limited`.


    **Amounts.** Token amounts are decimal strings in the token's smallest unit;
    fiat amounts are decimal strings in major units. Never JSON numbers.


    **Errors.** One envelope everywhere: `{ error: { code, message } }`, with
    `fields` added on bank refusals that named a field. A body that is not valid
    JSON answers `400 invalid_request`; an endpoint that does not exist answers
    `404 not_found`; a deployment with no partner keys configured answers `404
    not_configured` for all of /v1.


    **Environment.** Every response carries `environment` as its first field:
    `sandbox` or `production`, derived from the upstreams this deployment is
    configured against (never a flag). Read it off any response you paste into a
    ticket. In `sandbox` no real money moves and the card corridor is the
    provider's sandbox asset, which differs from production - read it from GET
    /v1/config, not from these docs.


    **Card corridor.** The asset and chain a card purchase settles as are fixed
    per deployment, not chosen per request. GET /v1/config reports the one
    actually configured.
servers:
  - url: https://api.rheon.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Configuration
  - name: Crypto deposits
  - name: Orders
  - name: Cards
  - name: Bank transfers
  - name: Virtual accounts
  - name: Reference
  - name: Sandbox only
paths:
  /v1/card/purchase:
    post:
      tags:
        - Cards
      summary: Start a card purchase
      description: >-
        Checks the buyer's verification first. Not green: answers `status:
        pending` and no money moves - poll and retry. Green: sets the buyer's
        profile and creates the purchase, answering the provider-hosted card
        page to redirect to. Card details are entered there, never on Rheon.
      operationId: cardPurchase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardPurchaseRequest'
      responses:
        '200':
          description: Ready to pay, or verification still pending.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardPurchaseResponse'
        '400':
          description: >-
            Cannot start this.


            - `invalid_request`: email not an email, address not an EVM address,
            fiatCurrency unsupported, fiatAmount not a positive decimal string,
            a billingAddress field empty, countryCode not alpha-2, birthday not
            YYYY-MM-DD.

            - `<provider code>`: The card provider refused (4xx); its code is
            passed through.
          x-error-codes:
            - invalid_request
            - <provider code>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: >-
            No usable API key.


            - `unauthorized`: Missing, malformed or unknown key. One
            undifferentiated answer on purpose.
          x-error-codes:
            - unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            Refused by permission.


            - `permission_denied`: The key does not carry the `cards`
            permission.
          x-error-codes:
            - permission_denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: >-
            Over this key's rate.


            - `rate_limited`: More requests per second than the key is
            configured for. Counted PER KEY (all your users share one bucket),
            never per IP.
          x-error-codes:
            - rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: >-
            Our fault.


            - `internal`: Unexpected server error. Detail is in our logs, never
            on the wire.
          x-error-codes:
            - internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: >-
            The provider behind this route is unavailable.


            - `upstream_error`: The payment provider answered a 5xx or did not
            answer.
          x-error-codes:
            - upstream_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - bearerAuth: []
components:
  schemas:
    CardPurchaseRequest:
      type: object
      properties:
        email:
          type: string
          pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
          description: Buyer email from the card form.
          example: buyer@example.com
        address:
          $ref: '#/components/schemas/EvmAddress'
          description: The user's EVM wallet - the non-custodial destination.
        fiatCurrency:
          $ref: '#/components/schemas/IsoCurrency'
          description: >-
            ISO 4217 code to charge in. Must be one of the deployment's
            supported fiat currencies (see GET /v1/card/currencies); others are
            refused.
        fiatAmount:
          $ref: '#/components/schemas/DecimalMajorUnits'
          description: Fiat to spend, decimal string in major units, greater than zero.
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
        birthday:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Date of birth, ISO YYYY-MM-DD.
          example: '1990-01-31'
        returnUrl:
          description: Where the hosted card page sends the user afterwards.
          example: https://example.com/return
          type: string
      required:
        - email
        - address
        - fiatCurrency
        - fiatAmount
        - billingAddress
        - birthday
      description: >-
        Asset and chain come from the deployment's fixed corridor; there is no
        field to choose them.
    CardPurchaseResponse:
      anyOf:
        - $ref: '#/components/schemas/CardPurchaseReady'
        - $ref: '#/components/schemas/CardPurchasePending'
    ErrorEnvelope:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Machine-readable error code. Branch on this, never on the
                message.
              example: invalid_request
            message:
              type: string
              description: Human-readable explanation. Wording may change.
              example: amount must be a decimal string of the token's smallest unit.
            fields:
              description: >-
                Per-field complaints from the bank provider, when it named the
                field it refused (bank routes only). Field names, never values.
              example:
                applicantInfo.nationality: iso3166_1_alpha2
              type: object
              propertyNames:
                type: string
              additionalProperties:
                type: string
          required:
            - code
            - message
          additionalProperties: false
      required:
        - environment
        - error
      additionalProperties: false
      description: The one error shape this API produces.
    EvmAddress:
      type: string
      pattern: ^0x[0-9a-fA-F]{40}$
      description: >-
        EVM address: 0x followed by 40 hex characters. Checksum casing is not
        required.
      example: '0x1111111111111111111111111111111111111111'
    IsoCurrency:
      type: string
      pattern: ^[A-Za-z]{3}$
      description: ISO 4217 currency code, three letters (case-insensitive on input).
      example: EUR
    DecimalMajorUnits:
      type: string
      pattern: ^\d+(\.\d+)?$
      description: >-
        Decimal string in the currency's major unit, e.g. "100" or "25.50".
        Never a JSON number.
      example: '100'
    BillingAddress:
      type: object
      properties:
        countryCode:
          $ref: '#/components/schemas/IsoCountry'
          description: ISO 3166-1 alpha-2 country code.
        streetLine1:
          type: string
          minLength: 1
          example: Main Street 1
        streetLine2:
          type: string
          minLength: 1
          description: Second address line. Required, non-empty (the provider requires it).
          example: Apt 2
        city:
          type: string
          minLength: 1
          example: Berlin
        zipCode:
          type: string
          minLength: 1
          example: '10115'
        stateCode:
          type: string
          minLength: 1
          description: >-
            State or region code; a non-empty string even for stateless
            countries.
          example: BE
      required:
        - countryCode
        - streetLine1
        - streetLine2
        - city
        - zipCode
        - stateCode
    CardPurchaseReady:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        status:
          type: string
          const: ready
        redirectUrl:
          type: string
          description: Provider-hosted card entry page. Redirect the user here.
        transactionId:
          type: string
          description: Provider transaction id to poll status with.
      required:
        - environment
        - status
        - redirectUrl
        - transactionId
      additionalProperties: false
    CardPurchasePending:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        status:
          type: string
          const: pending
        kycStatus:
          $ref: '#/components/schemas/CardKycStatus'
      required:
        - environment
        - status
        - kycStatus
      additionalProperties: false
      description: KYC is not green yet. No money moved; run the WebSDK / poll and retry.
    Environment:
      type: string
      enum:
        - sandbox
        - production
      description: >-
        Which environment answered. `sandbox`: at least one money upstream is
        the provider's sandbox - no real money moves there, and the card
        corridor is the sandbox's asset (read GET /v1/config), not the
        documented production one. `production`: every configured upstream is
        real. Derived from the configured upstream hosts at boot, never a flag.
      example: sandbox
    IsoCountry:
      type: string
      pattern: ^[A-Za-z]{2}$
      description: >-
        ISO 3166-1 alpha-2 country code, two letters (case-insensitive on input;
        sent upstream upper-cased).
      example: DE
    CardKycStatus:
      type: string
      enum:
        - complete
        - incomplete
        - pending
        - unknown
      description: Only `complete` unblocks a purchase; anything else means keep polling.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key, issued by us and shown once at creation.

````