Skip to main content
POST
/
api
/
v1
/
payments
/
payment-addresses
Allocate a payment address
curl --request POST \
  --url https://api-beta.pepay.io/api/v1/payments/payment-addresses \
  --header 'Content-Type: application/json' \
  --header 'x-session-token: <api-key>' \
  --header 'x-signature: <api-key>' \
  --data '
{
  "network": "ethereum",
  "tokenId": 1
}
'
{
  "temp_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "network": "ethereum",
  "supported_token_id": 1,
  "estimated_token_amount": "100.50",
  "exchange_rate": "0.9950",
  "usd_amount": 100,
  "quote_last_updated_at": "2025-12-12T12:00:00.000Z",
  "quote_valid_until": "2025-12-12T12:05:00.000Z",
  "quote_expires_in_seconds": 300,
  "ws_connection": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "endpoint": "/ws/payment"
  }
}

Authorizations

​
x-session-token
string
header
required

Payment session token (opaque). Returned when creating an invoice; send on every request.

​
x-signature
string
header
required

Payment session signature in the format signature_hash.timestamp_ms (returned with the invoice/session).

Body

application/json
​
network
string
required

Network identifier from /api/v1/payments/available-tokens (lowercase).

​
tokenId
integer
required

Token identifier from /api/v1/payments/available-tokens.

Response

Address allocated

​
success
boolean

Always true; quote availability is communicated via quote_status.

​
quote_status
enum<string>

Quote window status for this token selection.

Available options:
available,
unavailable,
expired
​
status_code
enum<string>

Machine-readable status.

Available options:
ok,
quote_unavailable,
quote_expired,
settlement_unavailable
​
message
string | null

Human-readable status message.

​
temp_address
string

Generated payment address

​
network
string

Network name (lowercase)

​
supported_token_id
integer

Token id that was selected.

​
estimated_token_amount
string

Amount to pay in token (includes buffer)

​
exchange_rate
string

USD to token exchange rate

​
usd_amount
number

Invoice amount in USD

​
quote_last_updated_at
string<date-time> | null

Server timestamp the current quote was persisted

​
quote_valid_until
string<date-time> | null

Server timestamp when the quote expires (5 minutes)

​
quote_expires_in_seconds
integer | null

Seconds remaining until quote_valid_until (computed at send time).

​
retryable
boolean | null

True when the backend recommends retrying to mint/refresh a quote.

​
retry_after_seconds
integer | null

Suggested backoff in seconds when retryable.

​
ws_connection
object