feat: add Bitcoin L1 deposit-address instruction + refundAddress to quotes

openapi/components/schemas/common/PaymentBitcoinDepositAddressInfo.yaml

@@ -0,0 +1,22 @@
+title: Bitcoin L1 Deposit Address
+type: object
+required:
+  - accountType
+  - address
+properties:
+  accountType:
+    type: string
+    description: Type of payment account or wallet
+    enum:
+      - BITCOIN_L1
+    example: BITCOIN_L1
+  address:
+    type: string
+    description: On-chain Bitcoin (L1) deposit address to send funds to
+    example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
+  network:
+    type: string
+    description: The blockchain network for the deposit address.
+    enum:
+      - BITCOIN
+    example: BITCOIN

openapi/components/schemas/common/PaymentInstructions.yaml

@@ -60,6 +60,7 @@ properties:
     - $ref: ../common/PaymentPolygonWalletInfo.yaml
     - $ref: ../common/PaymentBaseWalletInfo.yaml
     - $ref: ../common/PaymentEthereumWalletInfo.yaml
+    - $ref: ../common/PaymentBitcoinDepositAddressInfo.yaml
     - $ref: ../common/PaymentEmbeddedWalletInfo.yaml
     discriminator:
       propertyName: accountType
@@ -87,6 +88,7 @@ properties:
         POLYGON_WALLET: ../common/PaymentPolygonWalletInfo.yaml
         BASE_WALLET: ../common/PaymentBaseWalletInfo.yaml
         ETHEREUM_WALLET: ../common/PaymentEthereumWalletInfo.yaml
+        BITCOIN_L1: ../common/PaymentBitcoinDepositAddressInfo.yaml
         AED_ACCOUNT: ../common/PaymentAedAccountInfo.yaml
         KES_ACCOUNT: ../common/PaymentKesAccountInfo.yaml
         MWK_ACCOUNT: ../common/PaymentMwkAccountInfo.yaml

openapi/components/schemas/quotes/AccountDestination.yaml

@@ -21,4 +21,10 @@ allOf:
               The payment rail to use for the transfer. Must be one of the rails
               supported by the destination account. If not specified, the system
               will select a default rail.
+      refundAddress:
+        type: string
+        description: >-
+          Optional address the funds are returned to if the payout cannot be
+          completed. Applies to crypto off-ramp destinations.
+        example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
     description: Destination account details

openapi/components/schemas/quotes/RealtimeFundingQuoteSource.yaml

@@ -31,6 +31,13 @@ allOf:
           on, so the correct deposit address can be generated. Example values:
           `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `SPARK`, `LIGHTNING`, `BITCOIN`.
         example: SOLANA
+      refundAddress:
+        type: string
+        description: >-
+          Optional address the deposited funds are returned to if the crypto
+          deposit cannot be routed to complete the payment. Applies to on-chain
+          crypto funding sources.
+        example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
     description: >-
       Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.).
       This will require manual just-in-time funding using `paymentInstructions` in the response.