Drawdown

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

← All 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

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": "[e-mail]",
      "phone": "[phone]",
      "address1": "123 Main St",
      "city": "New York",
      "province": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "paymentMethod": {
      "type": "drawdown"
    }
  }'

Two-Step Flow (Add Payment to Existing Intent)

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:

curl -X GET https://api.rye.com/v1/billing/balance \
  -H "Authorization: Bearer $RYE_API_KEY"

To list past transactions against your balance:

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

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:

{
  "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.

{
  "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). Only invoices in open status can be cancelled.

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.