Redemption Intent (Partners)

The Redemption Intent object represents a customer's attempt to make a payment using one or more vouchers. It is a core part of the voucher-based payment workflow and is designed to track, process, and confirm the intent to pay for a partner's goods or services via voucher redemption.

Optional: You can specify a country_code when creating a Redemption Intent. To get valid country codes, refer to the Get All Countries endpoint (no authentication required).

💡 VAT Reporting: Country codes are used for VAT OSS reporting. Learn how to generate VAT reports from your Partner Panel.

🧾 How It Works

When a Redemption Intent is created:

It is initially marked as pending.

An authorization link is generated — this is a custom checkout page where the customer is expected to input their voucher codes.

Vouchers can be purchased from authorized resellers of CIAO. For testing, you can use test vouchers to complete the redemption intent.
Note: Test vouchers are not real.

The system waits for the customer to complete the redemption process.

Once the customer successfully redeems voucher(s) equivalent to the required amount:

The Redemption Intent is marked as success.

The customer is redirected to the provided callback_url, with the reference of the Redemption Intent appended as a query parameter.

The partner is expected to call the Verify Redemption Intent endpoint to confirm the final status and amount.

📨 Webhook Delivery

Webhooks provide real-time notifications when a Redemption Intent changes state (e.g., on successful redemption). They are sent to the webhook_url configured in the Partner Dashboard at the time the intent is created. This allows you to process successful redemptions programmatically, even if the customer does not return to your site.

🔔 Event Types

Event	Trigger Condition
`redemption-intent.success`	Redemption Intent successfully redeemed
`redemption-intent.chargeback`	Redemption Intent Charged back

📦 Webhook Payload

Webhook requests are sent as a JSON body using the following structure:

{
  "event": "redemption-intent.success",
  "data": {
    "reference": "RDM-01K2F8ZC0QTFS938ZXN017YY4A",
    "amount": 5000,
    "status": "success",
    "authorization_url": "https://app.ciao.cx/checkout/SFplEFvdoVFI4k5",
    "access_code": "SFplEFvdoVFI4k5",
    "callback_url": "https://yourdomain.com/payment/callback",
    "customer": {
      "email": "john@example.com"
    },
     "metadata": {
      "order_id": "ORD-7890"
    },
    "redeemed_at": "2025-06-30T10:45:00Z",
    "created_at": "2025-06-30T10:30:00Z",
    "updated_at": "2025-06-30T10:45:00Z",
  }
}

{
 "event": "redemption-intent.chargeback",
 "data": {
   "reference": "RDM-01K2F8ZC0QTFS938ZXN017YY4A",
   "amount": 5000,
   "customer": {
     "email": "john@example.com"
   },
   "chargeback": {
     "reference":"RDM-CHARGEBACK-01K4K82TY4PRCQE6GNXQX7DDBK",
     "reason":"fraud",
     "created_at": "2025-09-08T00:43:24.000000Z"
   },
   "metadata": {
     "order_id": "ORD-7890"
   },
   "redeemed_at": "2025-06-30T10:45:00Z",
   "created_at": "2025-06-30T10:30:00Z",
   "updated_at": "2025-06-30T10:45:00Z"
 }
}

🔐 Signature Verification

Every webhook request includes a signature in the header:

X-CIAO-SIGNATURE: f8e93bc8ac4a21bd...

This is an HMAC SHA256 signature generated using the raw JSON payload and your API secret key:

📌 The secretKey used is the same key that was used to initialize the Redemption Intent.

✅ How to Verify the Webhook (PHP Example)

Use hash_equals to prevent timing attacks. Always validate before trusting the payload.

🔁 Webhook Retry Policy

Webhook deliveries follow this retry schedule until a 2xx success response is received:

Every minute for the first 4 attempts

Then every hour for up to 24 hours

After 24 hours or a successful response, retries stop

Always return a 200 OK quickly and offload any heavy processing to a queue or background job.

📌 Reminder

You should always verify the reference from the callback using the Verify Redemption Intent endpoint. Just because the callback_url was visited doesn't prove that transaction was successful. When verifying the status of a transaction, you should also verify the amount to ensure it matches the value of the service you are delivering. If the amount doesn't match, do not deliver value to the customer.

Redemption Intent

🧾 How It Works#

📨 Webhook Delivery#

🔔 Event Types#

📦 Webhook Payload#

🔐 Signature Verification#

✅ How to Verify the Webhook (PHP Example)#

🔁 Webhook Retry Policy#

📌 Reminder#