This repository has been archived by the owner on Mar 8, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 17
/
payid-protocol.txt
1344 lines (872 loc) · 47.8 KB
/
payid-protocol.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group A. Malhotra
Internet-Draft D. Schwartz
Intended status: Standards Track Ripple
Expires: January 18, 2021 July 17, 2020
PayID Protocol
draft-aanchal-payid-protocol-01
Abstract
This specification defines the PayID protocol - an application-layer
protocol, which can be used to interact with a PayID-enabled service
provider. The primary use case is to discover payment account
information along with optional metadata identified by a PayID
[PAYID-URI]. The protocol is based on HTTP transfer of PayID
protocol messages over a secure transport.
Feedback
This specification is a draft proposal, and is part of the PayID
Protocol [1] work. Feedback related to this specification should be
sent to [email protected] [2].
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 18, 2021.
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
Malhotra & Schwartz Expires January 18, 2021 [Page 1]
Internet-Draft PayID Protocol July 2020
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Design Goals . . . . . . . . . . . . . . . . . . . . . . 4
3. PayID Server Discovery . . . . . . . . . . . . . . . . . . . 5
4. JSON Format Design . . . . . . . . . . . . . . . . . . . . . 5
4.1. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 6
4.2. Media Type of the Payment Account(s) Information Resource 6
4.3. Response for application/* + json . . . . . . . . . . . . 6
4.3.1. payId . . . . . . . . . . . . . . . . . . . . . . . . 6
4.3.2. addresses . . . . . . . . . . . . . . . . . . . . . . 6
4.3.3. memo . . . . . . . . . . . . . . . . . . . . . . . . 7
4.3.4. identity . . . . . . . . . . . . . . . . . . . . . . 8
4.3.5. proofOfControlSignature . . . . . . . . . . . . . . . 8
4.4. Meaning of Media Type application/* + json . . . . . . . 8
5. Header Fields . . . . . . . . . . . . . . . . . . . . . . . . 9
5.1. Common Headers . . . . . . . . . . . . . . . . . . . . . 9
5.1.1. Header Content-Type . . . . . . . . . . . . . . . . . 9
5.1.2. Header Content-Length . . . . . . . . . . . . . . . . 10
5.1.3. Header PayID-version (TODO) . . . . . . . . . . . . . 10
5.2. Request Headers . . . . . . . . . . . . . . . . . . . . . 10
5.2.1. Header Accept . . . . . . . . . . . . . . . . . . . . 10
5.3. Response Headers . . . . . . . . . . . . . . . . . . . . 10
5.3.1. Header Cache-Control . . . . . . . . . . . . . . . . 10
6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Payload Extensibility . . . . . . . . . . . . . . . . . . 11
6.2. Header Field Extensibility . . . . . . . . . . . . . . . 11
6.3. Format Extensibility . . . . . . . . . . . . . . . . . . 11
7. Basic PayID Protocol . . . . . . . . . . . . . . . . . . . . 11
7.1. Step 1: HTTP Request to PayID URL using HTTP GET Method . 12
7.2. Step 2: Payment Account Information Response . . . . . . 12
7.3. Step 3: Parse Payment Account Information Response . . . 12
8. Example Use of Basic PayID Protocol . . . . . . . . . . . . . 13
8.1. Basic PayID Protocol by a Wallet . . . . . . . . . . . . 13
9. Common Response Status Codes (TODO) . . . . . . . . . . . . . 15
9.1. Success Responses . . . . . . . . . . . . . . . . . . . . 15
9.1.1. Response Code 200 OK . . . . . . . . . . . . . . . . 15
9.1.2. Response Code 3xx Redirection . . . . . . . . . . . . 15
9.2. Client Error Responses . . . . . . . . . . . . . . . . . 16
Malhotra & Schwartz Expires January 18, 2021 [Page 2]
Internet-Draft PayID Protocol July 2020
10. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 16
11. Versioning(TODO) . . . . . . . . . . . . . . . . . . . . . . 17
12. Security Considerations . . . . . . . . . . . . . . . . . . . 17
12.1. Network Attacks . . . . . . . . . . . . . . . . . . . . 17
12.1.1. Denial-of-Service (DoS) attacks . . . . . . . . . . 18
12.2. Information Integrity . . . . . . . . . . . . . . . . . 18
13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18
13.1. Access Control . . . . . . . . . . . . . . . . . . . . . 19
13.2. Payment Address Rotation . . . . . . . . . . . . . . . . 19
13.3. On the Wire . . . . . . . . . . . . . . . . . . . . . . 19
13.4. In the PayID Server . . . . . . . . . . . . . . . . . . 20
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
14.1. Header Field Registration . . . . . . . . . . . . . . . 21
14.2. Media Type Registration . . . . . . . . . . . . . . . . 21
15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 23
16.1. Normative References . . . . . . . . . . . . . . . . . . 23
16.2. Informative References . . . . . . . . . . . . . . . . . 24
16.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24
1. Terminology
This protocol can be referred to as the "Basic PayID Protocol" or
"PayID Protocol". The following terminology is used by this
specification.
o Endpoint: either the client or the server of the connection.
* Sending Endpoint: sending side of the transaction (wallet or
exchange).
* Receiving Endpoint: receiving side of the transaction (wallet
or exchange).
o PayID client: The endpoint that initiates the PayID protocol.
o PayID owner: The owner of the PayID URI as described in
[PAYID-URI].
o PayID server: The endpoint that returns payment account
information.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
Malhotra & Schwartz Expires January 18, 2021 [Page 3]
Internet-Draft PayID Protocol July 2020
2. Introduction
[PAYID-URI] describes a URI scheme to identify payment account(s) at
a service provider. [PAYID-DISCOVERY], on the other hand, defines
how to transform a PayID URI into a PayID URL that can be used by
other protocols to interact with a PayID-enabled service provider but
does not define the protocol(s) to do so.
This document specifies the PayID protocol - an application-layer
protocol which can be used to interact with a PayID-enabled service
provider identified by a PayID URL using standard HTTP methods over a
secure transport. In its most basic mode, a PayID protocol resource
returns a JavaScript Object Notation (JSON) object representing the
payment account(s) information along with optional metadata
corresponding to the queried PayID URI [PAYID-URI]. The protocol
defines new media formatting types for requests and responses, but
uses normal HTTP content negotiation mechanisms for selecting
alternatives that the PayID client and server may prefer in
anticipation of serving different use cases.
2.1. Design Goals
o Extensibility
Although the primary use case for the payment account(s) information
resource returned via the Basic PayID protocol is assumed to be for
making payments, the PayID protocol is designed to be easily
extensible to facilitate creation and retrieval of other resources
about the PayID owner, PayID client and/or PayID server that might be
required for making payments.
o Neutrality: Currency and Network Agnostic
The PayID protocol is designed to be a fundamentally neutral
protocol. The PayID protocol is capable of returning a PayID owner's
payment account(s) information for any network that they (or their
service) can support. This makes the PayID protocol a network and
currency agnostic protocol, capable of enabling payments in BTC, XRP,
ERC-20 tokens, Lightning, ILP, or even fiat networks like ACH.
o Decentralized & Peer-to-Peer
Just like email servers, anyone can run their own PayID server or use
third-party hosted services. If self-hosted, the PayID protocol
introduces no new counterparty risk or changes to a service's
security or privacy model. PayID protocol doesn't require new,
complex, and potentially unreliable peer discovery protocols, instead
establishing direct peer-to-peer connections between communicating
Malhotra & Schwartz Expires January 18, 2021 [Page 4]
Internet-Draft PayID Protocol July 2020
parties from the start. PayID is built on the most successful
decentralized network: the web. There is no designated centralized
authority, or a risk of a patchwork of different standards in
different jurisdictions that make a global solution impossibly
complex.
o Service Sovereignty
Each service provider that uses PayID for their users maintains full
control of its PayID URL space and PayID service, and has the ability
to incorporate any policies they choose, including privacy,
authentication, and security. They also have full sovereignty over
users on their domain, just like with email. PayID is highly
generalized and does not prescribe any particular solution outside of
the standardized communication, which makes it compatible with
existing compliance and user management tools and philosophies.
3. PayID Server Discovery
To support PayID protocol, the PayID client needs to discover the
PayID URL corresponding to the PayID URI [PAYID-URI]. This can be
obtained either by using mechanisms described in [PAYID-DISCOVERY] or
by manually entering the PayID URL.
4. JSON Format Design
JSON, as described in [RFC8259][], defines a test format for
serializing structured data. Objects are serialized as an unordered
collection of name/value pairs. JSON does not define any semantics
around the name/value pairs that make up an object. PayID protocol's
JSON format defines name/value pairs that annotate a JSON object,
property or array for PayID protocol resources.
The PayID client MUST request a PayID response in JSON format through
the "Accept" header with the media type as defined below, optionally
followed by format parameters. One of the optional parameters is the
case-insensitive "q" value as described in Section 5.3.1 of [RFC7231]
to indicate relative preference.
Each message body is represented as a single JSON object. This
object contains a name/value pair whose value is the correct
representation for a primitive value as described in [RFC8259][], or
an array or object as described in the section below.
If the PayID server does not support JSON format, it MUST reply with
an appropriate error response.
Malhotra & Schwartz Expires January 18, 2021 [Page 5]
Internet-Draft PayID Protocol July 2020
4.1. HTTP Method
The PayID protocol payment account(s) information resource is
requested using the HTTP GET method.
Following are the media types to request the payment account(s)
information resource on different payment-networks and environments.
4.2. Media Type of the Payment Account(s) Information Resource
The media type for the payment account information resource is
"application/* + json".
4.3. Response for application/* + json
The response body for "application/* + json" is a JSON object with
the following name/value pairs.
{
optional string payId,
required Address[] addresses,
optional string memo,
optional string identity,
optional ProofOfControlSignature proofOfControlSignature
}
4.3.1. payId
The value of "payId" field is the PayID URI in the client request
that identifies the payment account information that the JSON object
describes.
The "payId" field is an optional field in the response.
4.3.2. addresses
The value of "addresses" field is a JSON array of type "Address" of
one or more JSON objects with the following name/value pairs.
{
required string paymentNetwork,
optional string environment,
required string addressDetailsType,
required addressDetailsType addressDetails
}
o paymentNetwork: The value of payment-network as specified in the
client request's "Accept" header
Malhotra & Schwartz Expires January 18, 2021 [Page 6]
Internet-Draft PayID Protocol July 2020
o environment: The value of environment as specified in the client
request's "Accept" header
o addressDetailsType: The value of "addressDetailsType" is one of
the following strings.
* CryptoAddressDetails
* ACHAddressDetails
o addressDetails: The value of "addressDetails" is the address
information necessary to send payment on a specific payment-
network and environment.
The "addresses" field MUST be present in the response.
4.3.2.1. addressDetails
We define the following two types of payment address types.
o CryptoAddressDetails: This is a JSON object with the following
name/value pairs.
{ required string address, optional string tag }
* address: The value of "address" field contains the on-ledger
address corresponding to this owner.
* tag: The value of "tag" field is the tag value used by some
cryptocurrencies to distinguish accounts contained within a
singular address. E.g XRP Ledger's destination tag.
o ACHAddressDetails: This is a JSON object with the following name/
value pairs.
{ required string accountNumber, required string routingNumber }
* accountNumber: The value of "accountNumber" is the ACH account
number.
* routingNumber: The value of "routingNumber" is the ACH routing
number.
4.3.3. memo
The "memo" string may specify additional metadata corresponding to a
payment.
Malhotra & Schwartz Expires January 18, 2021 [Page 7]
Internet-Draft PayID Protocol July 2020
The "memo" string is an OPTIONAL field in the response.
4.3.4. identity
The "identity" string may specify any additional identity information
about the PayID owner or PayID server.
The "identity" string is an OPTIONAL field in the response.
4.3.5. proofOfControlSignature
The value of "proofOfControlSignature" field is a JSON object of type
"ProofOfControlSignature" with the following name/value pairs.
{
required string publicKey,
required string payID,
required string hashAlgorithm,
required string signature
}
o publicKey: On-ledger public key of the Receiving Endpoint
o payID: PayID URI of the PayID owner
o hashAlgorithm: Hash algorithms used to hash the entire contents of
the "ProofOfControlSignature" message.
o signature: Digital signature over the hash of the entire contents
of the "ProofOfControlSignature" message using the private key
corresponding to the public key in "publicKey". This is a proof
that the Receiving Endpoint is the owner of the on-ledger public
key in "publicKey".
The "proofOfControlSignature" is an OPTIONAL field in the response.
4.4. Meaning of Media Type application/* + json
"*" may represent different payment-networks and environments. In
this document, we propose standards with the media types specific to
XRP, ILP, and ACH payment networks. We also propose media types that
return all addresses across all payment networks. Other payment
networks MUST establish standard media types for their networks at
IANA.
o Accept: application/payid-json Returns all payment account(s)
information corresponding to the requested PayID URI
Malhotra & Schwartz Expires January 18, 2021 [Page 8]
Internet-Draft PayID Protocol July 2020
o Accept: application/xrpl-mainnet+json
Returns XRPL mainnet XAddresses
o Accept: application/xrpl-testnet+json
Returns XRPL testnet XAddresses
o Accept: application/xrpl-devnet+json
Returns XRPL devnet XAddresses
o Accept: application/interledger-testnet+json
Returns mainnet payment pointer to initiate SPSP request
o Accept: application/interledger-devnet+json
Returns testnet payment pointer to initiate SPSP request
o Accept: application/ach+json
Returns account and routing number
The PayID client MAY specify more than one media type along with the
preference parameter. The server MUST respond as described in the
Content Negotiation section below.
5. Header Fields
PayID protocol defines semantics around the following request and
response headers. Additional headers MAY be defined, but have no
unique semantics defined in the PayID protocol.
5.1. Common Headers
The following headers are common between PayID requests and
responses.
5.1.1. Header Content-Type
PayID requests and responses with a JSON message body MUST have a
"Content-Type" header value of "application-json".
Malhotra & Schwartz Expires January 18, 2021 [Page 9]
Internet-Draft PayID Protocol July 2020
5.1.2. Header Content-Length
As defined in [RFC7230][], a request or response SHOULD include a
"Content-Length" header when the message's length can be determined
prior to being transferred. PayID protocol does not add any
additional requirements over HTTP for writing Content-Length.
5.1.3. Header PayID-version (TODO)
The PayID client MUST include the PayID version request header field
to specify the version of the PayID protocol used to generate the
request.
If present on a request, the PayID server MUST interpret the request
according to the rules defined in the specified version of the PayID
protocol or fail the request with an appropriate error response code.
If not specified in a request, the PayID server MUST fail the request
with an appropriate error code.
5.2. Request Headers
In addition to common Headers, the PayID client MUST specify the
following request header.
5.2.1. Header Accept
The PayID client MUST specify the "Accept" request header field with
at least one of the registered media types (Section X). The purpose
of this header is to indicate what type of content can be understood
in the response. It specifies the "payment-network" and
"environment" of the payment account and its representation format
for which the PayID client wants to receive information. The
representation format is always JSON.
The PayID server MUST reject formats that specify unknown or
unsupported format parameters.
5.3. Response Headers
In addition to the Common Headers, the PayID server MUST specify the
following response header.
5.3.1. Header Cache-Control
The PayID server MUST include the "Cache-Control" header with the
max-age limit of 0. The intermediate hops or PayID client MUST NOT
cache the responses.
Malhotra & Schwartz Expires January 18, 2021 [Page 10]
Internet-Draft PayID Protocol July 2020
6. Extensibility
6.1. Payload Extensibility
PayID protocol supports extensibility in the payload, according to
the specific format.
Regardless of the format, additional content MUST NOT be present if
it needs to be understood by the receiver in order to correctly
interpret the payload according to the specified PayID-Version
header. Thus, clients MUST be prepared to handle or safely ignore
any content not specifically defined in the version of the payload
specified by the PayID-version header.
6.2. Header Field Extensibility
The PayID protocol defines semantics around certain HTTP request and
response headers. Services that support a version of the PayID
protocol conform to the processing requirements for the headers
defined by this specification for that version.
Individual services MAY define custom headers. These headers MUST
NOT begin with PayID. Custom headers SHOULD be optional when making
requests to the service. A service MUST NOT require the PayID client
to understand custom headers to accurately interpret the response.
6.3. Format Extensibility
A PayID service MUST support JSON format as described above and MAY
support additional formats response bodies.
7. Basic PayID Protocol
The Basic PayID protocol is used to request a payment account(s)
information resource identified by a PayID URI from a PayID-enabled
service provider identified by a PayID URL using HTTP over secure
transport. When successful, the PayID protocol always returns the
JSON representation of a payment account(s) information resource
along with optional metadata. This information can be used for any
purposes outside the scope of this document, though it is expected
the most common application would be making payment.
The Basic PayID protocol comprises request and response messages,
each of which is defined in more detail below. The following is a
visual representation of the basic protocol flow:
Malhotra & Schwartz Expires January 18, 2021 [Page 11]
Internet-Draft PayID Protocol July 2020
PayID client PayID server
| |
| 1.) GET request to PayID URL |
|--------------------------------------------------------->|
| | | |
| 2.) 200 Ok |
| Payment account information response |
|<---------------------------------------------------------|
| |
| |
7.1. Step 1: HTTP Request to PayID URL using HTTP GET Method
A basic PayID client issues a query using the HTTP GET method to the
PayID URL without any query parameters and body.
The PayID client MUST query the PayID server using HTTPS only.
[RFC2818] defines how HTTPS verifies the PayID server's identity. If
the HTTPS connection cannot be established for any reason, then the
PayID client MUST accept that the PayID request has failed and MUST
NOT attempt to reissue the PayID request using HTTP over a non-secure
connection.
7.2. Step 2: Payment Account Information Response
In response, the PayID server returns a JSON object representation of
a payment account(s) information resource for the payment-network and
environment requested by the PayID client in the request "Accept"
header field, along with other required and/or optional metadata.
A PayID server MUST be able to process the "application/payid+json"
header type.
If the PayID server does not contain the payment account information
corresponding to the request, the PayID server MUST respond with an
appropriate error message.
A PayID server MAY redirect the PayID client; if it does, the
redirection MUST only be to an "https" URI and the PayID client MUST
perform certificate validation again when redirected.
7.3. Step 3: Parse Payment Account Information Response
If the PayID server returns a valid response, the response will
contain one or more of the fields defined above.
Malhotra & Schwartz Expires January 18, 2021 [Page 12]
Internet-Draft PayID Protocol July 2020
8. Example Use of Basic PayID Protocol
This section shows sample use of Basic PayID protocol in several
hypothetical scenarios.
8.1. Basic PayID Protocol by a Wallet
Suppose Alice wishes to send a friend some XRP from a web-based
wallet provider that Alice has an account on. Alice would log-in to
the wallet provider and enter Bob's PayID (say,
"bob$receiver.example.com") into the wallet UI to start the payment.
The Wallet application would first discover the PayID URL for the
PayID service-provider using one of the mechanisms described in PayID
discovery [PAYID-DISCOVERY] protocol.
The Wallet application would then issue an HTTPS GET request:
GET /users/bob HTTP/1.1
Host: www.receiver.example.com
Accept: application/payid+json
PayID-version: 1.0
The PayID server might respond like this:
Malhotra & Schwartz Expires January 18, 2021 [Page 13]
Internet-Draft PayID Protocol July 2020
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 403
PayID-version: 1.0
Cache-Control: max-age=0
Server: Apache/1.3.11
{
"payId" : "bob$receiver.example.com",
"addresses" :
[
{
"paymentNetwork" : "xrpl",
"environment" : "testnet",
"addressDetailsType" : "CryptoAddressDetails",
"addressDetails" : {
"address" : "XTVQWr6BhgBLW2jbFyqqufgq8T9eN7KresB684ZSHKQ3oDth"
}
},
{
"paymentNetwork" : "ach",
"environment" : "mainnet",
"addressDetailsType" : "ACHAddressDetails",
"addressDetails" : {
"accountNumber" : "5674536253",
"routingNumber" : "aYJTDFGLKAJD"
}
}
],
"memo" : "Additional optional Information"
}
In the above example we see that the PayID server returned a list of
payment accounts identified by PayID "bob$receiver.example.com".
This is because Alice's Wallet asked for all the payment accounts
corresponding to the PayID in the "Accept" header. Alice's Wallet
MAY then use the payment account information to make payments.
Another example:
GET /users/bob HTTP/1.1
Host: www.receiver.example.com
Accept: application/xrpl-testnet+json; q=0.4,
application/ach+json; q=0.1
PayID-version= 1.0
The PayID server might respond like this:
Malhotra & Schwartz Expires January 18, 2021 [Page 14]
Internet-Draft PayID Protocol July 2020
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 403
PayID-version: 1.0
Cache-Control: max-age=0
Server: Apache/1.3.11
{
"payId" : "bob$receiver.example.com",
"addresses" :
[
{
"paymentNetwork" : "xrpl",
"environment" : "testnet",
"addressDetailsType" : "CryptoAddressDetails",
"addressDetails" : {
"address" : "XTVQWr6BhgBLW2jbFyqqufgq8T9eN7KresB684ZSHKQ3oDth"
}
}
]
}
9. Common Response Status Codes (TODO)
A PayID server MAY respond to a request using any valid HTTP response
code appropriate for the request. The PayID server SHOULD be as
specific as possible in its choice of an HTTP specific status code.
9.1. Success Responses
The following response codes represent successful requests.
9.1.1. Response Code 200 OK
A request that does not create a resource returns 200 OK if it is
completed successfully and the value of the resource is not null.
null. In this case, the response body MUST contain the value of the
resource specified in the request URL.
9.1.2. Response Code 3xx Redirection
As per [RFC7231], a 3xx Redirection indicates that further action
needs to be taken by the client in order to fulfill the request. In
this case, the response SHOULD include a Location header, as
appropriate, with the URL from which the result can be obtained; it
MAY include a Retry-After header.
Malhotra & Schwartz Expires January 18, 2021 [Page 15]
Internet-Draft PayID Protocol July 2020
9.2. Client Error Responses
Error codes in the 4xx range indicate a client error, such as a
malformed request. In the case that a response body is defined for
the error code, the body of the error is as defined for the
appropriate format.
10. Content Negotiation
The PayID client MAY choose to query for all possible payment
addresses corresponding to a PayID URI
GET / HTTP/1.1
Accept: application/all+json
In this case, the PayID server MAY respond with all payment
account(s) information associated with the queried PayID.
Alternatively, the PayID client MAY choose to query for a subset
payment account(s) information in the order of preference.
GET / HTTP/1.1
Accept: application/xrpl-testnet+json; q=0.4,
application/xrpl-mainnet+json; q= 0.1
In this case, the PayID server MUST respond with the payment
account(s) information corresponding to at least one of the payment-
networks and environments mentioned in the "Accept" header in the
order of client request preference. If none of those exist, the
PayID server MUST send an appropriate error response.
Alternatively, the PayID client MAY combine the above two approaches.
GET / HTTP/1.1
Accept: application/xrpl-testnet+json; q=0.4,
application/xrpl-mainnet+json; q= 0.1,
application/payid+json
In this case, the PayID server MUST respond with the payment account
information corresponding to at least one of the payment-network and
environment mentioned in the "Accept" header in the order of PayID
client's preference. If none of those exist, then the PayID server
MUST respond with payment account(s) information corresponding to all
payment accounts associated with the queried PayID URI.
Malhotra & Schwartz Expires January 18, 2021 [Page 16]
Internet-Draft PayID Protocol July 2020
11. Versioning(TODO)
Versioning enables clients and servers to evolve independently.
PayID protocol defines semantics for protocol versioning.
PayID requests and responses are versioned according to the PayID-
version header. PayID clients include the PayID-version header in
order to specify the maximum acceptable response version. PayID
servers respond with the maximum supported version that is less than
or equal to the requested "major"
12. Security Considerations
This security considerations section only considers PayID clients and
servers bound to implementations as defined in this document. Such
implementations have the following characteristics:
o PayID URIs are static and well-known to the PayID client; PayID
server URLs can be static or discovered.
The following are considered out-of-scope:
o Communication between the PayID owner and the wallet or exchange
(which acts as PayID server) for PayID URI registration, etc.
o Communication between the sender of the transaction and the PayID
client to transfer information such as PayID URI and other
transaction details, etc.
o PayID server URL discovery by the PayID client. Implementations
using PayID-Discovery [PAYID-DISCOVERY] MUST consider the security
considerations in the corresponding document.
o PayID server URL resolution by the PayID client. Implementations
using DNS, DNSSEC, DoH, DoT, etc. MUST consider the security
considerations of the corresponding documents.
12.1. Network Attacks
Basic PayID protocol's security model assumes the following network
attackers:
o Off-path attacker: An off-path attacker can be anywhere on the
network. She can inject and spoof packets but can not observe, or
tamper with the legitimate traffic between the PayID client and
the server.
Malhotra & Schwartz Expires January 18, 2021 [Page 17]
Internet-Draft PayID Protocol July 2020
o On-path attacker: An on-path attacker can eavesdrop, inject, spoof
and replay packets, but can not drop, delay or tamper with the
legitimate traffic.
o In-path or Man-in-the-middle (MiTM) attacker: An MiTM is the most
powerful network attacker. An MiTM has full access to the
communication path between the PayID client and the server. She
can observe, modify, delay and drop network packets.
Additionally we assume that the attacker has enough resources to
mount an attack but can not break the security guarantees provided by
the cryptographic primitives of the underlying secure transport.
The basic PayID protocol runs over HTTPS and thus relies on the
security of the underlying transport. Implementations utilizing TLS
1.3 benefit from the TLS security profile defined in [RFC8446]
against all the above network attackers.
12.1.1. Denial-of-Service (DoS) attacks
As such, cryptography can not defend against DoS attacks because any
attacker can stop/interrupt the PayID protocol by: * Dropping network
packets, * Exhaustion of resources either at the network level or at
PayID client and/or server.
The PayID servers are recommended to follow general best network
configuration practices to defend against such attacks [RFC4732].
12.2. Information Integrity
The HTTPS connection provides transport security for the interaction
between PayID client and server but does not provide the response
integrity of the data provided by PayID server. A PayID client has
no way of knowing if data provided in the payment account information
resource has been manipulated at the PayID server, either due to
malicious behavior on the part of the PayID server administrator or
as a result of being compromised by an attacker. As with any
information service available on the Internet, PayID clients should
be wary of the information received from untrusted sources.
13. Privacy Considerations
The PayID client and server should be aware that placing information
on the Internet means that any one can access that information.