feat: reason input when canceling incoming payments (#3931)

* feat: add reason input to cancelIncomingPayment

* add test for input reason on canceling payment

* update bruno cancelIncomingPayment to receive reason

* add migration and update naming to cancellationReason

Author: Freedisch

bruno/collections/Rafiki/Rafiki Admin APIs/Cancel Incoming Payment.bru

@@ -15,6 +15,7 @@ body:graphql {
     cancelIncomingPayment(input: $input) {
       payment {
         id
+        cancellationReason
       }
     }
   }
@@ -24,7 +25,8 @@ body:graphql {
 body:graphql:vars {
   {
     "input": {
-      "id": "{{incomingPaymentId}}"
+      "id": "{{incomingPaymentId}}",
+      "cancellationReason": "{{cancellationReason}}"
     }
   }
 }

localenv/mock-account-servicing-entity/generated/graphql.ts

@@ -0,0 +1,19 @@
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.up = function (knex) {
+  return knex.schema.alterTable('incomingPayments', (table) => {
+    table.string('cancellationReason').nullable()
+  })
+}
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function (knex) {
+  return knex.schema.alterTable('incomingPayments', (table) => {
+    table.dropColumn('cancellationReason')
+  })
+}

packages/backend/migrations/20260531185012_add_cancellation_reason_to_incoming_payment.js

@@ -255,7 +255,8 @@ export const cancelIncomingPayment: MutationResolvers<TenantedApolloContext>['ca
 
     const incomingPaymentOrError = await incomingPaymentService.cancel(
       args.input.id,
-      ctx.tenant.id
+      ctx.tenant.id,
+      args.input.cancellationReason
     )
 
     if (isIncomingPaymentError(incomingPaymentOrError)) {
@@ -395,6 +396,10 @@ export function paymentToGraphql(
     receivedAmount: payment.receivedAmount,
     metadata: payment.metadata,
     createdAt: new Date(+payment.createdAt).toISOString(),
-    senderWalletAddress: payment.senderWalletAddress
+    senderWalletAddress: payment.senderWalletAddress,
+    cancellationReason: payment.cancellationReason,
+    cancelledAt: payment.cancelledAt
+      ? new Date(payment.cancelledAt).toISOString()
+      : undefined
   }
 }

packages/backend/src/graphql/generated/graphql.schema.json

@@ -422,6 +422,8 @@ input ApproveIncomingPaymentInput {
 input CancelIncomingPaymentInput {
   "Unique identifier of the incoming payment to be canceled. Note: incoming payment must be PENDING."
   id: ID!
+  "Reason for canceling the incoming payment."
+  cancellationReason: String
 }
 
 input CreateAssetInput {
@@ -1008,6 +1010,10 @@ type IncomingPayment implements BasePayment & Model {
   senderWalletAddress: String
   "The tenant associated with the incoming payment. If not provided, it will be obtained from the signature."
   tenant: Tenant
+  "Reason why the incoming payment was canceled."
+  cancellationReason: String
+  "The date and time that the incoming payment was canceled."
+  cancelledAt: String
 }
 
 type Receiver {

packages/backend/src/graphql/generated/graphql.ts

@@ -113,6 +113,7 @@ export class IncomingPayment
   private receivedAmountValue?: bigint
   public readonly tenantId!: string
   public readonly senderWalletAddress?: string | null
+  public cancellationReason?: string | null
 
   public get completed(): boolean {
     return this.state === IncomingPaymentState.Completed

packages/backend/src/graphql/resolvers/incoming_payment.ts

@@ -312,6 +312,27 @@ describe('Incoming Payment Service', (): void => {
         expect(canceledIncomingPayment.cancelledAt).toBeDefined()
         expect(!canceledIncomingPayment.approvedAt).toBeTruthy()
       })
+
+      it('should cancel incoming payment with reason', async (): Promise<void> => {
+        const reason = 'cancelled by operator'
+        const incomingPayment = await createIncomingPaymentHelper()
+        assert.ok(!isIncomingPaymentError(incomingPayment))
+
+        await IncomingPayment.query(knex)
+          .findOne({ id: incomingPayment.id })
+          .patch({ state: IncomingPaymentState.Pending })
+
+        const canceledIncomingPayment = await incomingPaymentService.cancel(
+          incomingPayment.id,
+          Config.operatorTenantId,
+          reason
+        )
+        assert.ok(!isIncomingPaymentError(canceledIncomingPayment))
+        expect(canceledIncomingPayment.id).toBe(incomingPayment.id)
+        expect(canceledIncomingPayment.cancelledAt).toBeDefined()
+        expect(!canceledIncomingPayment.approvedAt).toBeTruthy()
+        expect(canceledIncomingPayment.cancellationReason).toBe(reason)
+      })
     })
   })
 

packages/backend/src/graphql/schema.graphql

@@ -69,7 +69,8 @@ export interface IncomingPaymentService
   ): Promise<IncomingPayment | IncomingPaymentError>
   cancel(
     id: string,
-    tenantId: string
+    tenantId: string,
+    cancellationReason?: string
   ): Promise<IncomingPayment | IncomingPaymentError>
   complete(
     id: string,
@@ -115,7 +116,8 @@ export async function createIncomingPaymentService(
     get: (options) => getIncomingPayment(deps, options),
     create: (options, trx) => createIncomingPayment(deps, options, trx),
     approve: (id, tenantId) => approveIncomingPayment(deps, id, tenantId),
-    cancel: (id, tenantId) => cancelIncomingPayment(deps, id, tenantId),
+    cancel: (id, tenantId, cancellationReason) =>
+      cancelIncomingPayment(deps, id, tenantId, cancellationReason),
     complete: (id, tenantId) => completeIncomingPayment(deps, id, tenantId),
     getWalletAddressPage: (options) => getWalletAddressPage(deps, options),
     processNext: () => processNextIncomingPayment(deps),
@@ -479,7 +481,8 @@ async function approveIncomingPayment(
 async function cancelIncomingPayment(
   deps: ServiceDependencies,
   id: string,
-  tenantId: string
+  tenantId: string,
+  cancellationReason?: string
 ): Promise<IncomingPayment | IncomingPaymentError> {
   return deps.knex.transaction(async (trx) => {
     const payment = await IncomingPayment.query(trx)
@@ -508,7 +511,8 @@ async function cancelIncomingPayment(
 
     if (!payment.cancelledAt) {
       await payment.$query(trx).patch({
-        cancelledAt: new Date(Date.now())
+        cancelledAt: new Date(Date.now()),
+        cancellationReason: cancellationReason
       })
     }