Start a card purchase

Starts a card payment for a buyer who has already been quoted. Returns either a purchase to redirect into, or a signal that identity verification is not finished yet - handle both shapes.

Identity verification happens in the on-ramp’s own flow, not ours. Get an access token from /card/kyc-token and mount their widget; we never see the buyer’s documents.

Request

string

required

The buyer’s email. This is the key the on-ramp uses to identify them across the purchase and its verification.

string

required

The EVM address the crypto is delivered to. In the non-custodial flow this is the buyer’s own wallet.

string

required

ISO 4217 code of the currency being charged (e.g. "EUR").

string

required

Total to charge, as a decimal string, matching what was quoted.

object

required

Card billing address. Required by the on-ramp before a purchase can proceed.

Show billingAddress

string

required

ISO 3166-1 alpha-2 country code.

string

required

string

required

string

required

string

required

Buyer’s date of birth, as required by the on-ramp’s compliance checks.

Response

Two shapes. Branch on status.

Verification still pending

string

"pending" - the buyer must finish identity verification before a purchase can start.

string

incomplete, pending (submitted, under review) or unknown. Keep polling on pending; it is not terminal.

Ready to pay

string

Your reference for this purchase. Pass it to /card/status.

string

The hosted card page. Send the buyer here to enter card details, Apple Pay, and pass 3DS. Payment never touches your page or ours.

curl -X POST "$RHEON_API/card/purchase" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "address": "0x2222222222222222222222222222222222222222",
    "fiatCurrency": "EUR",
    "fiatAmount": "100.00",
    "billingAddress": {
      "countryCode": "PL",
      "streetLine1": "Main Street 1",
      "city": "Warsaw",
      "zipCode": "00-001"
    },
    "birthday": "1990-01-01"
  }'

{
  "transactionId": "1022fe1d470484769",
  "redirectUrl": "https://exchange.mercuryo.io/?widget_id=..."
}

{
  "status": "pending",
  "kycStatus": "pending"
}

Errors

HTTP	`code`	When
400	`invalid_request`	Missing or malformed email, address, amount, billing address or birthday.
429	`rate_limited`	Over the rate limit (5 requests / 10s / IP).
502	`upstream_error`	The on-ramp is unavailable.
500	`internal`	Unexpected server error.

Crypto deposits

Card payments

Bank transfers

Start a card purchase

Request

Response

Verification still pending

Ready to pay

Errors

​Request

​Response

​Verification still pending

​Ready to pay

​Errors

Request

Response

Verification still pending

Ready to pay

Errors