/payment

Description

This endpoint allows a member to pay for a transaction using their loyalty balance (credit or points), or cancel a previously confirmed payment using a confirmation code.

Purpose

• To allow members to redeem credit or points during a purchase
• To cancel a previously confirmed loyalty payment

When to Use

• To finalize a loyalty-based payment at checkout
• To reverse a previously processed loyalty transaction

Request Format

Method & URL

POST /payment

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	Client or integration source name
x-pos-id	string	Yes	POS terminal identifier
x-branch-id	string	Yes	Branch or store location identifier

Request Body

Field	Description	Type	Mandatory
member	Member object	Member	Y
payment	Payment info (action, amount, etc.)	Payment	Y
transaction	Transaction context for the payment	Transaction	N

Request Example

Payment Example

curl --location --request POST 'https://{{server}}/v1/payment' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: {{source-type}}' \
--header 'x-source-name: {{source-name}}' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--data-raw '{
  "member": {
    "phoneNumber": "5511122233"
  },
  "payment": {
    "action": "pay",
    "amount": 1500
  },
  "transaction": {
    "transactionId": "TX-LOYALTY-001",
    "dateTime": "2025-06-18T12:00:00Z",
    "totalAmount": 3000,
    "payments": [
      {
        "type": "CREDIT",
        "amount": 1500
      },
      {
        "type": "CASH",
        "amount": 1500
      }
    ],
    "items": [],
    "employee": "Cashier #1"
  }
}'

Cancel Payment Example

curl --location --request POST 'https://{{server}}/v1/payment' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: {{source-type}}' \
--header 'x-source-name: {{source-name}}' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--data-raw '{
  "member": {
    "phoneNumber": "5511122233"
  },
  "payment": {
    "action": "cancel",
    "confirmationCode": "CONF123456",
    "amount": 1000
  }
}'

amount on cancel

amount is required on every action, cancel included, so omitting it returns error 403. On a cancel the API then replaces your value with the original payment's amount, so what you send has no effect on the result.

The sign is currently unsettled between the reference and the code, and is being decided in teco-pos-api#213. Send the field; do not rely on its sign until that closes.

Success Response

{
  "status": "success",
  "data": {
    "payments": [
      {
        "type": "CREDIT",
        "amount": 1500,
        "confirmed": true,
        "confirmationCode": "CONF123456"
      }
    ],
    "wallet": {
      "credit": {
        "balance": 3500,
        "usable": true
      },
      "points": {
        "balance": 1200,
        "usable": false
      }
    }
  }
}

Error Response Examples

Member Not Found

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

Insufficient Credit

{
  "status": "error",
  "error": {
    "code": "407",
    "message": "creditBalance balance for members is insufficient to process the payment!"
  }
}

Used Asset Already Used

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

Error Codes

Code	Description
203	Member not found
401	Invalid payment.action
402	Missing confirmationCode for cancel
403	Missing amount
405	Member has not given consent
406	Verification code required
407	Insufficient balance
408	Amount outside allowed min/max range
410	Payment not found or already cancelled

Field Reference

Field	Type	Description
member.phoneNumber	string	Phone number used to identify the member
payment.action	string	"pay" or "cancel"
payment.amount	number	Amount to redeem using loyalty funds
payment.confirmationCode	string	Code used to cancel a prior payment
transaction	object	Full transaction context including items and payments