BechinBerim Developer Portal

Available Services v1

One API key, one credit wallet, all services. Create an order through any service below, then settle it from your partner credit — no per-transaction gateway needed.

Flights

Search, revalidate, book and issue tickets for domestic and international flights.

Hotels

Search availability, check live rates, book and cancel domestic & international hotels.

Travel Products

Pocket WiFi modems, SIM cards and accessories delivered to the traveller.

Tours

Browse tour packages, prebook and finalize with passenger details.

Residence

Villa & residence reservations with modify / cancel workflows.

Visa

Visa product catalogue and application requests.

BASE URL https://api.bechinberim.com

Authentication

Every request is authenticated with your two partner credentials, sent as HTTP headers. There is no OAuth or bearer token — just your key and secret on each call over HTTPS.

Your credentials

X-API-KEYa1b2c3d4e5f6……（64 hex chars）

X-API-SECRET••••••••••••••••••••••••（shown once at issue）

Keep your secret safe. It is shown only once when the account is created and stored hashed on our side. Never expose it in browser or mobile client code. Contact us to rotate it if it leaks.

Required headers (all requests)

X-API-KEYstringrequiredYour partner API key.

X-API-SECRETstringrequiredYour partner API secret.

Content-Typestringfor POSTapplication/json

curl https://api.bechinberim.com/api/partners/wallet/ \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET"

const res = await fetch("https://api.bechinberim.com/api/partners/wallet/", {
  headers: {
    "X-API-KEY": "YOUR_API_KEY",
    "X-API-SECRET": "YOUR_API_SECRET"
  }
});
const { ok, data } = await res.json();

import requests

headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "X-API-SECRET": "YOUR_API_SECRET",
}
r = requests.get("https://api.bechinberim.com/api/partners/wallet/", headers=headers)
print(r.json())

How Billing Works

You hold a credit wallet with us. It has a prepaid balance plus a credit_limit we grant you — so your spendable amount is available = balance + credit_limit, and the balance may go negative down to -credit_limit. Every service purchase is settled against this wallet.

Create an order through any service (e.g. POST /api/products/checkout/, POST /api/hotel/order/, POST /api/flights/air_booking/). The order is created in pending state and returns an id.

Pay it with credit — POST /api/partners/pay/ with the order_id (travel) or product_order_id (products). We atomically debit your wallet and finalize the booking (ticketing / reservation).

Confirm status — the pay response returns order_status: "completed" and your new_balance. You can also poll GET /api/partners/orders/.

Idempotency. Pass an idempotency_key on /pay/. Retries with the same key never double-charge. If finalization fails (e.g. the airline rejects), the debit is automatically reversed and the key released so you can retry.

Response Envelope & Errors

Every response is wrapped in a consistent envelope. Success returns ok: true with a data payload; failures return ok: false with an error message. Lists are paginated.

// success
{ "ok": true, "data": { … } }

// error
{ "ok": false, "error": "Insufficient partner credit." }

// paginated list (inside data)
{ "ok": true, "data": {
    "current_page": 1, "total_pages": 4, "total_count": 52,
    "next": "…?page=2", "previous": null, "results": [ … ] } }

Code	Meaning
`200 / 201`	Success.
`400`	Validation error, or order not payable (already completed / not yours).
`401`	Missing or invalid `X-API-KEY` / `X-API-SECRET`.
`402`	Insufficient credit — amount exceeds your available balance + limit.
`404`	Resource not found.

Credit & Wallet API

Inspect your wallet, review the transaction ledger, pay orders, and list what you've purchased.

GET/api/partners/wallet/Wallet balance & credit

Returns your current balance, granted credit limit, spendable amount and currency.

{ "ok": true, "data": {
    "balance": "1200000", "credit_limit": "5000000",
    "available": "6200000", "currency": "Toman",
    "updated_at": "2026-07-21T10:00:00Z" } }

200 OK401 Unauthorized

GET/api/partners/ledger/Transaction ledger

Paginated, append-only history of every movement: payments, refunds, top-ups and credit grants. Each row carries a balance_after snapshot.

Query parameters

pageintegeroptionalPage number. Page size is 15.

Row fields

directionstringdebit or credit

typestringpayment, refund, topup, credit_grant, adjustment

amount / balance_afterdecimalMovement amount and resulting balance.

order / product_orderintegerThe related order id, when applicable.

200 OK401 Unauthorized

POST/api/partners/pay/Pay an order with credit

Settle a travel order or a product order from your wallet. Provide exactly one of the two ids.

Request body

order_idintegerone ofA travel Order id (flight / hotel / tour / residence).

product_order_idintegerone ofA ProductOrder id (WiFi / SIM / accessory).

idempotency_keystringoptionalSafe-retry key, unique per payment. Max 128 chars.

# request
{ "order_id": 4821, "idempotency_key": "po-4821-try1" }

# response
{ "ok": true, "data": {
    "ledger_id": 9912, "amount": 3450000,
    "new_balance": -2250000, "available": 2750000,
    "order_status": "completed", "order_id": 4821 } }

200 OK400 Not Payable401 Unauthorized402 Insufficient Credit

GET/api/partners/orders/List travel orders

Paginated list of your travel orders (flight / hotel / tour / residence) with service, status, total_price and payment_method.

200 OK401 Unauthorized

GET/api/partners/product-orders/List product orders

Paginated list of your product orders with status, total_price_irt and payment_method.

200 OK401 Unauthorized

Travel Products API

