# 

## Prerequisites

* A valid API key — see [Obtain API credentials](/docs/how-tos/setup/obtain-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).

```shell
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
```shell
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
  }'
```

Python
```python
import requests

transaction_id = "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y"
resp = requests.post(
    f"https://api.dev.paradisegateway.net/v1/transactions/{transaction_id}",
    headers={"Content-Type": "application/json", "APIKEY": "YOUR-API-KEY"},
    json={
        "type": "card_update",
        "amount": 18000,
        "tip": 3000,
        "payment_method": {
            "type": "card",
            "pan": "4111111111111234",
            "expiry_month": "03",
            "expiry_year": "2028",
            "cardholder_name": "Spock",
            "cvv": "456",
            "address_line1": "1701 Enterprise Dr",
            "zip": "94102",
        },
        "recurring": False,
        "purchase_description": "Romulan ale",
    },
)
print(resp.json())
```

JavaScript
```javascript
const transactionId = "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y";
const resp = await fetch(
  `https://api.dev.paradisegateway.net/v1/transactions/${transactionId}`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "APIKEY": "YOUR-API-KEY",
    },
    body: JSON.stringify({
      type: "update",
      amount: 18000,
      tip: 3000
    }),
  }
);
console.log(await resp.json());
```

C#
```csharp
var transactionId = "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y";
var payload = new
{
    type = "update", amount = 18000, tip = 3000
};
var resp = await client.PostAsJsonAsync(
    $"https://api.dev.paradisegateway.net/v1/transactions/{transactionId}",
    payload);
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```

Java
```java
String transactionId = "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y";
String body = """
    {
      "type": "update", "amount": 18000, "tip": 3000
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://api.dev.paradisegateway.net/v1/transactions/" + transactionId))
    .header("Content-Type", "application/json")
    .header("APIKEY", "YOUR-API-KEY")
    .POST(HttpRequest.BodyPublishers.ofString(body)).build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());
```

Go
```go
transactionID := "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y"
payload := strings.NewReader(`{
  "type": "update", "amount": 18000, "tip": 3000
}`)
req, _ := http.NewRequest("POST",
    "https://api.dev.paradisegateway.net/v1/transactions/"+transactionID, payload)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("APIKEY", "YOUR-API-KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
```

PHP
```php
$id = "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y";
$ch = curl_init("https://api.dev.paradisegateway.net/v1/transactions/$id");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "APIKEY: YOUR-API-KEY"],
    CURLOPT_POSTFIELDS => json_encode([
        "type" => "update", "amount" => 18000, "tip" => 3000,
    ]),
]);
echo curl_exec($ch); curl_close($ch);
```

Ruby
```ruby
id = "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y"
uri = URI("https://api.dev.paradisegateway.net/v1/transactions/#{id}")
req = Net::HTTP::Post.new(uri, {
  "Content-Type" => "application/json", "APIKEY" => "YOUR-API-KEY",
})
req.body = {
  type: "update", amount: 18000, tip: 3000
}.to_json
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts resp.body
```

## 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.

```json
{
  "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 |


## Next steps

* [Authorize and capture separately](/docs/how-tos/process-payments/authorize-capture-separately)
* [Handle partial captures](/docs/how-tos/process-payments/handle-partial-capture)
* [About the transaction lifecycle](/docs/concepts/transactions/transaction-lifecycle)