Gifts

A Gift is a single transfer of money: person-to-person, person-to-charity, or business-to-cause. One flat $1 fee, full compliance, settled within hours.

The Gift object

{
  "id":              "gft_01HZ...",
  "from":            "usr_8f3...",
  "to":              "org_a91...",
  "amount_cents":    2500,
  "fee_cents":       100,
  "net_cents":       2400,
  "currency":        "USD",
  "status":          "settled",
  "memo":            "Spring drive",
  "receipt_id":      "rcp_...",
  "created_at":      "2026-05-15T13:45:09Z",
  "settled_at":      "2026-05-15T13:45:11Z",
  "metadata":        { "internal_ref": "abc-123" }
}

Status values

pending — accepted, awaiting screening or funding.
settling — clearing on the underlying rail.
settled — complete, receipt issued where eligible.
failed — rejected by screening or funding source.
reversed — settled then reversed (rare).

POST /v1/gifts

Create a gift. Returns immediately in pending; emits gift.settled when funds clear.

Field	Type		Description
from	string	required	Identity id of the sender.
to	string	required	Identity id of the recipient (individual or organization).
amount_cents	integer	required	Gift amount in integer cents. Minimum 50.
currency	string	optional	ISO 4217. Defaults to USD.
memo	string	optional	A short note from sender to recipient. Max 280 chars.
metadata	object	optional	Arbitrary key-value pairs you want echoed back on the gift.

Example request

curl -X POST https://api.bequest.org/v1/gifts \
  -H "Authorization: Bearer $BQ_KEY" \
  -H "Idempotency-Key: req_8x9..." \
  -d '{
    "from": "usr_8f3...",
    "to":   "org_a91...",
    "amount_cents": 2500,
    "memo": "Spring drive"
  }'

import Bequest from 'bequest';

const bq = new Bequest(process.env.BQ_KEY);

const gift = await bq.gifts.create({
  from:         'usr_8f3...',
  to:           'org_a91...',
  amount_cents: 2500,
  memo:         'Spring drive',
}, { idempotencyKey: 'req_8x9...' });

import bequest

bq = bequest.Client(api_key=os.environ['BQ_KEY'])

gift = bq.gifts.create(
    from_='usr_8f3...',
    to='org_a91...',
    amount_cents=2500,
    memo='Spring drive',
    idempotency_key='req_8x9...',
)

<?php
use Bequest\Client;

$bq = new Client(getenv('BQ_KEY'));

$gift = $bq->gifts->create([
    'from'         => 'usr_8f3...',
    'to'           => 'org_a91...',
    'amount_cents' => 2500,
    'memo'         => 'Spring drive',
], ['idempotency_key' => 'req_8x9...']);

require 'bequest'

bq = Bequest::Client.new(ENV['BQ_KEY'])

gift = bq.gifts.create(
  from:           'usr_8f3...',
  to:             'org_a91...',
  amount_cents:   2500,
  memo:           'Spring drive',
  idempotency_key: 'req_8x9...'
)

import "github.com/bequest/bequest-go"

bq := bequest.NewClient(os.Getenv("BQ_KEY"))

gift, err := bq.Gifts.Create(ctx, &bequest.GiftCreateParams{
    From:           "usr_8f3...",
    To:             "org_a91...",
    AmountCents:    2500,
    Memo:           bequest.String("Spring drive"),
    IdempotencyKey: "req_8x9...",
})

Example response

{
  "id":           "gft_01HZ...",
  "from":         "usr_8f3...",
  "to":           "org_a91...",
  "amount_cents": 2500,
  "fee_cents":    100,
  "net_cents":    2400,
  "currency":     "USD",
  "status":       "settling",
  "memo":         "Spring drive",
  "created_at":   "2026-05-15T13:45:09Z"
}

Returns: The newly-created Gift object.

GET /v1/gifts/{id}

Retrieve one gift by id.

Field	Type		Description
id	string	required	The gift id, prefixed `gft_`.

Example request

curl https://api.bequest.org/v1/gifts/gft_01HZ... \
  -H "Authorization: Bearer $BQ_KEY"

const gift = await bq.gifts.retrieve('gft_01HZ...');

gift = bq.gifts.retrieve('gft_01HZ...')

$gift = $bq->gifts->retrieve('gft_01HZ...');

gift = bq.gifts.retrieve('gft_01HZ...')

gift, err := bq.Gifts.Retrieve(ctx, "gft_01HZ...")

Example response

{ "id": "gft_01HZ...", "status": "settled", "amount_cents": 2500, ... }

Returns: The Gift object.

GET /v1/gifts

List gifts. Filterable by sender, recipient, status, or time window.

Field	Type		Description
from	string	optional	Only gifts with this sender identity.
to	string	optional	Only gifts with this recipient identity.
status	string	optional	pending\|settling\|settled\|failed\|reversed
created_after	string	optional	RFC 3339 timestamp.
created_before	string	optional	RFC 3339 timestamp.
limit	integer	optional	Default 25. Max 100.
cursor	string	optional	Opaque pagination cursor from the previous response.

Example request

curl 'https://api.bequest.org/v1/gifts?status=settled&limit=50' \
  -H "Authorization: Bearer $BQ_KEY"

const page = await bq.gifts.list({
  status: 'settled',
  limit:  50,
});

for (const gift of page.data) {
  // ...
}

page = bq.gifts.list(status='settled', limit=50)

for gift in page.data:
    pass

$page = $bq->gifts->list([
    'status' => 'settled',
    'limit'  => 50,
]);

foreach ($page->data as $gift) {
    // ...
}

page = bq.gifts.list(status: 'settled', limit: 50)

page.data.each do |gift|
  # ...
end

page, err := bq.Gifts.List(ctx, &bequest.GiftListParams{
    Status: bequest.String("settled"),
    Limit:  50,
})

for _, gift := range page.Data {
    // ...
}

Example response

{
  "data": [ { "id": "gft_...", "status": "settled", ... } ],
  "has_more":    true,
  "next_cursor": "eyJpZCI6Imdmd..."
}

Returns: A page of Gift objects + pagination cursor.

POST /v1/gifts/{id}/refund

Refund a settled gift. Refunds the platform fee as well.

Field	Type		Description
id	string	required	The gift to refund.
reason	string	optional	Free-text reason recorded on the audit trail.

Example request

curl -X POST https://api.bequest.org/v1/gifts/gft_01HZ.../refund \
  -H "Authorization: Bearer $BQ_KEY" \
  -d '{"reason": "Donor requested"}'

const refunded = await bq.gifts.refund('gft_01HZ...', {
  reason: 'Donor requested',
});

refunded = bq.gifts.refund(
    'gft_01HZ...',
    reason='Donor requested',
)

$refunded = $bq->gifts->refund('gft_01HZ...', [
    'reason' => 'Donor requested',
]);

refunded = bq.gifts.refund('gft_01HZ...', reason: 'Donor requested')

refunded, err := bq.Gifts.Refund(ctx, "gft_01HZ...", &bequest.RefundParams{
    Reason: bequest.String("Donor requested"),
})

Example response

{ "id": "gft_01HZ...", "status": "reversed", "refunded_at": "2026-05-16T09:01:22Z" }

Returns: The Gift object with status set to reversed.

Events

Gifts emit the following events to subscribed webhook endpoints:

gift.created
gift.settled — receipt is included in the payload when applicable.
gift.failed
gift.reversed