# 

## When to use this pattern

* You need to verify the card before fulfilling the order
* You ship physical goods and want to charge only when the order ships
* You want the option to adjust the amount (for example, partial shipments)


## Flow

![image](https://files.modern-mermaid.live/images/1776277181092-mermaid-diagram-1776277181292.png)

## Step 1: Authorize at checkout

When the customer places their order, authorize the full amount. This places a hold on the customer's card but does not transfer funds.

curl
```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": 7500,
    "payment_method": {
      "type": "card",
      "card": {
        "pan": "4111111111111111",
        "expiry_month": "12",
        "expiry_year": "2027",
        "cvv": "123",
        "cardholder_name": "Jane Smith"
      }
    },
    "metadata": {
      "order_id": "ORD-20260325-001"
    }
  }'
```

Python
```python
import os, requests

API_KEY = os.environ["PARADISE_API_KEY"]
BASE = "https://api.dev.paradisegateway.net"

auth_resp = requests.post(
    f"{BASE}/v1/transactions",
    headers={"Content-Type": "application/json", "APIKEY": API_KEY},
    json={
        "type": "auth",
        "amount": 7500,
        "payment_method": {
            "type": "card",
            "card": {
                "pan": "4111111111111111",
                "expiry_month": "12",
                "expiry_year": "2027",
                "cvv": "123",
                "cardholder_name": "Jane Smith",
            },
        },
        "metadata": {"order_id": "ORD-20260325-001"},
    },
)
auth = auth_resp.json()
txn_id = auth["id"]
print(f"Authorized: {txn_id}, state: {auth['transaction_state']}")
```

JavaScript
```javascript
const API_KEY = process.env.PARADISE_API_KEY;
const BASE = "https://api.dev.paradisegateway.net";

const authResp = await fetch(`${BASE}/v1/transactions`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "APIKEY": API_KEY },
  body: JSON.stringify({
    type: "auth",
    amount: 7500,
    payment_method: {
      type: "card",
      card: {
        pan: "4111111111111111",
        expiry_month: "12",
        expiry_year: "2027",
        cvv: "123",
        cardholder_name: "Jane Smith",
      },
    },
    metadata: { order_id: "ORD-20260325-001" },
  }),
});
const auth = await authResp.json();
console.log(`Authorized: ${auth.id}, state: ${auth.transaction_state}`);
```

### Authorization response

```json
{
  "id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC",
  "type": "auth",
  "amount": 7500,
  "transaction_state": "authorized",
  "response_status": "approved",
  "response_code": "00"
}
```

Save the `id` — you need it to capture or cancel later.

## Step 2: Capture when you ship

When the order ships, capture the authorized amount (or a partial amount if you ship less).

curl
```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/capture \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{ "amount": 7500 }'
```

Python
```python
cap_resp = requests.post(
    f"{BASE}/v1/transactions/{txn_id}/capture",
    headers={"Content-Type": "application/json", "APIKEY": API_KEY},
    json={"amount": 7500},
)
cap = cap_resp.json()
print(f"Captured: {cap['transaction_state']}")
```

JavaScript
```javascript
const capResp = await fetch(
  `${BASE}/v1/transactions/${auth.id}/capture`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json", "APIKEY": API_KEY },
    body: JSON.stringify({ amount: 7500 }),
  }
);
const cap = await capResp.json();
console.log(`Captured: ${cap.transaction_state}`);
```

## Step 3: Handle edge cases

### Cancel if the order is canceled

If the customer cancels before shipment, void the authorization to release the hold immediately.

```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/cancel \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{ "type": "cancel", "amount": 7500 }'
```

### Partial shipment

If you ship only part of the order, capture only that amount. The remaining hold is released automatically.

```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/capture \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{ "amount": 4500 }'
```

## Decision tree

![image](https://files.modern-mermaid.live/images/1776277225134-mermaid-diagram-1776277225352.png)

## Best practices

* **Capture promptly** — authorization holds typically expire in 7–10 days. Capture before the hold expires.
* **Use metadata** — attach your `order_id` to the authorization so you can correlate transactions with orders.
* **Check AVS/CVV** — review `avs_result_code` and `cvv_result` on the authorization response before fulfilling the order.
* **Idempotency** — if your capture request times out, it is safe to retry; the API is idempotent for capture operations.


## Next steps

* [Handle declined transactions](/docs/tutorials/payment-cookbook/handle-declined-transactions)
* [Handle partial captures](/docs/how-tos/process-payments/handle-partial-capture)
* [Cancel an authorized transaction](/docs/how-tos/manage-transactions/cancel-auth)