/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	Gifts, vouchers or punch cards being redeemed in this transaction	Asset	N
appliedDeals	Deals the POS already applied, reported for the record	Discount	N

Method & URL

POST /transaction

See API Servers for the base URL to use in place of {{your-server}}.

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,
    "otherDiscountsTotal": 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!"
  }
}

Error Codes

Code	Description
203	Member not found
402	Missing confirmationCode for cancel
520	Duplicate transaction ID
521	Asset does not belong to this member
522	Asset already used
523	Campaign not found
524	Asset expired
526	Campaign inactive
530	Error saving purchase
531	Member has not given consent

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