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

# Create payment or deposit

> Create a fixed-amount payment or a flexible deposit using secret key authentication

# Create payment or deposit

Creates a **payment** (fixed fiat amount) or a **deposit** (customer chooses how much crypto to send). Both return a hosted flow URL, a `paymentId`, and a **payment secret**\`.

<Note>
  **Deposits** require the merchant to have deposits enabled. If deposits are
  disabled for your account, contact SpacePay support team.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.spacepay.solutions/v1/external/secretkey-auth/payments \
    -H "X-SpacePay-Secret-Key: sk_test_your_secret_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: unique-key-for-request" \
    -d '{
      "type": "payment",
      "orderId": "order_123",
      "amount": 250,
      "currency": "USD",
      "redirectUrl": "https://merchant.example.com/checkout/success",
      "customMetadata": "{\"cartId\":\"abc123\",\"promo\":\"SUMMER24\"}"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (201) theme={null}
  {
    "payment": {
      "id": "4291f98b-d68c-4eb0-883e-6bc790a41c96",
      "merchantId": "4e29f55d-d6a8-42d7-8230-cb8efeded39e",
      "merchantShortName": "Copycat Creations",
      "amountInCents": 250,
      "currency": "USD",
      "status": "pending",
      "depositAddress": {
        "id": "6c1c95e1-04f1-4881-b7cc-c2a529fbde76",
        "paymentId": "4291f98b-d68c-4eb0-883e-6bc790a41c96",
        "type": "EVM",
        "address": "0xa35e74109b7040d0ee74cb7cb71bae35a2981254",
        "createdAt": "2025-10-10T21:44:06.749Z"
      },
      "quotes": [
        {
          "id": "eb0e59b9-14d5-4324-a056-e87b74aa954f",
          "paymentId": "4291f98b-d68c-4eb0-883e-6bc790a41c96",
          "token": {
            "id": "f9d14525-367d-4e16-b247-8d4ed23f1413",
            "coingeckoApiId": "ethereum",
            "chain": {
              "chainId": 84532,
              "name": "Base Sepolia",
              "nativeSymbol": "ETH",
              "nativeDecimals": 18,
              "isEnabled": true
            },
            "symbol": "ETH",
            "contractAddress": "0x0000000000000000000000000000000000000000",
            "decimals": 18,
            "type": "volatile",
            "assetType": "native",
            "status": "active"
          },
          "chainId": 84532,
          "expectedAmountAsset": "668082370801162",
          "rateUsdAsset": "3742.05353900",
          "expiresAt": "2025-10-10T21:54:06.796Z",
          "status": "active",
          "createdAt": "2025-10-10T21:44:06.794Z"
        }
      ],
      "receipt": null,
      "orderId": "order_123",
      "redirectUrl": "https://merchant.example.com/checkout/success",
      "createdAt": "2025-10-10T21:44:06.733Z"
    },
    "paymentUrl": "https://pay.spacepay.solutions/payment/4291f98b-d68c-4eb0-883e-6bc790a41c96",
    "secret": "payment_secret_key",
    "paymentId": "4291f98b-d68c-4eb0-883e-6bc790a41c96"
  }
  ```
</ResponseExample>

## Request parameters

<ParamField body="type" type="string" default="payment">
  `payment` (default) or `deposit`. For `payment`, you must send `amount`. For
  `deposit`, `amount` is optional; the customer can send a variable amount
  on-chain.
</ParamField>

<ParamField body="amount" type="number">
  Amount in cents (for example, 250 = \$2.50). **Required** when `type` is
  `payment` or omitted (defaults to `payment`). **Optional** when `type` is
  `deposit`. Minimum: **250** cents, maximum: 100000000 cents.
</ParamField>

<ParamField body="currency" type="string" required>
  Payment currency. Supports `USD`.
</ParamField>

<ParamField body="orderId" type="string" required>
  Your order or reference id for reconciliation.
</ParamField>

<ParamField body="redirectUrl" type="string">
  URL to send the customer after the payment completes.
</ParamField>

<ParamField body="customMetadata" type="string">
  Optional metadata as a JSON string (passed through to redirects as
  configured).
</ParamField>

## Response fields

<ResponseField name="payment" type="object" required>
  Complete payment object including `type` (`payment` | `deposit`), status, quotes, and deposit address when applicable.

  <Expandable title="Payment properties">
    <ResponseField name="id" type="string">
      Unique payment identifier.
    </ResponseField>

    <ResponseField name="type" type="string">
      `payment` or `deposit`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current payment status: `pending`, `processing`, `completed`, `failed`, `expired`, or `cancelled`.
    </ResponseField>

    <ResponseField name="amountInCents" type="number">
      Payment amount in cents.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code.
    </ResponseField>

    <ResponseField name="depositAddress" type="object">
      Deposit address for crypto settlement.

      <Expandable title="Deposit address properties">
        <ResponseField name="address" type="string">
          Chain address where the customer sends funds.
        </ResponseField>

        <ResponseField name="type" type="string">
          Address type (for example `EVM`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="quotes" type="array">
      Active or initial cryptocurrency quotes.

      <Expandable title="Quote properties">
        <ResponseField name="token" type="object">
          Token metadata (symbol, decimals, contract, chain).
        </ResponseField>

        <ResponseField name="expectedAmountAsset" type="string">
          Expected amount in the token's smallest unit.
        </ResponseField>

        <ResponseField name="rateUsdAsset" type="string">
          Exchange rate from token to USD.
        </ResponseField>

        <ResponseField name="expiresAt" type="string">
          Quote expiry time.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="paymentUrl" type="string">
  Hosted payment URL for the customer.
</ResponseField>

<ResponseField name="paymentId" type="string">
  Payment id (same as `payment.id`).
</ResponseField>

<ResponseField name="secret" type="string">
  **Payment secret** — use with `X-SpacePay-Payment-Secret` on payment-secret
  endpoints (never treat this like your merchant secret key).
</ResponseField>

## Error responses

<ResponseExample>
  ```json Error Response (400) theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "message": "The amount must be greater than 0",
      "code": "invalid_amount",
      "param": "amount"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Error Response (401) theme={null}
  {
    "error": {
      "type": "authentication_error",
      "message": "Invalid or missing X-SpacePay-Secret-Key header",
      "code": "invalid_api_key"
    }
  }
  ```
</ResponseExample>