Webhook Refund

post

https://sandbox-api.softpoint.io/interface/v1/locations/YOUR_LOCATION_ID/webhook/refund

Refunds a previously settled card present payment. Use this endpoint to return funds to a cardholder for a transaction that was processed on a terminal. A full refund returns the entire captured amount, while supplying an amount allows a partial refund.

Request Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_ACCESS_TOKEN
Content-Type	Yes	application/json

Request Parameters

Path Parameters

Parameter	Type	Required	Description
location_id	string	Yes	Identifier of the location processing the refund

Request Body Fields

Field	Type	Required	Description
payment_id	string	Yes	Identifier of the original payment to be refunded.
amount	integer	No	Amount to refund, in minor units (cents). When omitted, the full captured amount is refunded.
terminal_id	integer	Yes	Identifier of the terminal associated with the refund.
webhook_id	string	No	Identifier used to correlate the asynchronous terminal result.

Request Example

{
  "payment_id": "9859",
  "terminal_id": 103,
  "webhook_id": "1999445"
}

To issue a partial refund, include the amount field:

{
  "payment_id": "9859",
  "amount": 100,
  "terminal_id": 103,
  "webhook_id": "1999445"
}

cURL Example

curl --request POST \
  --url https://sandbox-api.softpoint.io/interface/v1/locations/YOUR_LOCATION_ID/webhook/refund \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "payment_id": "9859",
    "terminal_id": 103,
    "webhook_id": "1999445"
  }'

Success Response

{
  "response": "APPROVED",
  "data": {
    "id": 9859,
    "id_external": "7522739543526339304605",
    "amount": 1999,
    "tip": 0,
    "total": 1999,
    "refunded_amount": 1999,
    "surcharge": 0,
    "transaction_id": "7522739543526339304605",
    "card_holder": null,
    "reference_id": "93f6157aa5714fd798359058a6995bdb",
    "auth_code": "831000",
    "card_type": "AMERICAN_EXPRESS",
    "last4": "2513",
    "entry_type": "Fallback Swipe",
    "emv_tags": "{\"Account\":\"*** **** **** 2513\",\"Card\":\"VISA\",\"Entry Mode\":\"Keyed\",\"Authorization\":\"-\",\"mAuthorizationCode\":\"831000\"}",
    "status": 3
  }
}

Response Fields

Field	Type	Description
response	string	Transaction outcome. `APPROVED` indicates the refund succeeded.
data	object	Transaction detail object.
data.id	integer	Softpoint transaction identifier.
data.id_external	string	External reference for the transaction.
data.amount	integer	Original transaction amount, in minor units.
data.tip	integer	Tip amount, in minor units.
data.total	integer	Transaction total, in minor units.
data.refunded_amount	integer	Amount refunded, in minor units.
data.surcharge	integer	Surcharge amount, in minor units.
data.transaction_id	string	Processor transaction identifier.
data.card_holder	string	null
data.reference_id	string	Reference identifier returned by the processor.
data.auth_code	string	Authorization code returned by the issuer.
data.card_type	string	Card brand.
data.last4	string	Last four digits of the card number.
data.entry_type	string	How the original card was read.
data.emv_tags	string	JSON-encoded string of EMV tag data.
data.status	integer	Numeric transaction status code.

Error Responses

The refund endpoint uses the standard error envelope. Common scenarios include an unknown terminal and missing required parameters.

Terminal Not Found

{
  "error": {
    "code": 10107,
    "message": "The selected terminal doesn't exist.",
    "details": null
  }
}

Missing Required Parameter

{
  "error": {
    "code": 10109,
    "message": "The request is missing one or more required parameter(s).",
    "details": {
      "payment_id": [
        "missing_required_parameters"
      ]
    }
  }
}

Status Codes

Code	Description
200	Request processed. Inspect `response` for the outcome.
400	Missing or invalid request parameters.
401	Missing or invalid access token.
404	The selected terminal does not exist.

Workflow Placement

The refund endpoint closes out a completed card-present payment:

Process a sale or capture an authorization.
Identify the original payment to be reversed.
Submit the refund, optionally specifying a partial amount.
Confirm the result using refunded_amount.

Notes

Amounts are expressed in minor units (cents).
Omit the amount field to refund the full captured amount. Supply amount to refund a portion.
Confirm the outcome with the refunded_amount field rather than assuming the full amount was returned.
Refunds are tied to the original payment_id; ensure the payment has settled before attempting a refund.

Common Mistakes

Submitting a refund before the original payment has settled.
Sending the refund amount in major units (dollars) instead of minor units (cents).
Omitting payment_id or terminal_id, which results in error code 10109.
Expecting a partial refund without including the amount field, which results in a full refund.

Response

200OK