/payments

Overview

This endpoint retrieves points or credit transaction history for all members in the business. Unlike /member/payments, this endpoint does not require a specific member to be identified and returns transactions across all members.

When to Use This Endpoint

Use this endpoint in the following cases:

• To generate business-wide reports on points or credit transactions
• To analyze loyalty program usage across all members
• To audit or review all payment activities in the system
• To export transaction data for business intelligence or accounting purposes

Key Considerations

• The budgetType parameter determines whether to retrieve points or credit history
• Results can be filtered by date range using fromDate and toDate
• Pagination is supported through limit and offset parameters
• Default date range is not limited unless specified
• Does not require a specific member to be identified
• Returns transactions with member identification (membershipKey) included

Request Details

Method & URL

POST /payments

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

Headers

Header	Type	Required	Description
x-api-key	string	Yes	API key for authentication
x-source-type	string	Yes	Origin of the request (e.g., POS, Web)
x-source-name	string	Yes	Name of the client or integration system
x-pos-id	string	Yes	POS terminal identifier
x-branch-id	string	Yes	Branch or store location identifier

Request Body

Field	Type	Required	Default	Description
budgetType	string	Yes	—	Type of budget: points or credit
limit	integer	No	40	Max number of records (1-100)
offset	integer	No	0	Number of records to skip for pagination (≥0)
fromDate	string	No	—	Filter start date (ISO 8601 format)
toDate	string	No	—	Filter end date (ISO 8601 format)

Request Example

curl --location --request POST 'https://{{server}}/v1/payments' \
--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 '{
  "budgetType": "points",
  "limit": 20,
  "offset": 0,
  "fromDate": "2024-01-01T00:00:00Z",
  "toDate": "2024-12-31T23:59:59Z"
}'

Success Response

{
  "status": "success",
  "transactions": [
    {
      "transactionId": "confirmation-uuid-or-db-id",
      "createdAt": "2024-06-15T14:30:00.000Z",
      "operation": "AddPoints",
      "type": "Point",
      "amount": 105,
      "membershipKey": "abc123"
    },
    {
      "transactionId": "conf-uuid-2",
      "createdAt": "2024-06-10T12:15:00.000Z",
      "operation": "RedeemPoints",
      "type": "Point",
      "amount": -50,
      "membershipKey": "def456"
    }
  ]
}

Response Fields

Field	Type	Description
status	string	Request status indicator
transactions	array	Array of transaction objects
transactionId	string	Unique identifier for the transaction
createdAt	string	ISO 8601 timestamp of the transaction
operation	string	Operation type: AddPoints, RedeemPoints, AddCredits, RedeemCredits
type	string	Budget type: Point or Credit
amount	number	Transaction amount (positive for add, negative for use)
membershipKey	string	The member's membership key

Error Response Examples

Missing Required Header

{
  "status": "error",
  "error": {
    "code": "101",
    "message": "Missing X-Api-Key header"
  }
}

Invalid Budget Type

{
  "status": "error",
  "error": {
    "code": "1001",
    "message": "Invalid or missing budgetType. Must be 'points' or 'credit'"
  }
}

Invalid Date Format

{
  "status": "error",
  "error": {
    "code": "1002",
    "message": "Invalid fromDate format. Use ISO 8601 format"
  }
}

Error Codes

Code	Description
101	Missing X-Api-Key header
102	Missing X-Source-Type header
103	Missing X-Source-Name header
104	Missing X-Pos-Id header
105	Missing X-Branch-Id header
1001	Invalid or missing budgetType
1002	Invalid fromDate format
1003	Invalid toDate format
1010	Internal server error

Related Use Cases

• Generating business-wide loyalty transaction reports
• Analyzing loyalty program performance and usage patterns
• Auditing all points or credit transactions across the business
• Exporting transaction data for accounting or business intelligence
• Monitoring loyalty program health and member engagement