• English
  • Standalone Card Unbinding

    Market: ZA South Africa

    /api/v1/card/token/unbind

    Unbinds a previously bound cardToken, making it permanently unavailable for future payments. Once unbound, the card can no longer be used in cardPayerInfo when calling [CreateOrder]. To pay with the same card again, the cardholder must complete [Bind Card] again to obtain a new cardToken.

    ⚠️ Precondition: this endpoint only succeeds when the target cardToken is currently in cardStatus = 1 (Linked). Calling it on a token that is not in this state (e.g. never completed binding, already unbound, or in any other status) returns AC000006. Always confirm the token's current status via [Token Query] before calling this endpoint if you are not certain.

    Typical use cases: cardholder removes a saved card from their wallet, merchant offboards a stored payment method on customer request, compliance-driven token cleanup.

    Request Parameters

    ParameterTypeRequiredDescription
    cardTokenstringYesThe card token to unbind, obtained from [Bind Card]
    nonceStrstringYesRandom string, included in the signature
    requestTimeintegerYesUnix timestamp in milliseconds
    versionstringYesFixed value 2.0.0.0

    Yes = required · No = optional

    Response Fields

    FieldTypeDescription
    respCodestring00000000 on success, other values indicate failure
    respMsgstringResponse description
    statusbooleantrue / false
    dataobjectEmpty object {} on success

    Example — Success

    Request / Response

    curl 'https://open-gw.palmpay-inc.com/api/v1/card/token/unbind' \
      -H 'CountryCode: ZA' \
      -H 'Authorization: Bearer xxx' \
      -H 'Content-Type: application/json' \
      -d '{
            "cardToken": "4674f053401447049d2078b1e509f975",
            "nonceStr": "xxx",
            "requestTime": 1699925850000,
            "version": "2.0.0.0"
          }'
    {
      "respMsg": "success",
      "data": {},
      "respCode": "00000000",
      "status": true
    }

    Example — Failure

    Unbinding fails if the cardToken is not currently in cardStatus = 1 (Linked) — for example, if it was already unbound, never completed binding, or is otherwise invalid.

    {
      "respCode": "AC000006",
      "respMsg": "Unlink account failed, current account status is not link status",
      "status": false
    }

    Idempotency Note

    Calling this endpoint again with a cardToken that has already been unbound does not return a success response. Since the token is no longer in cardStatus = 1, the request fails with AC000006. Merchants should treat AC000006 on a retry as confirmation that the token is already unbound, rather than as an unexpected error.

    Card Status Requirement

    cardStatusMeaningCan unbind be called?
    1LinkedYes — the only status this endpoint accepts
    any other valueNot linked (e.g. initializing, failed, already unbound, frozen, etc.)No — returns AC000006

    Error Codes

    Error CodeMeaning
    AC000006Unlink account failed — the cardToken is not currently in cardStatus = 1 (Linked)

    Additional error codes may apply for common platform-level errors (signature errors, IP allowlist, etc.) — refer to the [Open Platform error code reference].