• English
  • Capture / Cancel Authorization

    Applicable Market: ZA South Africa

    Request path

    /api/v1/payment/merchant/card/operation

    Perform a capture (charge) or cancel (release without charge) on an authorized order. The same endpoint is used; the operation is distinguished by the action parameter.

    Prerequisite: The order must have orderStatus = 5 (required_capture) before this endpoint can be called.

    Request Parameters

    ParameterTypeRequiredDescription
    amountintegerRequired for cancel; optional for captureTransaction amount in the smallest currency unit (cents)
    currencystringYesCurrency code ZAR
    idempotencyIdstringYesIdempotency key to prevent duplicate submissions
    actionstringYescapture – charge · cancel – release
    orderNostringYesPlatform order number returned by CreateOrder
    userIdstringNoMerchant-side user identifier
    nonceStrstringYesRandom string (used for signature generation)
    requestTimeintegerYesUnix timestamp in milliseconds
    versionstringYes2.0.0.0
    notifyUrlstringYesAsynchronous notification callback URL

    Yes = Required · No = Optional

    action Enum

    ValueMeaningFund Flow
    captureChargeDebit the cardholder's account and settle to the merchant
    cancelReleaseRelease the cardholder's authorized amount; no charge is made

    Response

    FieldDescription
    orderNoPlatform order number
    idempotencyIdIdempotency key echoed back
    orderStatus1 (pending) = asynchronous processing in progress; query or await notification for the final result
    currencyCurrency code, e.g. ZAR
    amountTransaction amount in the smallest currency unit (cents)
    merchantIdMerchant ID assigned to your account

    Examples

    capture (Charge)

    curl 'https://open-gw-daily.palmpay-inc.com/api/v1/payment/merchant/card/operation' \
      -H 'CountryCode: ZA' -H 'Authorization: Bearer xxx' -H 'Content-Type: application/json' \
      -d '{"amount":10,"currency":"ZAR","idempotencyId":"c-001","action":"capture",
           "orderNo":"24260608092828582939","userId":"6545456","nonceStr":"xxx",
           "notifyUrl": "https://www.yoursite.com/callback/payment",
           "requestTime":1699925850000,"version":"2.0.0.0"}'

    cancel (Release)

    curl 'https://open-gw-daily.palmpay-inc.com/api/v1/payment/merchant/card/operation' \
      -H 'CountryCode: ZA' -H 'Authorization: Bearer xxx' -H 'Content-Type: application/json' \
      -d '{"amount":10,"currency":"ZAR","idempotencyId":"x-001","action":"cancel",
           "orderNo":"24260608092828582939","userId":"6545456","nonceStr":"xxx",
           "notifyUrl": "https://www.yoursite.com/callback/payment",
           "requestTime":1699925850000,"version":"2.0.0.0"}'

    Response

    {
      "respCode": "00000000",
      "respMsg": "success",
      "status": true,
      "data": {
        "orderNo": "24260701083336451596",
        "idempotencyId": "1782894800751",
        "orderStatus": 1,
        "currency": "ZAR",
        "amount": 1000,
        "merchantId": "124012503542121"
      }
    }

    Order Status Flow

    createorder (captureMode=manual)
            │
            ▼
      orderStatus=5 (required_capture)
            │
       ┌────┴──────────┐
       │               │
       ▼               ▼
    capture          cancel
       │               │
       ▼               ▼
    status=2        status=4
    (succeeded)     (closed)

    Important Notes

    1. Asynchronous Processing: A synchronous response with orderStatus=1 only indicates that the request has been accepted. The final outcome must be confirmed via order query or asynchronous notification.
    2. Idempotency: The idempotencyId ensures that duplicate calls do not result in duplicate charges.
    3. Cancel is Irreversible: Once cancelled, the authorized amount is released back to the cardholder and cannot be recovered. A new order must be created if a charge is subsequently needed.
    4. Capture Amount: amount must be ≤ the authorized amount.