Schema Reference

Quick reference for all DogeConnect JSON schemas.

All 8-DP string fields are decimal strings with up to 8 decimal places representing Dogecoin amounts. See Payment Envelope for details.

Optional String Fields

• Payment Relays SHOULD include optional string fields as empty strings "" when no value is available, rather than omitting them.
• Wallets MUST treat a missing field and an empty string "" identically (i.e. as not provided).
• Wallets SHOULD provide sensible placeholders for missing display fields (e.g. icons).

Enums

EnvelopeType

ItemType

PaymentStatus

ErrorCode

Connect Envelope

Signed wrapper around a Connect Payment payload.

{
	"version": "1.0",             // MUST be 1.0
	"payload": "YTc2ZDc2MzEyZ..", // Base64-encoded JSON payload (e.g. Connect Payment)
	"pubkey": "c8a6927d0a004..",  // Relay Public Key, BIP-340 Schnorr X-only (32 bytes)
	"sig": "202d831c6437c.."     // Payload Signature, BIP-340 Schnorr (64 bytes)
}

Connect Payment

The decoded payload inside a Connect Envelope.

{
	"type": "payment",                       // MUST be "payment"
	"id": "PID-123",                         // Relay-unique Payment ID
	"issued": "2006-01-02T15:04:05-07:00",   // RFC 3339 Timestamp
	"timeout": 60,                           // Timeout in seconds, do not pay after this time
	"relay": "https://relay.example.com/..", // Payment Relay to submit payment tx
	"relay_token": "eyJpZCI6IlBJRC...",      // Opaque relay-generated token (optional)
	"fee_per_kb": "0.01001386",              // Min fee per 1000 bytes the relay will accept, 8-DP string
	"max_size": 10000,                       // Max tx size in bytes the relay will accept
	"vendor_icon": "https://example.com/..", // Vendor icon URL, JPG or PNG (optional)
	"vendor_name": "Vendor Co",              // Vendor display name
	"vendor_address": "123 Example St",      // Vendor business address (optional)
	"vendor_url": "https://example.com",     // Vendor website URL (optional)
	"vendor_order_url": "https://example.com/..", // URL to view order on vendor's site (optional)
	"vendor_order_id": "INV-2025-0042",      // Vendor's unique order identifier (optional)
	"order_reference": "A073",               // Short customer-facing order identifier (optional)
	"note": "Thank you for your order!",     // Free-text note from vendor to customer (optional)
	"total": "41.9395",                      // Total including fees and taxes, 8-DP string
	"fees": "1.0",                           // Fees subtotal, 8-DP string (optional)
	"taxes": "1.9495",                       // Taxes subtotal, 8-DP string (optional)
	"fiat_total": "5.00",                    // Total in fiat currency, decimal string (optional)
	"fiat_tax": "0.23",                      // Taxes in fiat currency, decimal string (optional)
	"fiat_currency": "USD",                  // ISO 4217 currency code (required with fiat_total/fiat_tax)
	"items": [],                             // List of line items to display (Connect Items)
	"outputs": []                            // List of outputs to pay (Connect Outputs)
}

Connect Item

A line item within a Connect Payment.

{
	"type": "item",                           // item, tax, fee, shipping, discount, donation, signing
	"id": "SK-101",                           // unique item ID or SKU
	"icon": "https://example.com/itm/ic.png", // icon URL, JPG or PNG (optional)
	"name": "Doge Plushie",                   // name to display
	"desc": "One doge plushie in a soft bag", // item description to display (optional)
	"count": 1,                               // number of units >= 1
	"unit": "38.99",                          // unit price, 8-DP string
	"total": "38.99",                         // count x unit, 8-DP string
	"tax": "1.9495"                           // tax on this item, 8-DP string (optional)
}

Connect Output

A transaction output the wallet must pay.

P2PKH output (type defaults to "p2pkh" if omitted):

{
	"type": "p2pkh",                                 // optional, default "p2pkh"
	"address": "DQ6dt7wCjLDxtdSwCYSAMFHwrD5Q1xybmL", // Dogecoin Address
	"amount": "1.0"                                   // Amount, 8-DP string
}

Data-only output (type is "data"):

{
	"type": "data",           // OP_RETURN output
	"data": "48656c6c6f"     // Hex-encoded OP_RETURN payload
}

The type field defaults to "p2pkh" when omitted, for backwards compatibility.

For "p2pkh" outputs, address and amount are required.

For "data" outputs, data is required and address and amount MUST be omitted. The wallet MUST create an OP_RETURN output carrying the decoded bytes. The data value MUST be a valid hex string (even number of hex characters) and the decoded payload MUST NOT exceed 80 bytes, which is the maximum OP_RETURN data size.

Payment Submission

The wallet’s submission to the relay’s pay endpoint in response to a Connect Payment.

{
	"id": "PID-123",                    // Relay-unique Payment ID from Connect Payment
	"tx": "489c47f8a3ba3293737..",      // Hex-encoded signed dogecoin transaction
	"refund": "DKY8dUTQthSX..",        // Dogecoin address for refunds (recommended)
	"relay_token": "eyJpZCI6IlBJRC..." // Relay token from Connect Payment, if present
}

Payment Status

The relay’s response from both the pay and status endpoints.

{
	"id": "PID-123",
	"status": "accepted",
	"txid": "a1b2c3d4e5..",
	"required": 5,
	"confirmed": 0,
	"due_sec": 300
}

{
	"id": "PID-123",
	"status": "declined",
	"reason": "Transaction deemed too risky"
}

Status Query

Query the current status of a payment, submitted to the relay’s status endpoint.

{
	"id": "PID-123" // Relay-unique Payment ID from Connect Payment
}

Error Response

Returned by the relay when a request fails.

{
	"error": "invalid_tx",
	"message": "Transaction outputs do not match requested amounts"
}