Add a tip or surcharge

Prerequisites

A valid API key — see Obtain API credentials
An authorized transaction (from a sale, auth, or tokenized equivalent)

When to use this

Restaurant / hospitality: The person adds a tip after signing the receipt.
Service industry: A gratuity is added after the service is complete.
Surcharges: An additional fee is applied after initial authorization (where legally permitted).

Step 1: Authorize the transaction

First, request an authorization for the base amount (before tip).

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "auth",
    "amount": 15000,
    "tip": 0,
    "payment_method": {
      "type": "card",
      "pan": "4111111111111111",
      "expiry": {
        "month": "03",
        "year": "2028"
      },
    },
      "cardholder_name": "Spock",
      "cvv": "999",
      "address_line1": "1701 Enterprise Dr",
      "zip": "94102"
  },
  "metadata": {},
  "recurring": false,
  "purchase_description": "Romulan ale"
  }'

Save the id from the response.

Step 2: Update with the tip

Send POST /v1/transactions/{id} with type: update and include the updated amount and tip.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "update",
    "amount": 18000,
    "tip": 3000
  }'

Step 3: Verify the update

The response confirms the updated amounts. The 30.00 is added to the original 150.00 amount and the new amount is 180.00 USD.

{
  "id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "type": "update",
  "transaction_state": "authorized",
  "response_status": "Approved",
  "response_code": "00",
  "amount": 18000,
  "tip": 3000,
  "correlation_id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd"
}

The person's card will be charged 180.00 USD (150.00 + 30.00 tip) at settlement.

Tip field rules

Rule	Details
Minimum	50 cents (if provided; `0` is allowed to clear a tip)
Maximum	99,999,999 cents (999,999.99 USD)
Currency	USD only (all amounts in cents)
Timing	Must be updated before batch settlement