Confirm Redemption

📋

Optional API - Receive final confirmation when a redemption is completed or reverted.

This API notifies your system about the final status of a redemption, including whether the user successfully claimed their $YGG tokens or if the redemption was reverted.

Endpoint Details

Method: POST
Path: /confirm-redemption
Content-Type: application/json

POST https://partner-api.example.com/confirm-redemption

Request Format

Headers

Header	Description	Example
`X-API-KEY`	Your API key	`your_api_key`
`X-API-REQUEST`	Unique UUID v7	`01987d64-6519-747b-9200-beba98700464`
`X-API-SIGNATURE`	HMAC signature	`92aa703cc483ea2cc90488c05e699179...`
`Content-Type`	Must be `application/json`	`application/json`

Request Body

{
  "address": "0xabcd....a",
  "deductPoints": 1000,
  "usdAmount": 5.000000,
  "yggAmount": 50.000000,
  "priceYggUsd": 0.100000,
  "yggRedemptionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "claimed",
  "txnConfirmed": true,
  "txnHash": "0x123456789abcdef...",
  "initialAt": "2025-08-06T06:50:32.426Z",
  "pendingAt": "2025-08-06T06:50:32.426Z",
  "claimedAt": "2025-08-06T06:50:32.426Z",
  "revertedAt": null
}

Field	Type	Required	Description
`address`	string	✅	User's wallet address
`deductPoints`	integer	✅	Original deduction amount
`usdAmount`	number	✅	USD amount redeemed
`yggAmount`	number	✅	$YGG amount redeemed
`priceYggUsd`	number	✅	YGG-USD price at redemption time
`yggRedemptionId`	string	✅	YGG redemption UUID
`status`	string	✅	`"claimed"` or `"reverted"`
`txnConfirmed`	boolean	✅	Whether transaction is confirmed on-chain
`txnHash`	string	❓	On-chain transaction hash (if claimed)
`initialAt`	string	✅	ISO timestamp when redemption started
`pendingAt`	string	✅	ISO timestamp when processing began
`claimedAt`	string	❓	ISO timestamp when claimed (null if reverted)
`revertedAt`	string	❓	ISO timestamp when reverted (null if claimed)

Status Values

Claimed Status

When status: "claimed", the redemption was successful:

{
  "status": "claimed",
  "txnConfirmed": true,
  "txnHash": "0x123456789abcdef...",
  "claimedAt": "2025-08-06T06:52:15.789Z",
  "revertedAt": null
  // other fields
}

User successfully received $YGG tokens
Transaction is confirmed on blockchain
txnHash contains the proof of transfer

Response Format

Success Response

HTTP Status: 200 OK

{
  "success": true
}

✅

No additional response data is required. A simple success confirmation is sufficient.

Use Cases

This confirmation API is useful for:

Analytics & Reporting - Track successful vs failed redemptions
User Notifications - Inform users when their redemption completes
Reconciliation - Match your deduction records with final outcomes
Customer Support - Provide transaction hashes for user inquiries
Audit Compliance - Maintain complete redemption lifecycle records

Example Implementation

app.post('/confirm-redemption', async (req, res) => {
  try {
    // Validate authentication
    if (!validateAuth(req.headers)) {
      return res.json({
        success: false,
        errorCode: 'ERR-AUTH-FAILED',
        errorMessage: 'Authentication failed'
      });
    }
    
    const {
      address,
      deductPoints,
      yggRedemptionId,
      status,
      txnConfirmed,
      txnHash,
      initialAt,
      pendingAt,
      claimedAt,
      revertedAt
    } = req.body;
    
    // Find the redemption record
    const redemption = await findRedemptionById(yggRedemptionId);
    if (!redemption) {
      return res.json({
        success: false,
        errorCode: 'ERR-REDEMPTION-NOT-FOUND',
        errorMessage: 'Redemption not found'
      });
    }
    
    // Update redemption status
    await updateRedemptionStatus(yggRedemptionId, {
      status,
      txnConfirmed,
      txnHash,
      claimedAt,
      revertedAt
    });
    
    // Optional: Trigger notifications or analytics
    if (status === 'claimed') {
      await notifyUserSuccess(address, txnHash);
      await recordSuccessMetrics(redemption);
    } else {
      await notifyUserFailure(address, 'redemption-reverted');
      await recordFailureMetrics(redemption);
    }
    
    res.json({
      success: true
    });
    
  } catch (error) {
    console.error('Confirmation error:', error);
    res.json({
      success: false,
      errorCode: 'ERR-INTERNAL',
      errorMessage: 'Internal server error'
    });
  }
});

Database Schema Example

-- Add confirmation tracking to your redemptions table
ALTER TABLE redemptions ADD COLUMN final_status VARCHAR(20);
ALTER TABLE redemptions ADD COLUMN txn_hash VARCHAR(66);
ALTER TABLE redemptions ADD COLUMN txn_confirmed BOOLEAN DEFAULT FALSE;
ALTER TABLE redemptions ADD COLUMN claimed_at TIMESTAMP NULL;
ALTER TABLE redemptions ADD COLUMN reverted_at TIMESTAMP NULL;
ALTER TABLE redemptions ADD COLUMN confirmed_at TIMESTAMP DEFAULT NOW();
 
-- Index for efficient lookups
CREATE INDEX idx_redemptions_ygg_id ON redemptions(ygg_redemption_id);
CREATE INDEX idx_redemptions_status ON redemptions(final_status);

📈

Analytics Tip: Use this data to calculate success rates, average processing times, and identify common failure patterns.

Revert Points Error Codes