Payments & wallet
Order checkout (methods, session, status, refunds) and wallet deposits via Stripe, PayPal, Chargily, SATIM and in-app purchase.
Feeef has two payment surfaces that look similar but are not interchangeable:
| Surface | Pays for | Typical caller |
|---|---|---|
Order payment (/v1/orders/{orderId}/payment/*) | A customer's order (COD complement, card, SATIM, …) | Storefront / guest |
Wallet deposits (/v1/deposits/*) | Topping up a Feeef user wallet (subscriptions, paid templates, integrations) | Signed-in merchant |
Neither surface is fully wrapped by the JavaScript SDK today — use feeef.client (axios) or Dart Feeef.instance.deposits where noted.
Order payment flow
Prefix: /v1/orders/{orderId}/payment. Most steps are public so a guest who just placed a COD/card order can finish checkout without a Feeef account.
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | …/methods | Public | Payment methods enabled for this order's store |
POST | …/select | Public | Pin a method on the order ({ "method": "satim" }) |
POST | …/checkout | Public | Create a provider checkout session / redirect URL |
GET | …/status | Public | Poll payment status after the customer returns |
POST | …/webhook | Public (provider) | Order-level webhook (legacy; prefer store webhook) |
POST | …/refund | Bearer | Refund if the method supports it |
GET | …/refund/{refundId}/status | Bearer | Refund status |
POST | /v1/orders/{orderId}/payment/satim/initiate | Public | SATIM-specific initiate (CIB/Edahabia) |
POST | /v1/stores/{storeId}/payment/webhook | Public (provider) | Store-level payment webhook |
List methods
curl "https://api.feeef.org/v1/orders/{orderId}/payment/methods"Returns the methods the store has configured (and that apply to this order's currency / country).
Select, then checkout
curl -X POST "https://api.feeef.org/v1/orders/{orderId}/payment/select" \
-H "Content-Type: application/json" \
-d '{"method":"satim"}'
curl -X POST "https://api.feeef.org/v1/orders/{orderId}/payment/checkout" \
-H "Content-Type: application/json" \
-d '{"returnUrl":"https://shop.example/thanks","cancelUrl":"https://shop.example/checkout"}'The checkout body is method-specific (return URLs, SATIM force_terminal_id, …). The response typically includes a redirectUrl or sessionId for the customer.
Confirm
Poll GET …/status (or wait for the store/order webhook). Do not mark the order paid from the browser redirect alone — the webhook / status call is the source of truth.
curl "https://api.feeef.org/v1/orders/{orderId}/payment/status"Refunds require a merchant token. Not every method implements refunds — a 4xx with a clear message means "this provider does not support it".
Wallet deposits
A deposit is a wallet top-up row (pending → completed | failed | cancelled). List/show via the deposits resource; create through a provider-specific start endpoint (never invent a completed row yourself).
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /v1/deposits | Bearer | List your deposits |
GET | /v1/deposits/{id} | Bearer | Show one |
POST | /v1/deposits/send | Bearer | Manual / attachment deposit request |
POST | /v1/deposits/stripe/create-session | Bearer | Stripe Checkout session |
GET | /v1/deposits/stripe/session/{sessionId} | — | Session status |
POST | /v1/deposits/stripe/webhook | Stripe signature | Completes the deposit |
POST | /v1/deposits/paypal/create-order | Bearer | PayPal order + approval URL |
POST | /v1/deposits/paypal/capture-order | Public | Capture after the buyer returns |
GET | /v1/deposits/paypal/order/{orderId} | Bearer | PayPal order status |
POST | /v1/deposits/paypal/webhook | Public | Provider webhook |
POST | /v1/deposits/chargily/create-checkout | Bearer | Chargily Pay checkout (DZD) |
GET | /v1/deposits/chargily/checkout/{checkoutId} | Bearer | Checkout status |
POST | /v1/deposits/chargily/webhook | Public | Provider webhook |
POST | /v1/deposits/satim/create | Bearer | SATIM (CIB / Edahabia) order |
POST | /v1/deposits/satim/confirm | Bearer | Confirm after return |
GET | /v1/deposits/satim/check/{orderId} | Bearer | Poll SATIM |
POST | /v1/deposits/satim/refund | Bearer | SATIM refund |
POST | /v1/deposits/inAppPurchase/verify | Bearer | Apple/Google IAP receipt |
GET | /v1/deposits/inAppPurchase/status/{depositId} | Bearer | IAP verification status |
// Manual request
await feeef.deposits.send({ amount: 5000, currency: 'DZD', note: 'bank transfer' })
// PayPal
const paypal = await feeef.deposits.createPayPalOrder({
amount: 20,
currency: 'USD',
returnUrl: 'https://app.example/wallet/return',
cancelUrl: 'https://app.example/wallet/cancel',
})
// send the user to paypal.approvalUrl, then:
await feeef.deposits.capturePayPalOrder(paypal.id)Provider webhooks (…/webhook) are public by design and authenticated with the provider's signature (Stripe uses dedicated verifyStripeWebhook middleware). Do not call them from your app. Completing a deposit is the webhook's job — polling status / session is for UX only.
Transfers
/v1/transfers moves wallet balance between Feeef users (payouts, marketplace earnings). CRUD is a separate resource from deposits — see the generated Transfers reference. Finance-module transfers (/v1/finance/transfers) are a different ledger (store books), documented under Finance.