Pocket WiFi modems, SIM cards and accessories. Build a basket, check out to create a product order, then pay it with credit.

GET/api/products/products/List products

Query parameters

searchstringoptionalFree-text search over product name.

categoryintegeroptionalFilter by category id (see /api/products/product-categories/).

pageintegeroptionalPage number.

Product detail: GET /api/products/products/{id}/. Categories: GET /api/products/product-categories/.

200 OK401 Unauthorized

POST/api/products/basket/items/Add item to basket

Request body

productintegerrequiredProduct id.

quantityintegerrequiredUnits to add.

variantintegeroptionalProduct variant id, when the product has variants.

View basket: GET /api/products/basket/current · Remove item: DELETE /api/products/basket/items/{id}/

201 Created400 Validation401 Unauthorized

POST/api/products/checkout/Checkout → create product order

Turns the current basket into a ProductOrder. The response data.id is the product_order_id to pass to /api/partners/pay/.

Request body

payment_methodstringoptionalUse PARTNER_CREDIT for credit settlement. Default GATEWAY.

201 Created400 Validation401 Unauthorized

Hotels API

A multi-step flow: search → check live rate → book → order. The order step creates the travel Order you then pay with credit.

POST/api/hotel/search_hotels/Search availability

Request body

check_indaterequiredYYYY-MM-DD

check_outdaterequiredYYYY-MM-DD

city_idintegercity or hotelDestination city id.

hotel_idintegercity or hotelA specific hotel id.

nationality_idstringrequiredGuest nationality (affects pricing/rules).

roomsarrayrequiredEach: adult_count, child_count, child_ages[].

is_domesticbooleanoptionalSet true for domestic (Iranian) hotels. Default false.

200 OK400 Validation401 Unauthorized

POST/api/hotel/check_rate/Re-check a live rate

Confirms the selected room's current price and cancellation policy before booking. Pass the room/rate identifiers returned by search.

200 OK401 Unauthorized

POST/api/hotel/book/Reserve room + guest details

Holds the room with the selected rate and passenger details (first/last name, nationality, national id or passport per guest).

200 OK400 Validation401 Unauthorized

POST/api/hotel/order/Create the order

Finalizes the booking into a travel Order. Take its id and call POST /api/partners/pay/ with order_id.

201 Created401 Unauthorized

POST/api/hotel/prebook/ · /booking_data/ · /cancel_display/ · /cancel/Prebook, status & cancellation

/prebook/ holds a provisional booking; /booking_data/ fetches a booking's current data; /cancel_display/ previews the cancellation penalty; /cancel/ performs the cancellation.

200 OK401 Unauthorized

Flights API

Search → revalidate → book → issue ticket. The air_booking step creates the travel Order to settle with credit.

POST/api/flights/search_flights/Search flights

Request body

originstringrequiredOrigin IATA code, e.g. THR.

destinationstringrequiredDestination IATA code, e.g. IST.

departure_date_timedatetimerequiredISO 8601 departure.

return_date_timedatetimeround tripReturn leg for round trips.

adult_count / child_count / infant_countintegeroptionalPassenger counts. Default adult 1.

cabin_typeenumrequiredCabin class.

air_trip_typeenumrequiredOne-way / round-trip.

200 OK400 Validation401 Unauthorized

POST/api/flights/revalidate_flight/ · /air_rules/ · /air_baggages/Confirm price, fare rules & baggage

Each takes the fare_source_code from a search result. revalidate_flight re-confirms availability & price; air_rules returns fare rules; air_baggages returns the baggage allowance.

200 OK400 Validation401 Unauthorized

POST/api/flights/air_booking/Book & create order

Request body (key fields)

fare_source_codestringrequiredFrom the revalidated search result.

traveler_infoobjectrequiredContact (phone_number, email) + air_travelers[]: each with name, birth date, gender, passenger type, nationality, and national_id (Iranian) or passport (foreign).

Then issue the ticket after payment via POST /api/flights/air_order_ticket/; fetch state with POST /api/flights/air_booking_data/.

201 Created400 Validation401 Unauthorized

POST/api/flights/air_refund_display/ · /air_refund/ · /air_refund_offline/Refunds

air_refund_display previews the refundable amount; air_refund performs an online refund; air_refund_offline raises a manual refund request. Refunded amounts are credited back to your wallet.

200 OK401 Unauthorized

Tours · Residence · Visa

The same pattern: browse, create an order/booking, then settle with POST /api/partners/pay/.

GET/api/tours/Tours

GET /api/tours/ lists tours · GET /api/tours/{id}/ details · GET /api/tours/search-options/ filters · POST /api/tours/prebook/ holds seats with passengers · POST /api/tours/finalize/ creates the order.

200 OK401 Unauthorized

GET/api/residence/properties/list/Residence

/properties/list/ & /properties/detail/ to browse · POST /api/residence/reserve/ then /reserve/book/ to reserve · /reserve/time/, /reserve/detail/ for status · /bookings/cancel/ & /bookings/accept-cancel/ for cancellation.

200 OK401 Unauthorized

GET/api/visa/Visa

GET /api/visa/ lists visa products · GET /api/visa/{id}/ details · POST /api/visa/request/ submits a visa application request.

200 OK401 Unauthorized

BechinBerim Partner API

Available Services v1

Flights

Hotels

Travel Products

Tours

Residence

Visa

Authentication

How Billing Works

Response Envelope & Errors

Credit & Wallet API

Travel Products API

Hotels API

Flights API

Tours · Residence · Visa