Card Vault Link

{
  "type": "STORE_CARD",
  "item": {
    "title": "Save your card" // shown on the vault page and payer statement
  }
}

{
  "type": "STORE_CARD",

  "item": {
    "title": "Card activation fee", // shown on the vault page and payer statement
    "description": "A once-off activation fee is charged when your card is saved" // [optional]
  },

  "fee": {
    "amount": "50.00", // one-time fee charged with the 3DS verification; omit to default to "2.00"
    "is_refund": false // [optional] default false — when true, the default R2.00 verification amount is automatically reversed after successful storage; ignored when a custom fee amount is set
  },

  "notification": {
    "email": "me@my-email.co.za", // [optional] email notification when a card is stored
    "webhook_url": "https://merchant.example/webhooks/cards" // webhook on card vault events
  },

  "redirects": {
    "success_url": "https://merchant.example/card-saved?myquery=myparam", // may append &signature=
    "cancel_url": "https://merchant.example/cancel"
  }
}

{
  "type": "MANAGE_CARDS",

  "item": {
    "title": "Manage your cards"
  },

  "manage": {
    "is_allow_add": true, // [optional] default true — payer can add a new card (runs the R2.00 / fee 3DS flow)
    "is_allow_remove": true, // [optional] default true — removing the default card promotes the next card by priority
    "is_allow_set_default": true // [optional] default true — payer can choose their default card and reorder fallbacks
  },

  "notification": {
    "webhook_url": "https://merchant.example/webhooks/cards" // card.stored · card.removed · card.default_changed · card.reordered
  },

  "redirects": {
    "success_url": "https://merchant.example/cards?myquery=myparam",
    "cancel_url": "https://merchant.example/cancel"
  }
}

{
  "type": "STORE_CARD",

  "signature": "secret-key-for-payload", // [optional] shared-secret signature for the payload, see the signature section below

  "item": {
    "title": "Save your card",
    "description": "Securely store your card for future payments"
  },

  // Placement of the newly stored card in the customer's cascade order
  "card": {
    "is_default": false, // [optional] default true for the customer's first card, false otherwise; when true, the existing default card is demoted
    "priority": 2 // [optional] explicit fallback position among non-default cards; ignored when is_default is true; defaults to the end of the cascade order
  },

  "fee": {
    "amount": "50.00",
    "is_refund": false
  },

  "notification": {
    "email": "me@my-email.co.za",
    "webhook_url": "https://merchant.example/webhooks/cards"
  },

  "redirects": {
    "success_url": "https://merchant.example/card-saved?myquery=myparam",
    "cancel_url": "https://merchant.example/cancel"
  },

  "settings": {
    "expiry_time": 1440, // minutes until the vault link lapses — omit when the link never expires (default)
    "max_cards": 3, // [optional] cap on stored cards for this customer; the link shows an error state when the customer is at the limit — omit for no limit
    "is_duplicate_check": true // [optional] default true — rejects storing a card whose PAN fingerprint already exists on this customer
  },

  "customization": {
    "button_text": "Save card", // [optional] primary action button label
    "type": "PAGE", // or "EMBED" for iframe-style hosting or in-app card storage
    "is_display_cancel_button": true,
    "confirmation_message": "Your card has been saved", // [optional] shown after successful storage; otherwise use redirects
    "brand": {
      "primary": "#00DC82",
      "secondary": "#CCCCCC"
    }
  }
}

{
  "type": "STORE_CARD",

  "item": {
    "title": "Save your card"
  },

  "customization": {
    "button_text": "Save card", // [optional]
    "type": "EMBED", // show embedded screen that can be displayed in an iFrame or WebView, this will also send message events instead of a redirect
    "is_display_cancel_button": false, // hide the cancel button, if true will trigger a 'card.cancelled' message
    "brand": {
      "primary": "#00DC82", // brand according to your app
      "secondary": "#CCCCCC"
    }
  }
}

{
  "source": "kwik-payments",
  "event": "card.stored",
  "sessionId": "ses_abc123...",
  "customerId": "cus_abc123...",
  "cardId": "crd_abc123...",
  "transactionId": "tra_abc123...",
  "status": "ACTIVE"
}

{
  "source": "kwik-payments",
  "event": "card.failed",
  "sessionId": "ses_abc123...",
  "customerId": "cus_abc123...",
  "transactionId": "tra_abc123...",
  "status": "DECLINED",
  "message": "Your card could not be verified due to insufficient funds"
}

{
    "status": true,
    "result": {
      "id": "cdl_HVpCeoNys1f22X7QcuWHY",
      "session_id": "ses_G-xkVKoxHgEBrY8suKgR3",
      "customer_id": "cus_abc123...",
      "type": "STORE_CARD",
      "fee_amount": "2.00",
      "currency": "ZAR",
      "link_url": "https://pay.kwik.co.za/card-vault/cs_test_a1b2c3",
      "expires_at": "2026-07-06T12:30:00Z"
    }
}

{
  // card.stored · card.failed · card.removed · card.default_changed · card.reordered · card.link_expired
  "event": "card.stored",
  "data": [
    {
      "card": {
        "id": "crd_SFq2E9LskQimPkf2mRqnV",
        "customer_id": "cus_abc123...",
        "session_id": "ses_G-xkVKoxHgEBrY8suKgR3",
        "brand": "VISA",
        "last_four": "4242",
        "expiry_month": "09",
        "expiry_year": "2029",
        "holder": "J DOE",
        "card_status": "ACTIVE",
        "is_default": false,
        "priority": 2,
        "fee_amount": "2.00",
        "fee_transaction_id": "tra_pr6CvR_4pvWwmgQ4y3dtY", // 3DS verification / fee transaction (the card's CIT anchor for card-on-file charges)
        "created_at": "2026-07-06T10:15:30Z"
      }
    }
  ],
  "created_at": "2026-07-06T10:15:30Z"
}