Skip to main content

​
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`.
Deposits require the merchant to have deposits enabled. If deposits are disabled for your account, contact SpacePay support team.
curl -X POST https://api.spacepay.co.uk/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\"}"
  }'

{
  "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.co.uk/payment/4291f98b-d68c-4eb0-883e-6bc790a41c96",
  "secret": "payment_secret_key",
  "paymentId": "4291f98b-d68c-4eb0-883e-6bc790a41c96"
}

​
Request parameters

​
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.
​
amount
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.
​
currency
string
required
Payment currency. Supports USD.
​
orderId
string
required
Your order or reference id for reconciliation.
​
redirectUrl
string
URL to send the customer after the payment completes.
​
customMetadata
string
Optional metadata as a JSON string (passed through to redirects as configured).

​
Response fields

​
payment
object
required
Complete payment object including type (payment | deposit), status, quotes, and deposit address when applicable.
​
paymentUrl
string
Hosted payment URL for the customer.
​
paymentId
string
Payment id (same as payment.id).
​
secret
string
Payment secret — use with X-SpacePay-Payment-Secret on payment-secret endpoints (never treat this like your merchant secret key).

​
Error responses

{
  "error": {
    "type": "invalid_request_error",
    "message": "The amount must be greater than 0",
    "code": "invalid_amount",
    "param": "amount"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing X-SpacePay-Secret-Key header",
    "code": "invalid_api_key"
  }
}