> ## Documentation Index > Fetch the complete documentation index at: https://docs.gameball.co/llms.txt > Use this file to discover all available pages before exploring further. # Redeem Points > Redeem loyalty points as a payment method for customer transactions. Redeem loyalty points as a payment method for customer transactions. Security: Provide both `apikey` and `secretkey` headers. ## OpenAPI ````yaml POST /api/v4.0/integrations/transactions/redeem openapi: 3.1.0 info: title: Gameball API description: >- Gameball REST API v4.0 - Complete API reference for integrating loyalty, gamification, and customer engagement features version: 4.0.0 servers: - url: https://api.gameball.co security: - bearerAuth: [] paths: /api/v4.0/integrations/transactions/redeem: post: description: >- This API enables customers to redeem loyalty points as a payment method in Gameball, allowing them to use points in place of monetary value during transactions. By providing details such as customerId and amount, this endpoint facilitates point-based redemptions within the purchase process. requestBody: required: true content: application/json: schema: type: object required: - customerId - transactionId - transactionTime properties: customerId: type: string description: >- Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_12345abc email: type: string description: >- Customer's email address. This is required if your account uses email-based channel merging. example: john.doe@example.com mobile: type: string description: >- Customer's mobile number. This is required if your account uses mobile-based channel merging. example: '+1234567890' transactionId: type: string description: >- A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn98765 transactionTime: type: string format: date-time description: >- The time of the transaction in your system (e.g., order datetime, invoice datetime). example: '2024-10-11T10:57:43.382Z' amount: type: number description: >- The actual monetary value the customer wants to redeem. This will be deducted from their points balance based on the redemption factor. For instance, if the customer wants to redeem $10 and the redemption factor is 0.1, then 100 points will be deducted from their balance to cover this amount. Note: Only one of amount, points, or holdReference must be provided for the redemption. example: 10 points: type: integer description: >- The number of points the customer wants to redeem from their balance. This allows the customer to specify exactly how many points they wish to use. Note: Only one of amount, points, or holdReference must be provided for the redemption. example: 0 holdReference: type: string description: >- A unique reference obtained from the Hold Points API. If provided, the points in the hold will be used. It is used when points have been reserved previously, allowing the system to redeem the points that are on hold. Example: If you previously used the Hold Points API to hold 100 points, you would provide the holdReference obtained from that hold transaction to redeem the 100 points that were held. Note: Only one of amount, points, or holdReference must be provided for the redemption. example: null merchant: type: object description: >- This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place. properties: uniqueId: type: string description: Unique identifier for the merchant. name: type: string description: Name of the merchant. branch: type: object required: - uniqueId properties: uniqueId: type: string description: >- Unique identifier for the branch where the transaction took place. name: type: string description: Name of the branch where the transaction took place. hash: type: string description: >- A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. For more details on how the hash is generated and validated, refer to the Customer's Hash section. example: HASH1234 otp: type: string description: >- One-time password (OTP) required if OTP is enabled for the customer. This OTP serves as an additional layer of security for verifying the redemption request. For more details on how OTP works and when it is required, refer to the Transaction Validation section. example: '123456' ignoreOTP: type: boolean description: >- This attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP. example: false reason: type: string maxLength: 255 description: >- An optional reason for the redemption. This can be used to provide context about why the customer is redeeming points (e.g., 'Discount on order', 'Loyalty reward'). The reason will be stored with the transaction and displayed in the dashboard transaction details. example: 'Discount on order #12345' responses: '200': description: Points redeemed successfully content: application/json: schema: type: object properties: customerId: type: string description: >- Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_12345abc gameballTransactionId: type: string description: >- Unique identifier for the transaction in the Gameball system. example: '11034734' transactionId: type: string description: >- A unique identifier for the transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn98765 redeemAmount: type: number description: >- The amount of money redeemed in the transaction, based on the points redeemed. Example: If a customer redeems points equivalent to $10 off their purchase, the redeemAmount will be 10.0. example: 10 redeemEquivalentPoints: type: number description: >- The number of points used to redeem the specified monetary value in the transaction. Example: If a customer uses 100 points to redeem $10, the redeemEquivalentPoints will be 100. example: 100 reason: type: string description: >- The reason provided for the redemption, if one was included in the request. example: 'Discount on order #12345' security: - apiKey: [] secretKey: [] components: securitySchemes: bearerAuth: type: http scheme: bearer apiKey: type: apiKey in: header name: apikey secretKey: type: apiKey in: header name: secretkey ````