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
    required

    ID of the surcharge-pending transaction.

Headers

  • Accept
    enum
    const:  
    application/json
    required

    Response format. Must be application/json.

  • Content-Type
    enum
    const:  
    application/json
    required

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

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
    required

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

  • amount
    Type: integer | null

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

  • breakdown
    Type: nullable

    Optional updated breakdown with surcharge details.

    Properties: 7
  • event_id
    Type: string | null

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

Responses

  • application/json
  • application/json
  • application/json
  • 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": null,
  "breakdown": {
    "subtotal": 1,
    "taxAmount": null,
    "taxRate": 1,
    "tipAmount": null,
    "tipRate": 1,
    "tipType": "fixed",
    "surcharge": {
      "amount": null,
      "percentage": null,
      "bypass": false
    }
  },
  "event_id": null
}'

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

Successful Response