> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner-Managed

> How Rain validates a Partner-Managed authorization and how you approve, decline, or reverse it.

This page covers the authorization flow for Partner-Managed programs, where your system approves or declines each transaction. For the Rain-Managed equivalent, see [Rain-managed](/docs/authorization-rain-managed).

## Approving authorizations

When a cardholder initiates a purchase, Rain's system validates several criteria before sending the authorization request. This includes verifying card validity, checking the reserve balance, assessing spending limits, applying custom rules (such as merchant blocks), and evaluating fraud risk. If any of these checks fail, the transaction is declined immediately and you receive a `transaction.created` webhook with `status: declined`. No `transaction.requested` webhook is sent. If all checks pass, you receive a `transaction.requested` webhook to approve or decline the request. If you approve, place a hold on the funds to reserve them for settlement. At this stage, no funds are transferred.

Once Rain responds to the network, Rain sends you a [`transaction.created`](/docs/transaction#transaction-created) webhook. If the transaction is declined, it will have a `status` of `declined`. You will need to persist this data for logging purposes.

```mermaid theme={null}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
	    'textColor': '#A6CFFF',
      'primaryColor': '#212933',
      'primaryTextColor': '#FFFFFF',
      'primaryBorderColor': '#A6CFFF',
      'secondaryColor': '#F73196',
      'noteBkgColor': '#F4F3FF',
      'noteBorderColor': '#F4F3FF',
      'noteTextColor': '#6938EF'
    },
	  'sequence': {
	    'actorFontWeight': 'bold'
	  }
  }
}%%

sequenceDiagram
    Merchant->>+Rain: Auth Request ($100)
    Rain->>+You: `transaction.requested` Webhook ($100)
    You->>+Your Ledger: Place Hold ($100)
    Note over Your Ledger: Total Hold ($100)
    Your Ledger-->>-You: Hold Placed
	  You-->>-Rain: Webhook Approved
    Rain-->>-Merchant: Auth Approved
    Rain->>+You: `transaction.created` Webhook ($100)
    You-->>-Rain: Webhook Acknowledged
```

## Declining authorizations

<Warning>
  **Limited availability:**

  Only Partner-managed programs can decline transactions. Rain-managed programs do not support this feature at this time.
</Warning>

To decline a cardholder authorization request, respond to the `transaction.requested` webhook event with any non-`2xx` HTTP status code, such as `401`. Any `2xx` response approves the authorization. You will then receive a `transaction.created` webhook with a status of "Declined" and amount of \$0.

```mermaid theme={null}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
	    'textColor': '#A6CFFF',
      'primaryColor': '#212933',
      'primaryTextColor': '#FFFFFF',
      'primaryBorderColor': '#A6CFFF',
      'secondaryColor': '#F73196',
      'noteBkgColor': '#F4F3FF',
      'noteBorderColor': '#F4F3FF',
      'noteTextColor': '#6938EF'
    },
	  'sequence': {
	    'actorFontWeight': 'bold'
	  }
  }
}%%

sequenceDiagram
    Merchant->>+Rain: Auth Request ($100)
    Rain->>+You: `transaction.requested` Webhook ($100)
    You->>+Your Ledger: Check balance ($100)
    Note over Your Ledger: Current funds ($50)
    Your Ledger-->>-You: Transaction Declined
	  You-->>-Rain: Webhook HTTP Code 401
    Rain-->>-Merchant: Auth Declined
    Rain->>+You: `transaction.created` Webhook ($0)
    You-->>-Rain: Webhook Acknowledged
```

### Rejection codes

When declining a transaction, in addition to having an HTTP status code of 401 or any 40X HTTP status code, you can include a `rejectionCode` in your response body to indicate the reason for the decline.

| Code                     | Description                                                              |
| ------------------------ | ------------------------------------------------------------------------ |
| `INSUFFICIENT_FUNDS`     | Cardholder does not have sufficient funds                                |
| `SUSPICIOUS_TRANSACTION` | Transaction appears suspicious or has elevated risk                      |
| `NOT_PERMITTED`          | Transaction is not permitted for the user due to a policy decision       |
| `UNKNOWN`                | Partner declined the transaction for a reason not covered by other codes |

<CodeGroup>
  ```json Response Body theme={null}
  {
    "rejectionCode": "INSUFFICIENT_FUNDS"
  }
  ```
</CodeGroup>

<Info>
  The `rejectionCode` field is optional but recommended: it determines the decline reason sent to the network. If you decline without one, Rain treats it as a general webhook decline.
</Info>

## Incremental authorizations

Some merchants, such as hotels and gas stations, may need to increase the initial authorization amount. This typically occurs when the final transaction amount is not known upfront. For example, hotels may add room service charges, or gas stations may adjust for the total fuel cost. Rain's system supports this through incremental authorizations, allowing merchants to request additional funds beyond the original authorization. Each increment undergoes the same validation process as the initial authorization.

Rain notifies you with a [`transaction.requested`](/docs/transaction#transaction-requested) webhook followed by a [`transaction.updated`](/docs/transaction#transaction-updated) webhook with the new total amount (original amount + increment amount)

```mermaid theme={null}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
	    'textColor': '#A6CFFF',
      'primaryColor': '#212933',
      'primaryTextColor': '#FFFFFF',
      'primaryBorderColor': '#A6CFFF',
      'secondaryColor': '#F73196',
      'noteBkgColor': '#F4F3FF',
      'noteBorderColor': '#F4F3FF',
      'noteTextColor': '#6938EF'
    },
	  'sequence': {
	    'actorFontWeight': 'bold'
	  }
  }
}%%

sequenceDiagram
    Merchant->>+Rain: Auth Request ($50)
    Rain->>+You: `transaction.requested` Webhook ($50)
    You->>+Your Ledger: Place Hold ($50)
    Note over Your Ledger: Total Hold ($50)
    Your Ledger-->>-You: Hold Placed
	  You-->>-Rain: Webhook Approved
    Rain-->>-Merchant: Auth Approved
    Rain->>+You: `transaction.created` Webhook ($50)
    You-->>-Rain: Webhook Acknowledged
    Note over Merchant,Your Ledger: Time passes
    Merchant->>+Rain: Increment Request (+$25)
    Rain->>+You: `transaction.requested` Webhook ($25)
    You->>+Your Ledger: Place Hold ($25)
    Note over Your Ledger: Total Hold ($75)
    Your Ledger-->>-You: Hold Placed
	  You-->>-Rain: Webhook Approved
    Rain-->>-Merchant: Increment Approved
    Rain->>+You: `transaction.updated` Webhook ($75)
    You-->>-Rain: Webhook Acknowledged
```

## Partial reversals

When a merchant needs to reverse part of an authorization amount, the merchant can submit a partial reversal. Rain records the reversed amount and releases the authorization hold upon receiving the partial reversal. This is common in scenarios like gas stations, where the initial hold may be higher than the final amount.

To notify you of this change and the release of the authorization hold, Rain sends you a [`transaction.updated`](/docs/transaction#transaction-updated) webhook with a `status` of `reversed`.

If the transaction is partially reversed and the final settlement amount in the `transaction.completed` webhook does not reflect the partial reversal, the liability to fix this mismatch falls on the merchant/acquirer. To resolve, this is handled via Rain's [transaction issues and disputes](/docs/transaction-issues-disputes) process.

```mermaid theme={null}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
	    'textColor': '#A6CFFF',
      'primaryColor': '#212933',
      'primaryTextColor': '#FFFFFF',
      'primaryBorderColor': '#A6CFFF',
      'secondaryColor': '#F73196',
      'noteBkgColor': '#F4F3FF',
      'noteBorderColor': '#F4F3FF',
      'noteTextColor': '#6938EF'
    },
	  'sequence': {
	    'actorFontWeight': 'bold'
	  }
  }
}%%

sequenceDiagram
    Merchant->>+Rain: Auth Request ($100)
    Rain->>+You: `transaction.requested` Webhook ($100)
    You->>+Your Ledger: Place Hold ($100)
    Note over Your Ledger: Total Hold ($100)
    Your Ledger-->>-You: Hold Placed
	  You-->>-Rain: Webhook Approved
    Rain-->>-Merchant: Auth Approved
    Rain->>+You: `transaction.created` Webhook ($100)
    You-->>-Rain: Webhook Acknowledged
    Note over Merchant,Your Ledger: Time passes
    Merchant->>+Rain: Partial Reversal (-$40)
    Note over You,Your Ledger: Reversed Portion Released (-$40)
    Note over Your Ledger: Total Hold ($60)
    Rain-->>-Merchant: Reversal Processed
    Rain->>+You: `transaction.updated` Webhook ($60)
    You-->>-Rain: Webhook Acknowledged
```

## Full reversals

A full reversal cancels an authorization entirely. This typically happens when a transaction is canceled or times out. Rain's system marks the authorization as reversed. As with partial reversals, the hold is released upon reception of the reversal or automatically on the [stale authorization schedule](/docs/authorization-partner-managed#stale-authorization-closure).

Rain sends you a [`transaction.updated`](/docs/transaction#transaction-updated) webhook with a `status` of `reversed` and an `amount` of \$0, simultaneously releasing the authorization hold.

If the transaction is fully reversed and the final settlement amount in the `transaction.completed` webhook does not reflect the full reversal (that is, a final `amount` other than \$0), the liability to fix this mismatch falls on the merchant/acquirer. To resolve, this is handled via Rain's [transaction issues and disputes](/docs/transaction-issues-disputes) process.

```mermaid theme={null}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
	    'textColor': '#A6CFFF',
      'primaryColor': '#212933',
      'primaryTextColor': '#FFFFFF',
      'primaryBorderColor': '#A6CFFF',
      'secondaryColor': '#F73196',
      'noteBkgColor': '#F4F3FF',
      'noteBorderColor': '#F4F3FF',
      'noteTextColor': '#6938EF'
    },
	  'sequence': {
	    'actorFontWeight': 'bold'
	  }
  }
}%%

sequenceDiagram
    Merchant->>+Rain: Auth Request ($100)
    Rain->>+You: `transaction.requested` Webhook ($100)
    You->>+Your Ledger: Place Hold ($100)
    Note over Your Ledger: Total Hold ($100)
    Your Ledger-->>-You: Hold Placed
	  You-->>-Rain: Webhook Approved
    Rain-->>-Merchant: Auth Approved
    Rain->>+You: `transaction.created` Webhook ($100)
    You-->>-Rain: Webhook Acknowledged
    Note over Merchant,Your Ledger: Time passes
    Merchant->>+Rain: Full Reversal
    Note over You,Your Ledger: Hold Released
    Note over Your Ledger: No Remaining Hold
    Rain-->>-Merchant: Reversal Processed
    Rain->>+You: `transaction.updated` Webhook ($0)
    You-->>-Rain: Webhook Acknowledged
```

## Partial authorizations

<Warning>
  **Currently not supported:**

  Partial authorizations are not currently supported. When a cardholder has insufficient funds for the full requested amount, the transaction is declined.
</Warning>

Some merchants may request partial authorizations for the available balance when a cardholder has insufficient funds. This would allow a transaction to proceed with a reduced amount, which is common in scenarios such as pay-at-pump gas stations or retail transactions.

Rain does not currently support partial authorizations. If the cardholder's balance is insufficient for the full requested amount, the authorization is declined. You will receive a [`transaction.created`](/docs/transaction#transaction-created) webhook with a `status` of `declined`.

## Refund authorizations

Occasionally, merchants may send an authorization before processing a refund to a card. This resembles a standard authorization but with a negative amount. The key difference is that the user's ledger is not credited until the refund is fully settled.

Rain sends a [`transaction.requested`](/docs/transaction#transaction-requested) with a negative amount and upon your approval of this request (by responding with `200`) you will receive a [`transaction.created`](/docs/transaction#transaction-created) webhook.

```mermaid theme={null}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
	    'textColor': '#A6CFFF',
      'primaryColor': '#212933',
      'primaryTextColor': '#FFFFFF',
      'primaryBorderColor': '#A6CFFF',
      'secondaryColor': '#F73196',
      'noteBkgColor': '#F4F3FF',
      'noteBorderColor': '#F4F3FF',
      'noteTextColor': '#6938EF'
    },
	  'sequence': {
	    'actorFontWeight': 'bold'
	  }
  }
}%%

sequenceDiagram
    Merchant->>+Rain: Auth Request (-$100)
    Rain->>+You: `transaction.requested` Webhook (-$100)
    Note over You,Your Ledger: No Credit Hold
	  You-->>-Rain: Webhook Approved
    Rain-->>-Merchant: Auth Approved
    Rain->>+You: `transaction.created` Webhook (-$100)
    You-->>-Rain: Webhook Acknowledged
```

## Stale authorization closure

If an authorization remains pending and never settles, it becomes stale and is automatically closed. The closure period depends on the transaction type:

* **Refunds**: Closed after **31 days**
* **Low value positive transactions** (≤\$1000): Closed after **14 days**
* **High value positive transactions** (>\$1000): Closed after **31 days**
* **Travel and rental holds** (cruise, lodging, and vehicle-rental merchant categories): Closed after **30 days**

When a stale authorization is closed, any holds on the funds are released and the authorization is marked as closed.

## What's next

<Columns cols={2}>
  <Card title="Transaction events" icon="money-bill-transfer" href="/docs/transaction">
    See the full webhook payload and field reference for every transaction event.
  </Card>

  <Card title="Handle disputes & refunds" icon="life-ring" href="/docs/transaction-issues-disputes">
    Walk through filing a dispute, refunds, and chargebacks.
  </Card>
</Columns>