• English
  • Standalone Card Binding

    Market: ZA South Africa

    /api/v1/card/token/bind

    Binds a card via a zero-amount authorization without creating a payment transaction. The card binding flow triggers a $0 verification followed by 3DS authentication. On success, the API returns a cardToken that can be reused for subsequent payments.

    Typical use cases: MIT (merchant-initiated transaction) recurring billing setup, one-click payment pre-binding, wallet card management.

    Request Parameters

    ParameterTypeRequiredDescription
    cardNostringYesCard number (PAN)
    expiryMonthstringYesExpiry month, e.g. 12
    expiryYearstringYesExpiry year, last two digits, e.g. 26
    cvvstringYesCVV / CVC2
    holderNamestringNoCardholder name as printed on the card
    userIdstringNoMerchant-side user identifier
    callBackUrlstringNoBrowser redirect URL after the cardholder completes 3DS authentication
    nonceStrstringYesRandom string, included in the signature
    requestTimeintegerYesUnix timestamp in milliseconds (13 digits)
    versionstringYesFixed value 2.0.0.0

    Yes = required · No = optional

    Response Fields

    FieldDescription
    cardTokenCard token. Pass this value in cardPayerInfo when calling [CreateOrder] in token payment mode
    verifyMethodFixed value: open_url
    verifyUrl3DS authentication URL. Redirect the cardholder to this URL to complete identity verification

    Example

    Request / Response

    curl 'https://open-gw-daily.palmpay-inc.com/api/v1/card/token/bind' \
      -H 'CountryCode: ZA' \
      -H 'Authorization: Bearer xxx' \
      -H 'Content-Type: application/json' \
      -d '{
            "cardNo": "4000000000000002",
            "expiryMonth": "12",
            "expiryYear": "26",
            "cvv": "123",
            "holderName": "zhangg",
            "userId": "6545456",
            "callBackUrl": "https://www.yoursite.com/return",
            "nonceStr": "rNsxYX3Rkkktqq5NG3kkllpp",
            "requestTime": 1699925850000,
            "version": "2.0.0.0"
          }'
    {
      "respCode": "00000000",
      "respMsg": "success",
      "status": true,
      "data": {
        "cardToken": "60871b47d2e7444b859848c567824bfd",
        "verifyMethod": "open_url",
        "verifyUrl": "https://.../3ds-auth-html?..."
      }
    }

    Notification Callback

    Once the card binding flow (including 3DS authentication) is completed, PalmPay sends an asynchronous POST notification to the callback address configured in your Open Platform dashboard.

    ⚠️ Do not confuse the two URLs:

    • callBackUrl — where the cardholder's browser is redirected after 3DS (front-end)
    • Notification callback — a server-to-server call from PalmPay to your backend (asynchronous result push)

    Request Format

    • Method: POST
    • Content-Type: application/json
    • Header: countryCode: ZA

    Notification Parameters

    FieldTypeDescription
    bankNamestringIssuing bank name
    cardBrandstringCard scheme, e.g. VISA, MASTERCARD
    cardCountrystringCard issuing country code, e.g. ZA
    cardLast4stringLast 4 digits of the card number
    cardNostringMasked card number
    cardTokenstringThe bound card token, used for subsequent token payments
    cardTypestringCard type: debit_card / credit_card
    createTimestringBinding creation time (UTC, ISO 8601)
    expiryMonthstringExpiry month
    expiryYearstringExpiry year (last two digits)
    tokenStatusstringToken status
    updateTimestringLast update time (UTC, ISO 8601)
    signstringSignature value (URL-encoded; decode before verification)

    Example Payload

    {
      "bankName": "Wema Bank",
      "cardBrand": "VISA",
      "cardCountry": "ZA",
      "cardLast4": "2105",
      "cardNo": "400000******2105",
      "cardToken": "8162f22d69344efa92e5b8eb38eee942",
      "cardType": "debit_card",
      "createTime": "2026-09-10T02:45:38.202+00:00",
      "expiryMonth": "12",
      "expiryYear": "26",
      "tokenStatus": "1",
      "updateTime": "2026-09-10T02:45:39.326+00:00",
      "sign": "Uw%2FfhgHhpJx4CYdEt%2BYRDpxsvxsh/W7rcpufjBcSVupatZearYyAZoAMtS%2F7A0ba%2BVTFAfqs3jAASaNI5I5NfRs9sqeCe2AYf8UC80DQStg7x3JCVPPFqhE2L0S32QVhD8qv01w%2Bpcr9L2gU6Ebdn5IhSubJMWe3CIKu6E0h3D"
    }

    Signature Verification

    The sign field is generated with the same algorithm as request signing. Verify it using the PalmPay public key:

    1. URL-decode the sign value (it contains %2F = / and %2B = +)
    2. Sort all non-empty parameters except sign by key in ASCII ascending order and concatenate as key=value&key=value
    3. Compute MD5(strA).toUpperCase() → md5Str
    4. Verify md5Str against the decoded sign using SHA1WithRSA with the PalmPay public key

    ⚠️ Encoding caveat: the sign value may contain a mix of URL-encoded characters (%2F, %2B) and raw /. Always use a standard URL decoder (e.g. java.net.URLDecoder.decode) — do not perform manual string replacement.

    Notifications that fail signature verification must be treated as invalid and discarded.

    Retry Policy

    If your endpoint does not return the expected success acknowledgement within the timeout, PalmPay will retry the notification automatically according to the configured policy.

    Expected Merchant Response

    Return the agreed success acknowledgement after processing the notification. Otherwise PalmPay will keep retrying until the maximum attempt count is reached.

    Complete Flow: Bind Card → Token Payment

    Merchant                        PalmPay                        Card Scheme
       |
    |
    |
       |-- 1. POST /card/token/bind -->|
    |
       |      cardNo, cvv, expiry      |-- $0 auth + 3DS request ----->|
       |<-- cardToken + verifyUrl -----|
    |
       |
    |
    |
       |-- 2. Cardholder opens ------->|
    |
       |      verifyUrl, completes 3DS |<-- binding confirmed ---------|
       |
    |
    |
       |-- 3. POST /createorder ------>|
    |
       |      cardPayerInfo:           |-- pay with stored token ----->|
       |      {"cardToken":"..."}      |
    |
       |<-- orderNo (no 3DS needed) ---|
    |