TS 2021.014

Direct Payment Protocol

Background

This standard serves two purposes:

1. Ensure a well maintained source of information for all invoice based payment standards (currently BIP270, BIP271, BIP272, BIP273, BIP274, BIP275, BIP282) and related invoicing standards such that new industry players and developers find up to date and accurate information.
2. Harmonize extensions to BIP270, BIP271, BIP272, BIP273, BIP274, BIP275, BIP282 to allow invoicing for different payment options as well as combinations of payment options either in a single transaction or in multiple transactions.

Problem Statement

Currently BIP270, BIP271, BIP272, BIP273, BIP274, BIP275, BIP282 are not owned by a standards committee. Several versions exist on GitHub and they all share one thing in common: They don’t represent the current implementations in the field. This makes it very hard for new players to come in and get invoice based payments right the first time.

Further, many industry representatives have voiced the need for an extension to the current standard which, for example, could allow for payments in meta-assets or the accepting of discount coupons which lower the amount of BSV required to successfully satisfy the invoiced amount.

Objectives

1. Re-evaluate the current BIP270, BIP271, BIP272, BIP273, BIP274, BIP275, BIP282 standard and baseline it to the common field implementation.
2. Maintain backwards compatibility.
3. Collect extension wishes and needs from industry players.
4. Find the smallest denominator for such extension needs.
5. Allow for future custom extensions without jeopardizing backwards compatibility (e.g. Travel Rule information, SPV information, etc.).
6. Publish the standard/BIPs publicly (e.g. GitHub) and advertise it through the appropriate channels to spur adoption.
7. Maintain the standard/BIPs.

Scope

Invoice Based Payments, BIP270, BIP271, BIP272, BIP273, BIP274, BIP275, BIP282

Out of Scope: Topics covered by other working groups such as merchant-payee address resolution, and Simplified Payment Verification (SPV) transaction validation.

Methods and Concepts

1. Intro session with all interested participants. Understanding of interests and needs. Introduction to the existing draft proposal. Potential break out sessions for particular needs after. Collection of Requirements.
2. Formation of core group which writes the actual standard and makes sure requirements collected in phase 1 are covered as well as possible.
3. Preliminary rollout and implementation phase. Collection of Feedback from these implementations.
4. Amendments based on Feedback.
5. Publication and Rollout.
6. Maintain standard.

Specification

Abstract

This RFC describes a protocol for communication between a payment host (usually either a merchant, a payment processor, or simply the recipient’s wallet) and sender (a customer, acquaintance, or device like an IoT device – an entity known to the receiver). It aims to improve customer experience, simplifying wallet infrastructure to make more advanced wallet features such as multiple outputs easier to implement, and to improve wallet security against payment process attacks such as man-in-the-middle.

Please note that the “payment host” in this document may not actually be the recipient of the funds. Like BitPay, the payment host may actually be a host or payment processor who is providing this protocol as a service for another party who is the actual recipient of the funds. We have chosen the name “payment” host to be an abstraction over either a merchant, a payment processor, a wallet, or any other agent that receives funds or acts as a proxy to whoever is the true recipient of the funds.

Motivation

The naive Bitcoin payment protocol operates as follows:

1. Customer decides to checkout while online shopping, and chooses to pay using Bitcoin.
2. Payment host generates a unique payment address, generates an invoice for the customer, updates the invoice with the payment address, and displays the invoice on an order completion web page.
3. Customer copies the Bitcoin address from the payment host’s web page and pastes it into whatever wallet they are using, or follows a bitcoin: link (e.g., scans a QR code from a wallet on their smart phone) and their wallet is launched with the amount to be paid.
4. Customer authorizes payment to the merchant and their wallet posts the transaction to a wallet server which posts the transaction to a Bitcoin node.
5. Payment host’s server continuously scans the Bitcoin blockchain until the payment is detected, and after the transaction reached a certain threshold of transaction confirmations set by the merchant, it is considered settled.

There are several major problems with the naive approach. First, it requires the customer broadcast the transaction; meaning the customer’s wallet must connect to the Bitcoin network, and the payment host must wait for the transaction to be validated and propagate before accepting the payment. Second, it has no ability to allow for multiple outputs, which is necessary for many interesting use-cases of Bitcoin such as OP_RETURN data. Third, there is no reliable way for a payment host to refund a payment in case of an issue.

This RFC extends the naive protocol to simplify wallet construction, add new wallet features, and help make exponential ‘on-chain’ scaling possible; to the effect of enabling Bitcoin nodes to accommodate all future global network communications:

