feat(backend): publish webhooks to POS service if applicable (#3596)

* feat: created the backbone for the card service (#3508)

* Created the backbone for the card service

* Format fix

* feat: add card service to docker compose

---------

Co-authored-by: Nathan Lie <[email protected]>

* feat: Integrate Redis client in Card Service for (requestId, posServiceHost) mapping (#3524)

* Integrate Redis client in Card Service for (requestId, posServiceHost) mapping

* remove unused dep

* prettier fix

* Separate logging params from the message itself

* ttl

* prettier fix

* Rewrite redis service tests to use testcontainers instead of mocks

---------

Co-authored-by: Antoniu Neacsu <[email protected]>

* feat(point-of-sale): added route for registering a POS device (#3555)

* Route for registering a POS device

* Fixed issue addressed in comments, tried to fix the port issue of jest

* Changed test container port to 0, format fix

* feat(backend): publish webhooks to POS service if applicable

* feat: add column to incoming payment

* fix: tests

* feat: add warn log

* fix: better logger requirements for finalizing webhook recipients

* fix: make open payments default reason for incoming payment initialization

* fix: improve optional env var function

* fix: warn log, better optional env, backfill migration, tests

* fix: rebase bugs

* chore: regenerate lockfile

* chore: regenerate gql

* fix: tests

* fix: remove metadata; better tests

* fix: build errors

* fix: tests, add type file

---------

Co-authored-by: oana-lolea <[email protected]>
Co-authored-by: zeppelin44 <[email protected]>
Co-authored-by: Antoniu Neacsu <[email protected]>

Author: 4 people

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('webhooks', function (table) {
+    table.jsonb('metadata').nullable()
+  })
+}
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function (knex) {
+  return knex.schema.alterTable('webhooks', function (table) {
+    table.dropColumn('metadata')
+  })
+}

packages/backend/migrations/20250807210658_add_metadata_to_webhooks.js

@@ -0,0 +1,35 @@
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.up = function (knex) {
+  return knex.schema
+    .alterTable('incomingPayments', function (table) {
+      table.enum('initiatedBy', ['CARD', 'OPEN_PAYMENTS', 'ADMIN'])
+    })
+    .then(() => {
+      return Promise.all([
+        knex.raw(
+          `UPDATE "incomingPayments" SET "initiatedBy" = 'OPEN_PAYMENTS' WHERE "client" IS NOT NULL`
+        ),
+        knex.raw(
+          `UPDATE "incomingPayments" SET "initiatedBy" = 'ADMIN' WHERE "client" IS NULL`
+        )
+      ])
+    })
+    .then(() => {
+      return knex.raw(
+        `ALTER TABLE "incomingPayments" ALTER COLUMN "initiatedBy" SET NOT NULL`
+      )
+    })
+}
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function (knex) {
+  return knex.schema.alterTable('incomingPayments', function (table) {
+    table.dropColumn('initiatedBy')
+  })
+}

packages/backend/migrations/20250814213541_add_intiated_by_to_incoming_payment.js

@@ -203,7 +203,20 @@ export const Config = {
     'SEND_TENANT_WEBHOOKS_TO_OPERATOR',
     false
   ),
-  cardServiceUrl: process.env.CARD_SERVICE_URL
+  cardServiceUrl: optional(envString, 'CARD_SERVICE_URL'),
+  posServiceUrl: optional(envString, 'POS_SERVICE_URL')
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function optional<T extends (...args: any[]) => ReturnType<T>>(
+  envGetter: T,
+  envVar: string
+): ReturnType<T> | undefined {
+  try {
+    return envGetter(envVar)
+  } catch (err) {
+    return undefined
+  }
 }
 
 function parseRedisTlsConfig(

packages/backend/src/config/app.ts

@@ -26,6 +26,7 @@ import {
 } from '../../open_payments/payment/combined/model'
 import { getPageTests } from './page.test'
 import { createTenant } from '../../tests/tenant'
+import { IncomingPaymentInitiationReason } from '../../open_payments/payment/incoming/types'
 
 describe('Payment', (): void => {
   let deps: IocContract<AppServices>
@@ -84,7 +85,8 @@ describe('Payment', (): void => {
     const incomingPayment = await createIncomingPayment(deps, {
       walletAddressId: inWalletAddressId,
       client: client,
-      tenantId: Config.operatorTenantId
+      tenantId: Config.operatorTenantId,
+      initiationReason: IncomingPaymentInitiationReason.OpenPayments
     })
 
     const query = await appContainer.apolloClient

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

@@ -1,6 +1,10 @@
 import { ApolloError, gql } from '@apollo/client'
 import { getPageTests } from './page.test'
-import { createTestApp, TestContainer } from '../../tests/app'
+import {
+  createApolloClient,
+  createTestApp,
+  TestContainer
+} from '../../tests/app'
 import { IocContract } from '@adonisjs/fold'
 import { AppServices } from '../../app'
 import { initIocContainer } from '../..'
@@ -17,6 +21,7 @@ import {
   IncomingPayment as IncomingPaymentModel,
   IncomingPaymentState
 } from '../../open_payments/payment/incoming/model'
+import { IncomingPaymentInitiationReason } from '../../open_payments/payment/incoming/types'
 import {
   IncomingPayment,
   IncomingPaymentResponse,
@@ -29,6 +34,7 @@ import {
 } from '../../open_payments/payment/incoming/errors'
 import { Amount, serializeAmount } from '../../open_payments/amount'
 import { GraphQLErrorCode } from '../errors'
+import { createTenant } from '../../tests/tenant'
 
 describe('Incoming Payment Resolver', (): void => {
   let deps: IocContract<AppServices>
@@ -81,7 +87,8 @@ describe('Incoming Payment Resolver', (): void => {
             description: `IncomingPayment`,
             externalRef: '#123'
           },
-          tenantId
+          tenantId,
+          initiationReason: IncomingPaymentInitiationReason.Admin
         }),
       pagedQuery: 'incomingPayments',
       parent: {
@@ -122,7 +129,8 @@ describe('Incoming Payment Resolver', (): void => {
           metadata,
           expiresAt,
           incomingAmount,
-          tenantId
+          tenantId,
+          initiationReason: IncomingPaymentInitiationReason.Admin
         })
 
         const createSpy = jest
@@ -171,7 +179,11 @@ describe('Incoming Payment Resolver', (): void => {
               query.data?.createIncomingPayment
           )
 
-        expect(createSpy).toHaveBeenCalledWith({ ...input, tenantId })
+        expect(createSpy).toHaveBeenCalledWith({
+          ...input,
+          tenantId,
+          initiationReason: IncomingPaymentInitiationReason.Admin
+        })
         expect(query).toEqual({
           __typename: 'IncomingPaymentResponse',
           payment: {
@@ -241,7 +253,11 @@ describe('Incoming Payment Resolver', (): void => {
           })
         )
       }
-      expect(createSpy).toHaveBeenCalledWith({ ...input, tenantId })
+      expect(createSpy).toHaveBeenCalledWith({
+        ...input,
+        tenantId,
+        initiationReason: IncomingPaymentInitiationReason.Admin
+      })
     })
 
     test('Internal server error', async (): Promise<void> => {
@@ -288,7 +304,107 @@ describe('Incoming Payment Resolver', (): void => {
       }
       expect(createSpy).toHaveBeenCalledWith({
         ...input,
-        tenantId
+        tenantId,
+        initiationReason: IncomingPaymentInitiationReason.Admin
+      })
+    })
+
+    describe('tenant boundaries', (): void => {
+      test('operator can label incoming payment as card payment', async (): Promise<void> => {
+        const createSpy = jest.spyOn(incomingPaymentService, 'create')
+
+        const input = {
+          walletAddressId,
+          isCardPayment: true
+        }
+
+        const query = await appContainer.apolloClient
+          .query({
+            query: gql`
+              mutation CreateIncomingPayment(
+                $input: CreateIncomingPaymentInput!
+              ) {
+                createIncomingPayment(input: $input) {
+                  payment {
+                    id
+                    walletAddressId
+                  }
+                }
+              }
+            `,
+            variables: { input }
+          })
+          .then(
+            (query): IncomingPaymentResponse =>
+              query.data?.createIncomingPayment
+          )
+
+        expect(createSpy).toHaveBeenCalledWith({
+          walletAddressId: input.walletAddressId,
+          tenantId,
+          initiationReason: IncomingPaymentInitiationReason.Card
+        })
+        expect(query).toEqual({
+          __typename: 'IncomingPaymentResponse',
+          payment: {
+            __typename: 'IncomingPayment',
+            id: expect.any(String),
+            walletAddressId
+          }
+        })
+      })
+
+      test('tenant cannot label incoming payment as card payment', async (): Promise<void> => {
+        const tenant = await createTenant(deps)
+        const tenantWalletAddress = await createWalletAddress(deps, {
+          tenantId: tenant.id
+        })
+        const createSpy = jest.spyOn(incomingPaymentService, 'create')
+
+        const input = {
+          walletAddressId: tenantWalletAddress.id,
+          isCardPayment: true
+        }
+
+        const tenantedApolloClient = await createApolloClient(
+          appContainer.container,
+          appContainer.app,
+          tenant.id
+        )
+        const query = await tenantedApolloClient
+          .query({
+            query: gql`
+              mutation CreateIncomingPayment(
+                $input: CreateIncomingPaymentInput!
+              ) {
+                createIncomingPayment(input: $input) {
+                  payment {
+                    id
+                    walletAddressId
+                  }
+                }
+              }
+            `,
+            variables: { input }
+          })
+          .then(
+            (query): IncomingPaymentResponse =>
+              query.data?.createIncomingPayment
+          )
+
+        expect(createSpy).toHaveBeenCalledWith({
+          walletAddressId: input.walletAddressId,
+          tenantId: tenant.id,
+          initiationReason: IncomingPaymentInitiationReason.Admin
+        })
+        expect(query).toEqual({
+          __typename: 'IncomingPaymentResponse',
+          payment: {
+            __typename: 'IncomingPayment',
+            id: expect.any(String),
+            walletAddressId: tenantWalletAddress.id
+          }
+        })
       })
     })
   })
@@ -307,7 +423,8 @@ describe('Incoming Payment Resolver', (): void => {
           assetCode: asset.code,
           assetScale: asset.scale
         },
-        tenantId
+        tenantId,
+        initiationReason: IncomingPaymentInitiationReason.Admin
       })
     }
 
@@ -484,7 +601,8 @@ describe('Incoming Payment Resolver', (): void => {
           metadata,
           expiresAt,
           incomingAmount,
-          tenantId
+          tenantId,
+          initiationReason: IncomingPaymentInitiationReason.Admin
         })
         const input = {
           id: payment.id,

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

@@ -6,6 +6,7 @@ import {
   QueryResolvers
 } from '../generated/graphql'
 import { IncomingPayment } from '../../open_payments/payment/incoming/model'
+import { IncomingPaymentInitiationReason } from '../../open_payments/payment/incoming/types'
 import {
   isIncomingPaymentError,
   errorToCode,
@@ -97,14 +98,25 @@ export const createIncomingPayment: MutationResolvers<ForTenantIdContext>['creat
       throw new Error('Missing tenant id to create incoming payment')
     }
 
+    if (!ctx.isOperator && args.input.isCardPayment) {
+      ctx.logger.warn(
+        { input: args.input, tenant: ctx.tenant },
+        'non-operator cannot create card payment'
+      )
+    }
+
     const incomingPaymentOrError = await incomingPaymentService.create({
       walletAddressId: args.input.walletAddressId,
       expiresAt: !args.input.expiresAt
         ? undefined
         : new Date(args.input.expiresAt),
       incomingAmount: args.input.incomingAmount,
       metadata: args.input.metadata,
-      tenantId
+      tenantId,
+      initiationReason:
+        ctx.isOperator && args.input.isCardPayment
+          ? IncomingPaymentInitiationReason.Card
+          : IncomingPaymentInitiationReason.Admin
     })
     if (isIncomingPaymentError(incomingPaymentOrError)) {
       throw new GraphQLError(errorToMessage[incomingPaymentOrError], {