Transfers

A Transfer is a debit — a sale. It charges a Payment Instrument, settles the proceeds to a Merchant, and keeps your platform fee. This is the core money-movement primitive.

Create a transfer

POST/v1/transfers

Charge a card and settle to a merchant with a platform fee.

`merchant` stringrequired	The venue receiving the funds (MU…).
`source` stringrequired	The Payment Instrument to charge (PI…).
`amount` integerrequired	Total charged to the card, in cents (bill + tip + tax).
`fee` integeroptional	Your platform fee in cents, kept from the amount. The merchant is settled amount − fee.
`currency` stringrequired	ISO-4217. CAD or USD.
`idempotency_id` stringoptional	Safely retry without double-charging.
`tags` objectoptional	Free-form metadata (e.g. your check id).

curl -u "$YUSKER_KEY" "$YUSKER_BASE/transfers" \
  -H "Content-Type: application/json" \
  -H "Idempotency-ID: check_4823" \
  -d '{
    "merchant": "MUxxxx",
    "source": "PIxxxx",
    "amount": 5000,
    "fee": 175,
    "currency": "CAD",
    "tags": { "check_id": "4823" }
  }'
# -> { "id": "TRxxxx", "state": "SUCCEEDED", "amount": 5000, "fee": 175, "ready_to_settle_at": "..." }

How the fee works

Yusker uses destination charges: the diner is charged amount, the merchant is settled amount − fee, and Yusker keeps fee as platform revenue. Compute the fee on the full amount charged (bill + tip + tax) — the same base the networks charge you on — so your margin holds on tips.

Example

A $50.00 CAD sale at 2.90% + $0.30 → amount: 5000, fee: 175. The venue receives $48.25; Yusker earns $1.75. On the ledger this posts to processing revenue automatically.

Transfer states

PENDING — submitted, not yet authorized.
SUCCEEDED — captured and settling.
FAILED / CANCELED — declined or reversed; no funds moved.

The authoritative state transition also arrives over Webhooks — always settle on the webhook, not just the API response.

Refunds

Reverse a transfer fully or partially. The reversal returns funds to the cardholder and debits the merchant.

POST/v1/transfers/{transfer_id}/reversals

Refund a transfer.

curl -u "$YUSKER_KEY" "$YUSKER_BASE/transfers/TRxxxx/reversals" \
  -H "Content-Type: application/json" -d '{ "refund_amount": 5000 }'

Payment Instruments

Accept a payment