1. Flexible payment destinations: can be human-readable (customers will be asked to authorize payment to “http://example.com ” instead of an inscrutable 34-character bitcoin address), support for various tokens protocols, support for native approach (from BIP270).
2. Secure proof of payment, which customers can use in the event of a dispute with the merchant.
3. Protection from man-in-the-middle attacks that replace a payment host’s receiving Bitcoin address with an attacker’s address before a transaction is authorized with a hardware wallet.
4. Payment is sent directly to the payment host, removing the necessity of the customer engaging with the Bitcoin p2p network, and enabling quicker confirmation.
5. Payment received messages, so the customer knows immediately that the payment host has received, and has processed (or is processing) their payment.
6. Originator data automatically given to the payment host by the customer’s wallet software, so payment hosts e.g. do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason. Originator data can be used also for various other cases e.g. promotions (like every 10th payment from the same customer will trigger send voucher back).
7. Payment can contain multiple outputs which can be arbitrary scripts and not just addresses, making new applications possible.
8. It is no longer necessary for wallets to connect to the Bitcoin p2p network to broadcast transactions.
9. It is no longer necessary for payment hosts to maintain an address index to monitor for in coming transactions.

Protocol

This specification describes payment protocol messages encoded using JSON, authenticated and communicated using HTTPS or other authentication and communication systems (such as the blockchain itself). Future BIPs might extend this payment protocol to other encodings, PKI systems, or transport protocols.

The payment protocol consists of three messages; PaymentTerms, Payment, and PaymentACK, and begins with the customer somehow indicating that they are ready to pay and the payment host’s server responding with a PaymentTerms message:

Messages

There are several JSON objects used in the protocol. We start with a summary of the JSON objects, and then proceed to the details. Top-level objects are the messages type at the same time.

• PaymentTerms: A way of specifying the details of a required payment, including a dict of destinations, expiration data, and other meta data. This message/object contains 2 main parts (and a few variables):
  1. Modes: Payment modes where each mode describes detailed instruction about payment requirements, where requirements are embedded in specified format (Payment Mode)
  2. Beneficiary: A way of specifying data about merchant.
  3. Policies: A way of specifying special merchant’s requirements according to Payment object.
• Payment: Includes a signed Bitcoin transaction. Detailed format of Payment depends on chosen Payment Mode but the below object is common for all modes:
  1. Originator: A way of specifying data about payer.
• PaymentAck: Acknowledgement of receipt of payment. Detailed format of PaymentACK depends on chosen Payment Mode but the below object is common for all modes
  1. PeerChannel: A way to provide data needed to communicate via created channel in a secure manner.

PaymentTerms

A payment request contains the information the consumer needs to make the payment to the payment host.

PaymentTerms {
    network // string. required.
    version // string. required. 
    outputs // an array of outputs. optional, deprecated - for backward compatibility.
    creationTimestamp // number. required.
    expirationTimestamp // number. optional.
    memo // string. optional.
    paymentUrl // string. required.
    beneficiary // object. optional.
    modes // a key-value map. required.
    policies // object. optional.
}

The paymentUrl specified in the PaymentTerms should remain valid at least until the PaymentTerms expirationTimestamp (or as long as possible if the PaymentTerms does not expire). Note that this is irrespective of any state change in the underlying payment request; for example cancellation of an order should not invalidate the paymentUrl, as it is important that the payment host’s server can record mis-payments in order to refund the payment.

When a Bitcoin wallet application receives a PaymentTerms, it must authorize payment by doing the following:

1. Validate the payment host’s identity and signature using the PKI system. The PKI system is assumed to occur in a wrapper layer (such as HTTPS) and if no PKI system is available then the wallet can choose whether or not to display the payment request. The PKI system is usually HTTPS, and as such if the payment request is retrieved over HTTPS then the domain name should be displayed as the payment host.
2. Validate that customer’s system unix time (UTC) is before PaymentTerms.expirationTimestamp. If it is not, then the payment request must be rejected.
3. Display the payment host’s identity and ask the customer if they would like to submit payment (e.g. display the “Common Name” in the first X.509 certificate).

PaymentTerms messages larger than 10 MB should be rejected by the wallet application, to mitigate denial-of-service attacks.

Example:

{
  memo: "Payment for purchasing Socks online",
  network: mainnet,
  creationTimestamp: 1648163657,
  expirationTimestamp: 1648164657,
  paymentUrl: https://localhost:3443/api/v1/payment/Order-325214,
  beneficiary: {
    name: "GoldenSocks.com",
    email: "[email protected]
    address: wonderland 25, Nicecountry
    paymentReference: "Order-325214",
  },
  policies: {
    requiredOriginatorFields: [paymail]
  }
  modes: {
  'ef63d9775da5': { // HybridPaymentMode
      choiceID0: {
        transactions: [
          {
            outputs: {
              native: [
                {
                  satoshis: 10000000,
                  script: "76a91493d0d43918a5df78f08cfe22a4e022846b6736c288ac",
                },
              ],
            },
            policies: {
              fees: {
                  standard: {
                    satoshis: 1,
                    bytes: 1
                  },
                  data: {
                    satoshis: 1,
                    bytes: 10
                  }
                },
              SPVRequired: false
            }
          },
        ],
      },
      choiceID1: {
        transactions: [
          {
            outputs: {
              native: [
                {
                  satoshis: 10000,
                  script: "76a91493d0d43918a5df78f08cfe22a4e022846b6736c288ac",
                },
              ],
              brfc1: [ // please note that this is only example, RUN protocol schema might be differ
                {
                  contractName: "MyToken",
                  contractType: "RUN's word for Standard Fungible Token", // this will further devide the sub-protocol into sub-sub-protocols.
                  contractLocation:
                    "bc64f3ab1ffe7b4396097b9611ed4105ac5994901202c84b334708d6cc42067a_o1",
                  tokenAmount: 400,
                  tokenRecepient: "1DjmxqX7AnzQe6rUyG1AibPhUCXLJyoMVU",
                },
              ],
            },
            inputs: {
              native: [
                {
                  // input #1
                },
              ],
              // brfc100: [
              //     {}
              // ]
            },
            policies: {
              ancestry: { format: "binary", minDepth: 2 },
              SPVRequired: false
              // can be extended with "req-" parameter if extensions are Required!
            },
            // can be extended with "req-" parameter if extensions are Required!
          },
          {
            outputs: {
              STAS: [ // please note that this is only example, STAS protocol schema might be differ
                {
                  satoshis: 10000,
                  script: "some really long STAS script",
                  contractTX: "XYZ",
                  contractAddress: "ABC",
                },
              ],
            },
            policies: {
              ancestry: { format: "binary", minDepth: 2 },
              SPVRequired: false
            },
          }
        ],
      },
    }
  }
}

a. Modes

Required outputs packed inside some specified mode. PaymentTerms might provide various modes and the customer or wallet logic has to choose which mode it’s going to use. Chosen mode then dictates how the Payment and PaymentACK objects will look like to fit the chosen mode’s flow and requirements. More information about PaymentModes can be found <here>.

b. Beneficiary

The beneficiary data contains information about the merchant.

Beneficiary {
  name // string. required.
  email // string. required.
  address // string. required.
  paymentReference // string. ID of invoice. required.
  avatar // string. optional.
  extendedData // object. optional, freestyle object.
}

c. Policies

Policies defines extra merchant’s requirements. At this version of DPP the only one are related to required Originator fields (e.g. if payer doesn’t provide paymail, the payment won’t be processed) but in the future it might be extended (e.g. travel rule might be required by merchant, payers country might be limited etc.)

Policies {
  requiredOriginatorFields // an array. optional.
}

Payment

Payment messages are sent after the customer has authorized payment. It refers to which payment mode was chosen and provides the specific data required for the particular mode:

Payment {
  modeId // string. The chosen mode
  mode // object. The Payment object for the specific mode used.
  originator // object. payer data needed for identification as well as refund. optional.
  transaction // a hex-formatted (and fully-signed and valid) transaction. optional. deprecated
  memo // string. optional.
}

When the payment host’s server receives the Payment message, it must determine whether or not the transactions satisfies conditions of payment terms. If and only if they do, it should broadcast the transaction to the the Bitcoin p2p network.

Payment messages larger than 10 MB should be rejected by the payment host’s server, to mitigate denial-of-service attacks.

Example:

{
  modeId: "ef63d9775da5", // This ID is brfcid for HybridPaymentMode"
  mode: {
    ...  //HybridPaymentMode Payment object
  },
  originator: {
    name: "Aleks Dinkov",
    paymail: "[email protected]",
    avatarUrl: "https://iamges.com/vtwe4eerf",
  }
}

a. Originator

A payer data contains info about payer of the TX.

Originator {
  name // string. required.
  paymail // string. optional.
  return_address // string. optional
  return_script // string. optional
  avatar // string. optional.
  extendedData // object. optional, freestyle object.
}

b. Ancestor

The details about this object are referenced The details about this object are referenced in the Transactions Ancestors Standard

PaymentACK

PaymentACK is the final message in the payment protocol; it is sent from the payment host’s server to the bitcoin wallet in response to a Payment message:

PaymentACK {
  modeId // string. The chosen mode
  mode // object. The Payment object for the specific mode used.
  peerChannel // object. optional
  redirectUrl // string. optional
}

Example:

{
  modeId: "ef63d9775da5", // This ID is brfcid for HybridPaymentMode"
  mode: {
    ...  //HybridPaymentMode PaymentACK object
  },
  peerChannel: {
    host: "peerchannels:25009",
    token: "token",
    channel_id: "channelid",
  },
}

PaymentACK messages larger than 11 MB bytes should be rejected by the wallet application, to mitigate denial-of-service attacks. This is larger than the limits on Payment and PaymentTerms messages as PaymentACK contains a full Payment message within it.

Payment Modes

This is the main part of the PaymentTerms object. For now we propose one, flexible payment mode which you can use to pay with BSV, tokens, or a combination of funding sources (called HybridPaymentMode). In the future if HybridPaymentMode cannot fullfil some requirements, other PaymentModes can be specified. Chosen payment mode also has impact on the format of Payment and PaymentACK objects which might differ for different modes.

In the next section, predefined mode – HybridPaymentMode will be described together with related Payment and PaymentACK objects.

HybridPaymentMode (BRFCID: ef63d9775da5)

This is first defined payment which may fullfil a lot of requirements because of its flexible nature. It allows for a payment host to stipulate payment from a set of funding types created with AND and OR connections. With this arrangement a payment host can define a set of various outputs (tokens + BSV + loyalty points + stable coins) or even multiple equivalent alternatives to successfully fund the transaction. The wallet may chose which option depending upon user resources. This is the definition of the mode:

Options {
  "ID": Transactions // required, min one key-value pair.                   
}

So this payment mode just contains a dictionary of various options (options are OR relation, so they are alternative sets of outputs and the customer or their wallet will pick one).

Options (In PaymentTerms)

Every option contains a set of transactions (AND relation, if the customer chooses the option they must provide all the required funds to satisfy the transaction). Below you can find the interface for transaction object and transaction’s internal objects.

Transaction

Transaction object is a set which contains 3 parts:

1. Outputs: A way of specifying a Bitcoin transaction output, including the value and script for various token standards.
2. Inputs: A way of declaring which specific inputs should be used (useful for multisig, payment_channels etc).
3. Policies: A way of requesting specific TX policies like fees, SPV, nLockTime etc.

Transaction {
  outputs // list of output objects. required
  inputs // list of input objects. optional
  policies // additional properties and requirements for transaction. optional
}

Outputs

List of outputs – payment destinations.

Outputs {
  native // list of native output objects. optional.
  brfcXYZ // list of brfc objects of XYZ token. optional.
  tokenABC // list of ABC token objects. optional.
  ...
}

Native output

This is regular native BSV output which specify amount and recipient in bitcoin script form (usually p2pkh).

Native output {
  amount // number. required.
  script // string. required. hexadecimal script.
  description // string. optional. must not have JSON string length of greater than 100.
}

STAS output

This is output used for getting tokens using STAS protocol. It required to define tokenId (with symbol), amount and recipinet.

Native output {
  tokenId // string. required.
  amount // number. required.
  recipient // string. bitcoin address or paymail.
}

TokenXYZ

Structure for this object is specific for each particular token standard. This may be based on BRFC reference if said token standard hasn’t published a name yet or otherwise based upon a particular token’s name. Below are two example schemas:

brfc1234 {
  properties_1
  properties_2
  ...
}

unicornToken {
  tokenId // string. required
  script // string. required. hexadecimal script.
  ...
}

Inputs

A list of inputs object contains data needed to specify the required inputs which should be used.

Input {
  scriptSig // string. required.
  txid // string. required.
  vout // integer. required.
  value // integer. required.
  nSequence// number. optional.
}

Policies

An object containing some policy information like fees or spv envelope.

Policies {
  fees // dictionary. optional. Nested dictionary which include on Fee objects on 3rd level.
  SPVRequired // boolean. optional. default is false.
  lockTime // number. optional.  
}

Mode (In Payment)

This object defines fields required by HybridPaymentMode. In this mode important data are chosen for payment option (paymentId) and a list of transactions which fulfil this option:

"ef63d9775da5" {
  optionId // string. ID of chosen payment options
  transactions // a list of raw transactions. required
  ancestors // object. optional.
}

Example:

{
  optionId: "choiceID1",
  transactions: [
    " RAW_TRANSACTION for 'choiceID1.transactions[0]' ",
    " RAW_TRANSACTION for 'choiceID1.transactions[1]' ",
  ],
  ancestors: {
    " TXID of RAW_TRANSACTION for 'choiceID1.transactions[1]' ": {
      /* This object has the ancestors of 'choiceID1.transactions[1]' */
    },
  }
}

Mode (In PaymentACK)

This object defines fields required by HybridPaymentMode:

{
  transactionIds // a list of transaction ids. required
  peerChannel // object. optional
}

Example:

{
  transactions: [
    " TXID of transaction for 'choiceID1.transactions[0]' ",
    " TXID of transaction for 'choiceID1.transactions[1]' ",
  ],
  // Things like peer_channel should probably still be defined at the paymentAck root level. Different transactions should probably not have different peer_channel-s.
  peerChannel: {
    host: "peerchannels:25009",
    token: "token",
    channel_id: "channelid",
  },
}

API definition

Below is the table with messages requested from client (wallet) to merchant (server).

PaymentID parameter is assumed to be known as a result of request between client-server before DPP protocol operation (the first request/response on the diagram).

For more info you can refer to: https://jadwahab.github.io/direct-payment-protocol/#/

URI Scheme

URI scheme for 4P protocol represents a scheme for downloading the PaymentTerms object; which is the beginning of the payment process.

The URI is to allow users to click on a link in a web page, email or scan a QR codes to initiate the payment protocol.

The scheme is following:

pay:?r=https://merchant.com/pay.php?h%3D2a8628fc2fbe

Certificates

The original BIP 70 which this spec is based on included signatures from X.509 certificates (the same certificates used for SSL / TLS / HTTPS). We follow BIP270 which assumes the authentication happens at a separate layer and as such for simplicity we have removed authentication. Wallets should use other mechanisms to determine the name and identify of the recipient in a secure manner. Under the usual case on the web, DPP messages will be sent and received over HTTPS, which uses X.509 certificates, and thus the wallet should simply show the domain name under most cases. HTTP (and insecure form of HTTPS) should not be supported. Additional security layer is provided experimentally here https://jadwahab.github.io/direct-payment-protocol/#/ (/sec/ endpoints) and might be included in future DPP protocol versions.

Extensibility

We use JSON as JSON is naturally extensible. Any property of the objects not specified in this spec is a candidate to convey information for extensions.

History

Relationships

Supplementary Material

Summary of the comments

The comments received were very diverse and lead to a lot of great discussions around a few topics including but not limited to these:

• Should the protocol be more fundamentally changed than building on BIP270 implementations out there today? Like e.g. but not limited to: Should the originator be able to choose how to fulfill the payments with Bitcoin outputs instead of the requestor? Should it be backward compatible or start on a clean slate?
• Modularity and rigidity of the standard. The most open standard is no standard, but then what’s the point of a standard? A lot of use cases were considered by many reviewers and the goal of the workgroup was to accommodate as many of them as possible
• Comments around what information should be requested from the payment originator if any at all.
• The interfaces of IT networking and use cases the standard may be used for. Is a consumer-to-merchant transaction peer-to-peer? Socially these are not peers at the time. Is there a limitation to the interactions this protocol can be used with? These comments resulted in a lot of discussions around the name of DPP which was at the time proposed as “Invoice Based Payments”.

Summary of the decision log

• As initially proposed the standard was heavily built on how BIP270 payments which are implemented by major industry players today, especially by mobile wallets and interfaces. The party posing a payment request decides which options for fulfillment exist. The standard also maintains two fields that are depreciated at a point where all industry players had a chance to upgrade to DPP. So by still providing values in these two fields DPP payment requests are compatible with providers which don’t interpret DPP payment modes information yet.
• Despite extensive review and participation in the workgroup it became clear that not all future use cases can be foreseen today and that the ideas we have today already need a lot of flexibility. Therefore the concept of the payment mode was introduced into the standard. This allows not only for today and future use cases but allows the standard to be used also by various token protocols and for almost any type of bitcoin script.
• DPP allows for sending some default originator fields and also allows to extend the information that can travel with the transaction, such as information used from other standards such as the Travel Rule Standard or e.g. eligible buyer information. The requester of the payment can signal the policy in the payment request.
• The name of the standard that found an overwhelming majority was “Direct Payment Protocol (DPP)”.