Acknowledge and Reward

Overview

Acknowledge and reward is a process that executed on difference service even on difference machine, so the process need an transactional mechanism to ensure acknowledge and reward operations execute sequencially in multi threads/processes environment.

Some methods can be used:

• Execute operations in a FIFO queue
• Using locking mechanism on supported atomic update query

Payment service try to implement locking mechanism to easily support transactional for acknowledge and reward operations.

Sequence diagrams

Related APis

VERD	Endpoint	Parameters	Data	Response	Desc
POST	/api/payment-locks		EntityLockAcquireDto	EntityLock	Lock an entity
DELETE	/api/payment-locks		EntityLockReleaseDto	EntityLockReleaseResult	Release lock

export class EntityLock {
  id: string;
  entityId: string;
  callerId: string;
  expiresAt: Date;
  createdAt: Date;
}

export class EntityLockAcquireDto {
  // Entity id to lock
  entityId: string;

  // [Optional] Custom call id
  callerId?: string;

  // Number of seconds for the lock to expires
  expiresInSeconds?: number;
}

export class EntityLockReleaseDto {
  // Lock id to release
  lockId: string;

  // Entity id for unlock confirmation
  entityId: string;
}

export class EntityLockReleaseResult {
  // Success ?
  success: boolean;

  // Message
  message: string;
}

VERD	Endpoint	Parameters	Data	Response	Desc
POST	/api/orders/acknowledge/:orderId	orderId		Order	Acknowledge an order

Process flows

Step 1: Lock order using lock api

Call POST /api/payment-locks

with data

{
  "entityId": "61031169186479153",
  "expiresInSeconds": 300
}

will response

{
  "entityId": "61031169186479153",
  "callerId": "61376123809530760",
  "expiresAt": "2023-07-04T18:34:36.165Z",
  "id": "61376133336414598",
  "createdAt": "2023-07-04T18:29:37.120Z"
}

Step 2: Acknowledge order

Call POST /api/orders/acknowledge/:orderId

will response

{
  "id": "61031169186479153",
  "userId": "1",
  "status": "ACKNOWLEDGED",
  "subTotal": 10.99,
  "currencyCode": "USD",
  "note": "This is order",
  "acknowledgedAt": "2023-07-04T18:23:59.860Z"
}

Step 3: Reward the item on game/app code

Do the reward yourself

Step 4: Release order lock

Call DELETE /api/payment-locks

with data

{
  "lockId": "61376133336414598",
  "entityId": "61031169186479153"
}