/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 Details

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

Method & URL

POST /payment

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 Example

Payment Example

curl --location --request POST '{{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 '{{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"
  }
}'

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."
  }
}

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