/transaction

Overview

This endpoint is used to submit a completed transaction or to cancel a previously submitted transaction using its confirmation code.

When to Use This Endpoint

Use this endpoint in the following cases:

• A member or non-member completes a purchase
• You want to log the transaction for segmentation, rewards, or asset usage
• A previously submitted transaction needs to be canceled

note

Submitting every transaction—whether linked to a member or not—is required to maintain accurate loyalty records and analytics.

warning

Canceling a transaction does not reverse any associated loyalty payment. Use the /payment endpoint separately for payment cancellation.

Request Details

Field	Description	Type	Mandatory
member	Member making the transaction	Member	N
transaction	Transaction details to be recorded	Transaction	Y
usedAssets	Loyalty assets being used for this transaction	Item	N
appliedDeals	Any deals/combos applied during the transaction	Discount	N

Method & URL

POST /transaction

Headers

Header	Type	Required	Description
x-api-key	string	Yes	API key used for authentication
x-source-type	string	Yes	Source of the transaction (POS, Web, Kiosk)
x-source-name	string	Yes	Integration or client system name
x-pos-id	string	Yes	Unique POS terminal identifier
x-branch-id	string	Yes	Branch or store location identifier

Request Example

curl --location --request POST 'https://{{your-server}}/v1/transaction' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: POS' \
--header 'x-source-name: pos_terminal_01' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--data-raw '{
  "member": {
    "phoneNumber": "123456789"
  },
  "transaction": {
    "transactionId": "TX-DEMO-1001",
    "dateTime": "2025-07-01T13:45:00Z",
    "totalAmount": 3000,
    "totalTaxAmount": 500,
    "totalGeneralDiscount": 200,
    "items": [
      {
        "lineId": "1",
        "code": "PZ001",
        "name": "Pizza Margherita",
        "departmentCode": "FOOD",
        "departmentName": "Main Dishes",
        "quantity": 1,
        "subtotal": 1700,
        "total": 1500,
        "tags": ["promo"]
      },
      {
        "lineId": "2",
        "code": "DRK001",
        "name": "Soda",
        "departmentCode": "BEV",
        "departmentName": "Beverages",
        "quantity": 1,
        "subtotal": 1500,
        "total": 1500,
        "tags": []
      }
    ],
    "payments": [
      {
        "type": "CREDITCARD",
        "amount": 2000
      },
      {
        "type": "POINTS",
        "amount": 1000
      }
    ],
    "employee": "Cashier 1"
  },
  "usedAssets": [
    {
      "key": "birthday-gift-2025",
      "code": "BIRTHDAY25",
      "appliedAmount": 500
    }
  ],
  "appliedDeals": [
    {
      "key": "combo-meal-1",
      "appliedAmount": 200
    }
  ]
}'

Success Response

{
  "status": "success",
  "data": {
    "confirmationCode": "TRX-CONFIRM-20250701",
    "token": "abc123xyz456",
    "awardedPoints": 100,
    "updatedBalances": {
      "points": 1200,
      "credit": 500
    },
    "appliedDeals": [
      {
        "key": "combo-meal-1",
        "appliedAmount": 200
      }
    ],
    "usedAssets": [
      {
        "key": "birthday-gift-2025",
        "code": "BIRTHDAY25",
        "appliedAmount": 500
      }
    ]
  }
}

Error Response Examples

Used Asset Already Consumed

{
  "status": "error",
  "error": {
    "code": "522",
    "message": "Used asset is already used."
  }
}

Member Not Found

{
  "status": "error",
  "error": {
    "code": "203",
    "message": "Cannot find any member with the given identifier!"
  }
}

Field Reference

Field	Type	Description
member.phoneNumber	string	Optional. Used to link transaction to a loyalty member
transaction.transactionId	string	Unique transaction identifier
transaction.items[]	array	List of purchased items
transaction.payments[]	array	List of payments with types and amounts
usedAssets[]	array	Optional. Assets applied to the transaction
appliedDeals[]	array	Optional. Deals applied and their value
employee	string	Name or ID of the cashier or terminal operator

Related Use Cases

• Submitting completed member or guest transactions
• Triggering benefit calculation, points, and segmentation logic
• Canceling a transaction by confirmation code