diff options
| -rw-r--r-- | bip-0070/extensions.mediawiki | 4 | ||||
| -rw-r--r-- | bip-0075.mediawiki | 60 | ||||
| -rw-r--r-- | bip-0075/paymentrequest.proto | 18 |
3 files changed, 69 insertions, 13 deletions
diff --git a/bip-0070/extensions.mediawiki b/bip-0070/extensions.mediawiki index b572b1d..947622d 100644 --- a/bip-0070/extensions.mediawiki +++ b/bip-0070/extensions.mediawiki @@ -5,5 +5,7 @@ Add your extension below using tags starting at 1000 and submit a pull-req. {| | Field Number || Extension Name || Field Name || Description |- -| 1000 || [[https://example.com|(unassigned)]] || (unassigned) || (unassigned) +| 1000 || [[https://github.com/bitcoin/bips/bip-0075.mediawiki|(BIP75)]] || status_code || Status Code for Payment Protocol error communication +|- +| 1001 || [[https://github.com/bitcoin/bips/bip-0075.mediawiki|(BIP75)]] || status_message || Human-readable message for Payment Protocol error communication |}
\ No newline at end of file diff --git a/bip-0075.mediawiki b/bip-0075.mediawiki index 753c6e5..6bac44a 100644 --- a/bip-0075.mediawiki +++ b/bip-0075.mediawiki @@ -101,7 +101,7 @@ message InvoiceRequest { |- | memo || Human-readable description of invoice request for the receiver |- -| notification_url || Secure (usually HTTPS) location where an [[#EncryptedPaymentRequest|EncryptedPaymentRequest]] (see below) SHOULD be sent when ready +| notification_url || Secure (usually TLS-protected HTTP) location where an [[#EncryptedPaymentRequest|EncryptedPaymentRequest]] (see below) SHOULD be sent when ready |- | signature || PKI-dependent signature |} @@ -242,6 +242,19 @@ message EncryptedPaymentACK { | identifier || Use the identifier specified with the EncryptedPayment, if any. |} +==Updated Messages== +The BIP70 PaymentRequest, Payment and PaymentACK messages have been updated by this BIP to contain Payment Protocol error communication. The following two extension fields have been added to each of the aforementioned messages: + +<pre> +{ +... + optional uint32 status_code = 1000; // Payment Protocol status code + optional string status_message = 1001; // Human-readable status message +} +</pre> + +status_code and/or status_message MUST be set to communicate a Payment Protocol error to the message receiver. The message consumer MUST handle status_code and status_message if either field is present. + ==InvoiceRequest / PaymentRequest Process== The process overview for using InvoiceRequests and receiving encrypted PaymentRequests is defined below in two sections. Optionally, the Sender MAY choose to encrypt the InvoiceRequest message and therefore MUST follow the '''Encrypted InvoiceRequest Overview''' process below. @@ -282,8 +295,8 @@ The process overview for using InvoiceRequests and receiving encrypted PaymentRe ==Message Interaction Details== -===New Message Content Types=== -Messages MUST be transmitted via TLS-protected HTTP using the appropriate Content-Type header as defined per message type here: +===New Message HTTP Content Types=== +When communicated via HTTP, these messages MUST be transmitted via TLS-protected HTTP using the appropriate Content-Type header as defined per message type here: {| class="wikitable" ! Message Type !! Content Type |- @@ -298,8 +311,43 @@ Messages MUST be transmitted via TLS-protected HTTP using the appropriate Conten | EncryptedPaymentACK || application/bitcoin-encrypted-paymentack |} -===Message or Communication Errors=== -An invalid or unparsable message or communications error MUST be communicated to the party that initiated the communication. This SHOULD be done through standard HTTP Status Code messaging ([https://tools.ietf.org/html/rfc7231 RFC 7231 Section 6]). If the provided hash of each message does not match the contents of the message once decrypted, a general error should be returned to prevent oracle attacks. +===Payment Protocol Errors=== + +Payment Protocol errors MUST be communicated to the party that initiated the communication via the status_code and status_message extension fields present in the PaymentRequest, Payment and PaymentACK messages. For example, if the provided hash of each message does not match the contents of the message once decrypted, a general error MUST be returned to prevent oracle attacks. + +====Payment Protocol Status Codes==== +{| class="wikitable" +! Status Code !! Description +|- +| 1 || General / Unknown Error +|- +| 2 || Authentication Failed +|- +| 3 || Encrypted Message Required +|- +| 100 || Amount Too High +|- +| 101 || Amount Too Low +|- +| 102 || Amount Invalid +|- +| 103 || Payment Does Not Meet PaymentRequest Requirements +|- +| 200 || Certificate Required +|- +| 201 || Certificate Expired +|- +| 202 || Certificate Invalid for Transaction +|- +| 203 || Certificate Revoked +|- +| 204 || Certificate Not Well Rooted +|- +|} + +===Communication Errors=== + +Communications errors MUST be communicated to the party that initiated the communication via the communication layer's existing error messaging faciltiies. In the case of TLS-protected HTTP, this SHOULD be done through standard HTTP Status Code messaging ([https://tools.ietf.org/html/rfc7231 RFC 7231 Section 6]). ==Process Step Details== @@ -311,7 +359,7 @@ Where used, '''nonce''' MUST be set to a non-repeating number AND MUST be chosen * Create an InvoiceRequest message * sender_public_key MUST be set to the public key of an EC keypair * nonce MUST be set according to the requirement above. -* Amount is optional. If the amount is not specified by the InvoiceRequest, the Receiver MAY specify the amount in the returned PaymentRequest. If an amount is specified by the InvoiceRequest and a PaymentRequest cannot be generated for that amount, the InvoiceRequest SHOULD be rejected with HTTP status code 406. +* Amount is optional. If the amount is not specified by the InvoiceRequest, the Receiver MAY specify the amount in the returned PaymentRequest. If an amount is specified by the InvoiceRequest and a PaymentRequest cannot be generated for that amount, the InvoiceRequest SHOULD return a PaymentRequest with the status_code and status_message fields set appropriately. * Memo is optional. This MAY be set to a human readable description of the InvoiceRequest * Set notification_url to URL that the Receiver will submit completed EncryptedPaymentRequest to * If NOT including certificate, set pki_type to "none" diff --git a/bip-0075/paymentrequest.proto b/bip-0075/paymentrequest.proto index 1c9cc8e..912fcd3 100644 --- a/bip-0075/paymentrequest.proto +++ b/bip-0075/paymentrequest.proto @@ -33,19 +33,25 @@ message PaymentRequest { optional bytes pki_data = 3; // depends on pki_type required bytes serialized_payment_details = 4; // PaymentDetails optional bytes signature = 5; // pki-dependent signature + optional uint32 status_code = 1000; // Payment Protocol status code + optional string status_message = 1001; // Human-readable Payment Protocol status message } message X509Certificates { repeated bytes certificate = 1; // DER-encoded X.509 certificate chain } message Payment { - optional bytes merchant_data = 1; // From PaymentDetails.merchant_data - repeated bytes transactions = 2; // Signed transactions that satisfy PaymentDetails.outputs - repeated Output refund_to = 3; // Where to send refunds, if a refund is necessary - optional string memo = 4; // Human-readable message for the merchant + optional bytes merchant_data = 1; // From PaymentDetails.merchant_data + repeated bytes transactions = 2; // Signed transactions that satisfy PaymentDetails.outputs + repeated Output refund_to = 3; // Where to send refunds, if a refund is necessary + optional string memo = 4; // Human-readable message for the merchant + optional uint32 status_code = 1000; // Payment Protocol status code + optional string status_message = 1001; // Human-readable Payment Protocol status message } message PaymentACK { - required Payment payment = 1; // Payment message that triggered this ACK - optional string memo = 2; // Human-readable message for customer + required Payment payment = 1; // Payment message that triggered this ACK + optional string memo = 2; // Human-readable message for customer + optional uint32 status_code = 1000; // Payment Protocol status code + optional string status_message = 1001; // Human-readable Payment Protocol status message } // BIP-IR Extensions |