feat(backend): add handlePartialPayment for incoming payments

localenv/mock-account-servicing-entity/app/lib/webhooks.server.ts

@@ -119,7 +119,7 @@ export async function handleOutgoingPaymentCreated(
         input: {
           outgoingPaymentId: payment.id,
           idempotencyKey: uuid(),
-          dataToTransmit: 'sample kyc data'
+          dataToTransmit: acc.name
         }
       }
     })

packages/backend/src/graphql/resolvers/liquidity.test.ts

@@ -3528,19 +3528,11 @@ describe('Liquidity Resolvers', (): void => {
           assert.ok(outgoingPayment.debitAmount)
           await expect(depositSpy).toHaveBeenCalledWith({
             id: eventId,
-            account: expect.any(OutgoingPayment),
+            account: expect.objectContaining({
+              dataToTransmit
+            }),
             amount: outgoingPayment.debitAmount.value
           })
-          await expect(
-            accountingService.getBalance(outgoingPayment.id)
-          ).resolves.toEqual(outgoingPayment.debitAmount.value)
-          await expect(
-            OutgoingPayment.query(knex).findById(outgoingPayment.id)
-          ).resolves.toEqual(
-            expect.objectContaining({
-              dataToTransmit
-            })
-          )
         })
 
         test("Can't deposit for non-existent outgoing payment id", async (): Promise<void> => {

packages/backend/src/graphql/schema.graphql

@@ -604,7 +604,7 @@ input DepositOutgoingPaymentLiquidityInput {
   outgoingPaymentId: String!
   "Unique key to ensure duplicate or retried requests are processed only once. For more information, refer to [idempotency](https://rafiki.dev/apis/graphql/admin-api-overview/#idempotency)."
   idempotencyKey: String!
-  "Data to be encrypted and sent to the receiver."
+  "Data to transmit to the recipient during payment."
   dataToTransmit: String
 }
 

packages/backend/src/open_payments/payment/incoming/model.ts

@@ -19,7 +19,8 @@ import { IncomingPaymentInitiationReason } from './types'
 export enum IncomingPaymentEventType {
   IncomingPaymentCreated = 'incoming_payment.created',
   IncomingPaymentExpired = 'incoming_payment.expired',
-  IncomingPaymentCompleted = 'incoming_payment.completed'
+  IncomingPaymentCompleted = 'incoming_payment.completed',
+  IncomingPaymentPartialPaymentReceived = 'incoming_payment.partial_payment_received'
 }
 
 export enum IncomingPaymentState {

packages/backend/src/open_payments/payment/incoming/service.test.ts

@@ -1,3 +1,4 @@
+import { createDecipheriv, randomBytes } from 'node:crypto'
 import assert from 'assert'
 import { faker } from '@faker-js/faker'
 import { Knex } from 'knex'
@@ -1118,6 +1119,113 @@ describe('Incoming Payment Service', (): void => {
     })
   })
 
+  describe('processPartialPayment', (): void => {
+    let incomingPayment: IncomingPayment
+
+    const dbEncryptionOverride: Partial<IAppConfig> = {
+      dbEncryptionSecret: randomBytes(32).toString('base64')
+    }
+
+    beforeEach(async (): Promise<void> => {
+      incomingPayment = await createIncomingPayment(deps, {
+        walletAddressId,
+        tenantId,
+        initiationReason: IncomingPaymentInitiationReason.Admin
+      })
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    test(
+      'can process partial payment for incoming payment',
+      withConfigOverride(
+        () => config,
+        dbEncryptionOverride,
+        async (): Promise<void> => {
+          const dataToTransmit = JSON.stringify({
+            data: faker.internet.email()
+          })
+          const processedPayment =
+            await incomingPaymentService.processPartialPayment(
+              incomingPayment.id,
+              dataToTransmit
+            )
+          assert.ok(!isIncomingPaymentError(processedPayment))
+
+          const webhookEvent = await IncomingPaymentEvent.query(knex)
+            .where({
+              incomingPaymentId: processedPayment.id,
+              type: IncomingPaymentEventType.IncomingPaymentPartialPaymentReceived
+            })
+            .withGraphFetched('webhooks')
+            .first()
+          assert.ok(webhookEvent)
+          assert.ok(webhookEvent.data.dataToTransmit)
+
+          const webhookDataToTransmit = JSON.parse(
+            webhookEvent.data.dataToTransmit as string
+          )
+          const decipher = createDecipheriv(
+            'aes-256-gcm',
+            Uint8Array.from(
+              Buffer.from(config.dbEncryptionSecret as string, 'base64')
+            ),
+            webhookDataToTransmit.iv
+          )
+          decipher.setAuthTag(
+            Uint8Array.from(Buffer.from(webhookDataToTransmit.tag, 'base64'))
+          )
+          let decrypted = decipher.update(
+            webhookDataToTransmit.cipherText,
+            'base64',
+            'utf8'
+          )
+          decrypted += decipher.final('utf8')
+
+          expect(decrypted).toEqual(dataToTransmit)
+          expect(webhookEvent.webhooks).toHaveLength(1)
+        }
+      )
+    )
+
+    test(
+      'does not encrypt transmitted data without configured encryption secret',
+      withConfigOverride(
+        () => config,
+        {
+          ...dbEncryptionOverride,
+          dbEncryptionSecret: undefined
+        },
+        async (): Promise<void> => {
+          const dataToTransmit = JSON.stringify({
+            data: faker.internet.email()
+          })
+
+          const processedPayment =
+            await incomingPaymentService.processPartialPayment(
+              incomingPayment.id,
+              dataToTransmit
+            )
+          assert.ok(!isIncomingPaymentError(processedPayment))
+
+          const webhookEvent = await IncomingPaymentEvent.query(knex)
+            .where({
+              incomingPaymentId: processedPayment.id,
+              type: IncomingPaymentEventType.IncomingPaymentPartialPaymentReceived
+            })
+            .withGraphFetched('webhooks')
+            .first()
+          assert.ok(webhookEvent)
+
+          expect(webhookEvent.data.dataToTransmit).toEqual(dataToTransmit)
+          expect(webhookEvent.webhooks).toHaveLength(1)
+        }
+      )
+    )
+  })
+
   describe('getPage', (): void => {
     let receiverWalletAddress: MockWalletAddress
     let assetId: string

packages/backend/src/open_payments/payment/incoming/service.ts

@@ -17,7 +17,7 @@ import {
 import { Amount } from '../../amount'
 import { IncomingPaymentError } from './errors'
 import { IAppConfig } from '../../../config/app'
-import { poll } from '../../../shared/utils'
+import { encryptDbData, poll } from '../../../shared/utils'
 import { AssetService } from '../../../asset/service'
 import { finalizeWebhookRecipients } from '../../../webhook/service'
 import { Pagination, SortOrder } from '../../../shared/baseModel'
@@ -78,6 +78,10 @@ export interface IncomingPaymentService
   update(
     options: UpdateOptions
   ): Promise<IncomingPayment | IncomingPaymentError>
+  processPartialPayment(
+    id: string,
+    dataToTransmit?: string
+  ): Promise<IncomingPayment | IncomingPaymentError>
 }
 
 export interface ServiceDependencies extends BaseService {
@@ -107,7 +111,9 @@ export async function createIncomingPaymentService(
     getWalletAddressPage: (options) => getWalletAddressPage(deps, options),
     processNext: () => processNextIncomingPayment(deps),
     update: (options) => updateIncomingPayment(deps, options),
-    getPage: (options) => getPage(deps, options)
+    getPage: (options) => getPage(deps, options),
+    processPartialPayment: (id, dataToTransmit) =>
+      processPartialPayment(deps, id, dataToTransmit)
   }
 }
 
@@ -549,6 +555,43 @@ async function addReceivedAmount(
   return payment
 }
 
+async function processPartialPayment(
+  deps: ServiceDependencies,
+  id: string,
+  dataToTransmit?: string
+): Promise<IncomingPayment | IncomingPaymentError> {
+  const { config, knex } = deps
+
+  const incomingPayment = await IncomingPayment.query(knex)
+    .findById(id)
+    .withGraphFetched('asset')
+  if (!incomingPayment) return IncomingPaymentError.UnknownPayment
+
+  await IncomingPaymentEvent.query(knex).insertGraph({
+    incomingPaymentId: incomingPayment.id,
+    type: IncomingPaymentEventType.IncomingPaymentPartialPaymentReceived,
+    data: {
+      ...incomingPayment.toData(0n),
+      dataToTransmit:
+        dataToTransmit && config.dbEncryptionSecret
+          ? encryptDbData(dataToTransmit, config.dbEncryptionSecret)
+          : dataToTransmit
+    },
+    tenantId: incomingPayment.tenantId,
+    webhooks: finalizeWebhookRecipients(
+      {
+        tenantIds: [incomingPayment.tenantId],
+        sendToPosService:
+          incomingPayment.initiatedBy === IncomingPaymentInitiationReason.Card
+      },
+      deps.config,
+      deps.logger
+    )
+  })
+
+  return incomingPayment
+}
+
 async function getPage(
   deps: ServiceDependencies,
   options?: GetPageOptions