Skip to content

Commit 388ad25

Browse files
raffecatraffecat
committed
Payment Relay
1 parent 2e3900c commit 388ad25

File tree

3 files changed

+98
-4
lines changed

3 files changed

+98
-4
lines changed

‎src/getting_started/introduction.md

+2
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ DogeConnect is a payment protocol for transmitting a detail-rich _Payment Reques
44
_Vendor_ to a _Client Wallet_ and receiving a _Payment Response_ containing a signed
55
transaction, which is validated and relayed to the network by a _Payment Relay_.
66

7+
**Note: this specification is not yet final; please provide feedback.**
8+
79
DogeConnect comprises:
810
* a _Payment QR Code_ specification,
911
* a _Payment Envelope_ JSON schema,

‎src/payment_envelope/envelope.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55
```json
66
{
77
"version": "1.0", // MUST be 1.0
8-
"payload": "YTc2ZDc2MzEyZ..", // Base64-encoded JSON payload (e.g. ConnectPayment)
9-
"pubkey": "c8a6927d0a004..", // Gateway Public Key, BIP-340 Schnorr X-only (32 bytes)
8+
"payload": "YTc2ZDc2MzEyZ..", // Base64-encoded JSON payload (e.g. Connect Payment)
9+
"pubkey": "c8a6927d0a004..", // Relay Public Key, BIP-340 Schnorr X-only (32 bytes)
1010
"sig": "202d831c6437c..", // Payload Signature, BIP-340 Schnorr (64 bytes)
1111
}
1212
```
@@ -16,7 +16,7 @@
1616
```json
1717
{
1818
"type": "payment", // MUST be "payment"
19-
"id": "xyz123", // Gateway unique payment ID
19+
"id": "PID-123", // Relay-unique Payment ID
2020
"issued": "2006-01-02T15:04:05-07:00", // RFC 3339 Timestamp
2121
"timeout": 60, // Timeout in seconds
2222
"relay": "https://example.com/..", // Payment Relay to submit payment tx
@@ -75,7 +75,7 @@ Use the following steps to decode and verify the payload.
7575
7. Parse the JSON payload bytes using a standard JSON parser.
7676
8. Check the `timeout` field: do not submit a payment transaction after the time `issued` + `timeout`.
7777
9. Display the payment information and ask the user to confirm payment.
78-
10. Create and sign a payment transaction and submit it to the `relay` URL.
78+
10. Create and sign a payment transaction and submit it to the [Payment Relay](../payment_relay/relay.md).
7979

8080
The goals of the above process are to verify that the _Payment Envelope_ is cryptographically
8181
signed by the _Payment Relay's_ private key, i.e. the envelope was created by the _Payment Relay_.

‎src/payment_relay/relay.md

+92
Original file line numberDiff line numberDiff line change
@@ -1 +1,93 @@
11
# Payment Relay
2+
3+
The _Payment Relay_ base URL is found in the `relay` field of _Connect Payment_.
4+
5+
The following Web API must be implemented by a _Payment Relay_:
6+
7+
| URL | Method | Post Data | Response | Function |
8+
|--------------------|--------|-------------------------|-----------------------|--------------------------------|
9+
| _relay_/**pay** | POST | _Payment Response_ | _Payment Reply_ | Submit payment tx |
10+
| _relay_/**status** | POST | _Status Query_ | _Status Reply_ | Query payment status |
11+
12+
Requests and responses are JSON payloads; JSON _must_ be UTF-8 encoded.
13+
14+
All responses must include a `Cache-Control: no-store` header, to avoid
15+
leaking payment information into caches. Both endpoints additionally use
16+
the _POST_ method to avoid caching edge-cases (e.g. error responses.)
17+
18+
19+
### Payment Response
20+
21+
This is the wallet's _response_ to the original _Payment Request_.
22+
23+
```json
24+
{
25+
"id": "PID-123", // Relay-unique Payment ID from Connect Payment
26+
"tx": "489c47f8a3ba3293737a.." // hex-encoded signed dogecoin transaction
27+
}
28+
```
29+
30+
31+
### Payment Reply
32+
33+
This is the _Payment Relay's_ reply from the `pay` URL.
34+
35+
```json
36+
{
37+
"id": "PID-123", // Relay-unique Payment ID from Connect Payment
38+
"status": "accepted", // One of: accepted | declined
39+
"reason": "", // Reason for decline (message, optional)
40+
"required": 5, // number of block confirmations required (risk analysis)
41+
"confirmed": 0, // current number of block confirmations on-chain
42+
"due_sec": 300, // Estimated time in seconds until confirmed
43+
}
44+
```
45+
46+
If the transaction is malformed, or does not pay the requested amounts to
47+
the requested addresses, the POST will be rejected with a **400 Bad Request**
48+
http response. This represents a _programming error_ in the wallet.
49+
50+
Payments may also be rejected with a `declined` status, in the case that
51+
the _Vendor_ or their nominated _Relay_ believes the transaction is too
52+
risky. This represents a _customer-specific_ problem.
53+
54+
The final three fields, `required`, `confirmed` and `due_sec` are in common
55+
with the _Status Reply_ below.
56+
57+
58+
### Status Query
59+
60+
This allows the wallet to query the current status of a payment.
61+
62+
```json
63+
{
64+
"id": "PID-123" // Relay-unique Payment ID from Connect Payment
65+
}
66+
```
67+
68+
69+
### Status Reply
70+
71+
This is the _Payment Relay's_ reply from the `status` URL.
72+
73+
```json
74+
{
75+
"id": "PID-123", // Relay-unique Payment ID from Connect Payment
76+
"status": "accepted", // unpaid | accepted | confirmed
77+
"required": 5, // number of block confirmations required
78+
"confirmed": 4, // current number of block confirmations on-chain
79+
"due_sec": 30, // Estimated time in seconds until confirmed
80+
}
81+
```
82+
83+
Payments transition from `unpaid` to `accepted` after the signed transaction
84+
is submitted to the `pay` endpoint (provided payment was accepted.)
85+
86+
After the required number of block confirmations have been seen on-chain,
87+
the payment status transitions to `confirmed`.
88+
89+
When the payment status is `confirmed`, the `confirmed` field is always greater
90+
or equal to `required`, and the `due_sec` field is alway zero.
91+
92+
Note: there are some edge-cases where the `confirmed` count can reduce,
93+
i.e. during a short-term blockchain fork.

0 commit comments

Comments
 (0)