# 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](/transactions/0009.md). 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. ## Status Note BRC-50 is historical. Current incoming transaction submission is specified by [BRC-100](/wallet/0100.md) `internalizeAction`. For BRC-29 payments, the current `outputs[].protocol` value is `wallet payment`; for basket insertions, it is `basket insertion`. The legacy `submitDirectTransaction` route and BRC-8 envelope payload are deprecated for new implementations. ## 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](/wallet/0005.md). 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](/wallet/0001.md) 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](/payments/0029.md) are present in this message. This standard essentially facilitates an implementation of [BRC-29](/payments/0029.md) 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](/payments/0029.md)). | | `transaction` | (object, required) | The [BRC-8](/transactions/0008.md) transaction envelope to submit, including key derivation information (the "Outputs Extension" as defined in [BRC-29](/payments/0029.md)) | | `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](/transactions/0008.md), with the [BRC-29](/payments/0029.md) 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](/wallet/0001.md) communications substrate, such as [BRC-5](/wallet/0005.md), [BRC-6](/wallet/0006.md) or [BRC-7](/wallet/0007.md). A specific implementation of this BRC can be seen in the Babbage [Dojo/Ninja](https://projectbabbage.com/docs/dojo) architecture. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bsv.brc.dev/wallet/0050.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.