> ## Documentation Index
> Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Drawdown

> Pay for orders using your pre-funded Rye account balance — no card tokenization required.

<Card title="← All Payment Providers" href="/api-v2/payment-providers" />

## Overview

Drawdown lets you pay for orders directly from your pre-funded Rye account balance. Unlike card-based payment methods, drawdown requires no tokenization or sensitive card handling. You simply fund your balance ahead of time and reference `{ "type": "drawdown" }` as the payment method when placing orders.

In this flow, the developer is responsible for collecting funds from the user, making the developer the merchant of record.

The order cost (minus any surcharge) is deducted from your balance at purchase time. If an order fails, the deducted amount is automatically credited back to your balance.

## How It Works

1. **Fund your balance** — Top up your Rye account balance via Stripe invoices.
2. **Place an order** — Submit a checkout intent with `"type": "drawdown"` as the payment method.
3. **Balance deducted** — The order cost is deducted from your balance when the order is placed.

## Usage

### Single-Step Purchase

```bash theme={null}
curl -X POST https://api.rye.com/v1/checkout-intents/purchase \
  -H "Authorization: Bearer $RYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productUrl": "https://example-store.myshopify.com/products/example-product",
    "quantity": 1,
    "buyer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "address1": "123 Main St",
      "city": "New York",
      "province": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "paymentMethod": {
      "type": "drawdown"
    }
  }'
```

### Two-Step Flow (Add Payment to Existing Intent)

```bash theme={null}
curl -X POST https://api.rye.com/v1/checkout-intents/{id}/payment \
  -H "Authorization: Bearer $RYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": {
      "type": "drawdown"
    }
  }'
```

## Checking Your Balance

You can check your current drawdown balance at any time:

```bash theme={null}
curl -X GET https://api.rye.com/v1/billing/balance \
  -H "Authorization: Bearer $RYE_API_KEY"
```

To list past transactions against your balance:

```bash theme={null}
curl -X GET https://api.rye.com/v1/billing/transactions \
  -H "Authorization: Bearer $RYE_API_KEY"
```

## Top-Up Invoices

If you need to add funds on demand (outside of automatic top-ups), you can create a top-up invoice. Only one unpaid top-up invoice is allowed at a time.

### Create a Top-Up Invoice

Create an on-demand top-up invoice ([API reference](/api-v2-experimental/api-reference/billing/create-on-demand-top-up-invoice)).

```bash theme={null}
curl -X POST https://api.rye.com/v1/billing/drawdown/topup \
  -H "Authorization: Bearer $RYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountSubunits": 500000,
    "chargeAutomatically": false
  }'
```

**Parameters:**

* `amountSubunits` (integer, required) — Amount in smallest currency unit (e.g. cents). Must be a positive integer.
* `chargeAutomatically` (boolean, optional) — Whether to automatically charge the invoice. Defaults to the value in your drawdown configuration.

**Response** (`201 Created`) — `bankTransferDetails` contains the destination bank info to push funds to; actual values are returned at runtime:

```json theme={null}
{
  "id": "in_abc123",
  "status": "open",
  "amount": {
    "amountSubunits": 500000,
    "currencyCode": "USD"
  },
  "url": "https://invoice.stripe.com/i/acct_xxx/test_xxx",
  "bankTransferDetails": {
    "routingNumber": "<routing-number>",
    "accountNumber": "<account-number>",
    "bankName": "<bank-name>",
    "accountHolderName": "<account-holder-name>"
  }
}
```

**Error responses:**

| Status | Reason                                                                                               |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | Drawdown billing is not enabled on your account.                                                     |
| `409`  | An unpaid top-up invoice already exists, or one is currently being created. See response body below. |
| `503`  | Bank transfer payment details are temporarily unavailable. Retry after a short delay.                |

**409 response body:**

When a 409 is returned, the body contains the existing invoice when it can be fetched, `null` when no invoice ID is yet known (creation is still in progress), or a partial invoice (with `amount` and `bankTransferDetails` set to `null`) when the invoice ID is known but full details could not be retrieved.

```json theme={null}
{
  "message": "An unpaid top-up invoice already exists",
  "invoice": {
    "id": "in_abc123",
    "status": "open",
    "amount": { "amountSubunits": 500000, "currencyCode": "USD" },
    "url": "https://invoice.stripe.com/i/acct_xxx/test_xxx",
    "bankTransferDetails": {
      "routingNumber": "<routing-number>",
      "accountNumber": "<account-number>",
      "bankName": "<bank-name>",
      "accountHolderName": "<account-holder-name>"
    }
  }
}
```

### Cancel a Top-Up Invoice

Cancel an unpaid top-up invoice ([API reference](/api-v2-experimental/api-reference/billing/cancel-top-up-invoice)). Only invoices in `open` status can be cancelled.

```bash theme={null}
curl -X DELETE https://api.rye.com/v1/billing/drawdown/topup/{invoiceId} \
  -H "Authorization: Bearer $RYE_API_KEY"
```

Returns `204 No Content` on success.

**Error responses:**

| Status | Reason                                                                 |
| ------ | ---------------------------------------------------------------------- |
| `400`  | Drawdown billing is not enabled on your account.                       |
| `404`  | Invoice not found.                                                     |
| `409`  | Invoice cannot be cancelled (e.g. it has already been paid or voided). |

## Notes

* Drawdown billing must be enabled on your Rye account. Contact the Rye team to get set up.
* If an order fails after the balance has been deducted, the amount is automatically refunded to your balance.