Confirm Surcharge

​

Confirm or decline a surcharge-pending transaction. This is the structured endpoint used by SDK flows.

When a payment or preauth returns surcharge_pending, the SDK presents the surcharge to the cardholder and calls this endpoint. The transaction ID is in the URL path and the body uses the typed ProcessConfirmRequest schema with optional amount and breakdown overrides.

Path Parameters
  • transaction_id
    Type: string · Transaction Id
    required

    ID of the surcharge-pending transaction.

Headers
  • Accept
    enum
    const:  
    application/json
    required

    Response format. Must be application/json.

    values
    • application/json
  • Content-Type
    enum
    const:  
    application/json
    required

    Request payload format. Must be application/json when a body is sent.

    values
    • application/json
Body·
required
application/json

Request body for confirming or declining a surcharge-pending transaction. After a payment returns surcharge_pending status, the client must present the surcharge to the cardholder and call confirm with the result.

  • confirm
    Type: boolean · Confirm
    required

    Whether the cardholder accepted the surcharge. true processes the payment with surcharge applied; false cancels the transaction.

  • amount
    Type: integer | null · Amount

    Optional override of the total transaction amount in cents. If not provided, the original calculated amount (including surcharge) is used.

  • breakdown
    Type: object · nullable

    Optional updated breakdown with surcharge details.

    Enhanced payment amount breakdown with surcharge support. Rates can be sent as integers (old SDK format, e.g., 875 = 8.75%) or floats (new SDK format, e.g., 8.75). Values >= 100 are auto-converted from basis points.

  • event_id
    Type: string | null · Event Id

    Idempotency key for this confirmation event. If not provided, one is generated server-side.

Responses
  • application/json
  • 400

    Missing confirm field or duplicate event_id.

  • 404

    Transaction not found.

  • application/json
Request Example for post/v1/payments/{transaction_id}/confirm
curl 'https://api.uat.koard.com/v1/payments/{transaction_id}/confirm' \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-koard-apikey: YOUR_SECRET_TOKEN' \
  --data '{
  "confirm": true,
  "amount": 10850,
  "breakdown": {
    "subtotal": 10000,
    "taxAmount": 500,
    "surcharge": {
      "percentage": 3.5
    }
  },
  "event_id": "evt_confirm_001"
}'

{
  "account_id": "string",
  "additional_details": {},
  "apple_transaction_id": "string",
  "batch_id": null,
  "card": "string",
  "card_brand": "string",
  "card_type": "string",
  "created_at": 1,
  "currency": "string",
  "device_id": null,
  "event_id": "string",
  "gateway": null,
  "gateway_transaction_id": null,
  "gateway_transaction_response": null,
  "history": [],
  "location_id": null,
  "merchant_name": "",
  "mid": "string",
  "owner_id": null,
  "parent_account_ids": [
    "string"
  ],
  "payment_method": "string",
  "processor": null,
  "processor_mid": "string",
  "processor_response_code": null,
  "processor_response_message": null,
  "processor_tid": "string",
  "reader_identifier": "string",
  "refunded": null,
  "reversed": null,
  "status": null,
  "status_reason": null,
  "subtotal": 1,
  "surcharge_amount": null,
  "surcharge_applied": false,
  "surcharge_rate": null,
  "tax_amount": null,
  "tax_rate": null,
  "tid": "string",
  "tip_amount": null,
  "tip_type": null,
  "total_amount": 1,
  "transaction_id": "string",
  "transaction_type": null
}

The confirmed or canceled transaction. Status will be the payment result (e.g., approved) if confirmed, or surcharge_declined_by_payer if declined.