# Submitting Received Payments to a Wallet Brayden Langley () ## Abstract To ensure a seamless process for submitting payments to a wallet, there must be a standardized method by which this process takes place. Wallets that implement this standard will be able to support the direct submission of transactions from applications to a user's wallet along with the associated SPV information as defined by [BRC-9](https://bsv.brc.dev/transactions/0009). The required message structure and fields are defined below in the [Payment Submission Message](#payment-submission-message) section, and the expected response to provide is defined in the [Payment Acknowledgment Message](#payment-acknowledgment-message) section. Wallets that choose to implement this specification will allow applications that facilitate the exchange of payments to be built in a way that is interoperable, extensible, and SPV compliant. ## Motivation BRC-50 standardizes payment submission to a wallet, improving the user experience for incoming Bitcoin payments. This enables higher-layer applications to add funds to a user's wallet without needing to maintain their own external balance. By standardizing payment submission, developers can create interoperable, extensible, and SPV compliant applications. This ensures a seamless and secure payment process, benefiting both wallet providers and end-users. ## Specification For this specification, we assume that there exists a wallet that facilitates a channel by which communication can occur with an application, such as over HTTP as defined in [BRC-5](https://bsv.brc.dev/wallet/0005). Based on this premise, we specify a standard by which payments can be submitted from an application to a wallet which then receives and processes the payment. ### Payment Submission Message We define an extension to the abstract [BRC-1](https://bsv.brc.dev/wallet/0001) messaging layer as the Payment Submission Message which comprises a JSON object with the following fields: > Several of the same fields as defined in [BRC-29](https://bsv.brc.dev/payments/0029) are present in this message. This standard essentially facilitates an implementation of [BRC-29](https://bsv.brc.dev/payments/0029) over an abstract, wallet-to-application interface. | Field | Type / Required | Description | | ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `protocol` | (string, required) | This field denotes that the JSON object comprises a payment message according to the given protocol (such as `3241645161d8` for [BRC-29](https://bsv.brc.dev/payments/0029)). | | `transaction` | (object, required) | The [BRC-8](https://bsv.brc.dev/transactions/0008) transaction envelope to submit, including key derivation information (the "Outputs Extension" as defined in [BRC-29](https://bsv.brc.dev/payments/0029)) | | `senderIdentityKey` | (string, required) | The recipient will need to know the public identity key of the sender in order to validate the incoming payment. This field's value should be the 33-byte, compressed, hex-encoded secp256k1 public key of the sender | | `derivationPrefix` | (string, required) | This field denotes the payment-wide derivation prefix used by the sender when the keys for the payment UTXOs were derived | | `note` | (string, required) | Human-readable description for the transaction. | | `amount` | (number, optional) | Amount of satoshis associated with the transaction. If provided, it is used to verify that the amount returned from processing the transaction matches the payment amount. | The transaction field is a JSON object that conforms to the [BRC-8](https://bsv.brc.dev/transactions/0008), with the [BRC-29](https://bsv.brc.dev/payments/0029) Outputs Extension. Only ***one*** transaction can be submitted per request. This provides the wallet with enough information to verify and receive payments from an application. Here is an *example* of a simple Payment Submission Message: ```json { "protocol": "3241645161d8", // Simple Authenticated BSV P2PKH Payment Protocol "transaction": { "rawTx": "01000000017...", "inputs": { "b7d1297158f01bfc3fdace31f62a0d4634e9471d11b2a99f0784621cedb9367c": { "proof": {...}, "rawTx": "01000000011..." } }, "mapiResponses": [...], "txid": "737a1e90af9745da3f22ef74bc71a089c5e2a76e9662a0c9fa5b7cf94fe32e75" }, "senderIdentityKey": "031d903f5b32a6121f29c59c547d2ea41ee8157ab0f0c2b5190be24a032816f827", "note": "Payment for spelling fix pull request.", "amount": 1033, "derivationPrefix:": "8217bb4e7fa0541e0f5e04fea764ab91" } ``` ### Payment Acknowledgment Message The Payment Acknowledgment Message is the response that should be returned from the wallet to the calling application with the status of the request, and a reference number for the transaction submitted. Here is an *example* response from a successful payment submission: ```json { "reference": "cd5b1e4947e304476c788cd474fb579a" } ``` ### Payment Error Message If an error occurs during submission, an internal error should be thrown which can be caught and handled by the application code. ## Implementation Wallets can implement this specification by providing access to a `submitDirectTransaction` route over a given [BRC-1](https://bsv.brc.dev/wallet/0001) communications substrate, such as [BRC-5](https://bsv.brc.dev/wallet/0005), [BRC-6](https://bsv.brc.dev/wallet/0006) or [BRC-7](https://bsv.brc.dev/wallet/0007). A specific implementation of this BRC can be seen in the Babbage [Dojo/Ninja](https://projectbabbage.com/docs/dojo) architecture.