title: "API سرور به سرور (S2S)" order: 5 description: "احراز هویت OAuth2 client credentials و endpointهای بررسی خرید، تأیید، اشتراک و بازپرداخت"
API سرور به سرور (S2S)
با این API سرور شما وضعیت معتبر خرید و اشتراک را از بلهاستور میپرسد، خرید را تأیید (acknowledge) میکند، اشتراک را لغو میکند و بازپرداخت میدهد. این API مرجع نهایی برای تصمیمگیری دربارهٔ دادن محصول به کاربر است.
- نشانی پایه:
https://api.<domain>(نشانی نهایی در حال نهاییشدن است؛ در محیط توسعه:http://localhost:18080) - همهٔ مسیرها زیر
/s2s/هستند. - قالب: JSON با کلیدهای
camelCase؛ مبالغ به ریال (عدد صحیح)؛ زمانها طبق هر فیلد (در زیر). - هدف کارایی: پاسخ بررسی خرید در صدک ۹۵ کمتر از ۳۰۰ میلیثانیه.
۱. ساخت کلاینت
در کنسول، بخش پرداخت ← دسترسی سرور به سرور یک کلاینت بسازید (POST /console/v1/billing/orgs/{orgId}/s2s-clients). پاسخ شامل clientId و clientSecret است؛ clientSecret فقط یک بار نمایش داده میشود؛ آن را در محل امن (مثلاً vault) نگه دارید. کلاینت متعلق به سازمان است و فقط به برنامههای همان سازمان دسترسی دارد. برای باطل کردن کلاینت: DELETE /console/v1/billing/orgs/{orgId}/s2s-clients/{clientId}.
scopeها
| scope | اجازه |
|---|---|
purchases.read |
خواندن وضعیت خرید |
purchases.write |
تأیید (acknowledge) خرید |
subscriptions.read |
خواندن وضعیت اشتراک |
subscriptions.write |
لغو اشتراک |
orders.refund |
بازپرداخت سفارش |
به هر کلاینت فقط scopeهای لازم را بدهید؛ مثلاً سرور بازی که فقط خرید را بررسی میکند، purchases.read و purchases.write کافی دارد.
۲. دریافت توکن دسترسی
POST /s2s/oauth/token با احراز هویت HTTP Basic (clientId:clientSecret) و بدنهٔ application/x-www-form-urlencoded:
API=https://api.<domain>
curl -sS -X POST "$API/s2s/oauth/token" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'
{
"access_token": "eyJhbGciOi…",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "purchases.read purchases.write"
}
- میتوانید با پارامتر
scope(جداشده با فاصله) زیرمجموعهای از scopeهای کلاینت را درخواست کنید. - توکن را تا نزدیک انقضا (
expires_inثانیه) کش کنید و برای هر درخواست توکن تازه نگیرید. - در همهٔ درخواستهای بعدی:
Authorization: Bearer <access_token>.
۳. بررسی خرید
GET /s2s/v1/apps/{packageName}/purchases/{purchaseToken} — scope: purchases.read
curl -sS "$API/s2s/v1/apps/com.example.game/purchases/$PURCHASE_TOKEN" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"orderId": "6f1c2a7e-3b0d-4b8e-9f51-2f7a0c9d1e44",
"productId": "coins_100",
"purchaseState": "PURCHASED",
"consumptionState": "NOT_CONSUMED",
"acknowledged": false,
"refundState": "NONE",
"purchaseTime": 1763539200000,
"developerPayload": "order-42",
"userHash": "9c1f0e…",
"test": false
}
| فیلد | توضیح |
|---|---|
orderId |
شناسهٔ یکتای سفارش (UUID). برای جلوگیری از دادن تکراری محصول، آن را در پایگاه دادهٔ خود یکتا نگه دارید. |
productId |
شناسهٔ محصول (SKU) |
purchaseState |
PENDING، PURCHASED، ACKNOWLEDGED، CONSUMED، REFUNDED، AUTO_REFUNDED |
consumptionState |
NOT_CONSUMED یا CONSUMED |
acknowledged |
آیا خرید تأیید شده است |
refundState |
NONE، PARTIAL، FULL |
purchaseTime |
زمان خرید به میلیثانیهٔ epoch |
developerPayload |
همان payload که هنگام خرید فرستادید |
userHash |
شناسهٔ مستعار و پایدار کاربر در برنامهٔ شما (هویت واقعی کاربر به شما داده نمیشود) |
test |
true برای خرید آزمایشگرهای مجوز (سندباکس) |
الگوی پیشنهادی بررسی
- برنامه
purchaseTokenوproductId(و در صورت نیازorderId) را برای سرور شما میفرستد. - سرور این endpoint را صدا میزند و بررسی میکند:
purchaseStateبرابرPURCHASED(یا برای محصول غیرمصرفی،ACKNOWLEDGED) باشد؛productIdهمان چیزی باشد که کاربر خواسته؛developerPayloadبا سفارش داخلی شما بخواند؛refundStateبرابرNONEباشد؛orderIdقبلاً استفاده نشده باشد؛- در محیط تولید،
testبرابرfalseباشد (مگر عمداً خرید آزمایشی را بپذیرید).
- محصول را به کاربر بدهید.
- خرید را نهایی کنید: محصول مصرفی را برنامه با
consumeProductمصرف میکند؛ محصول غیرمصرفی و اشتراک را با endpoint زیر (یا از برنامه) تأیید کنید.
⚠️ خریدی که تا مهلت مقرر (پیشفرض ۳ روز، قابل تنظیم) نه مصرف شود و نه تأیید، خودکار بازپرداخت میشود (
AUTO_REFUNDED).
۴. تأیید خرید
POST /s2s/v1/apps/{packageName}/purchases/{purchaseToken}:acknowledge — scope: purchases.write
curl -sS -X POST "$API/s2s/v1/apps/com.example.game/purchases/$PURCHASE_TOKEN:acknowledge" \
-H "Authorization: Bearer $ACCESS_TOKEN" -o /dev/null -w '%{http_code}\n'
# 204
پاسخ موفق 204 No Content است.
۵. وضعیت اشتراک
GET /s2s/v1/apps/{packageName}/subscriptions/{purchaseToken} — scope: subscriptions.read
curl -sS "$API/s2s/v1/apps/com.example.game/subscriptions/$PURCHASE_TOKEN" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"status": "IN_GRACE",
"expiryTime": 1766131200000,
"autoRenewing": true,
"inGrace": true,
"graceEndsAt": "2026-12-22T08:00:00Z"
}
status |
معنی | دسترسی کاربر |
|---|---|---|
ACTIVE |
فعال | بله |
IN_GRACE |
تمدید ناموفق، در دورهٔ مهلت (پیشفرض ۳ روز، قابل تنظیم برای هر محصول) | بله |
ON_HOLD |
پس از پایان مهلت، تا پرداخت موفق معلق | خیر |
EXPIRED |
منقضی | خیر |
CANCELED |
کاربر لغو کرده؛ تا پایان دورهٔ جاری فعال میماند | تا expiryTime |
۶. لغو اشتراک
POST /s2s/v1/apps/{packageName}/subscriptions/{purchaseToken}:cancel — scope: subscriptions.write
curl -sS -X POST "$API/s2s/v1/apps/com.example.game/subscriptions/$PURCHASE_TOKEN:cancel" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# 204
تمدید خودکار متوقف میشود و اشتراک تا پایان دورهٔ جاری فعال میماند.
۷. بازپرداخت
POST /s2s/v1/apps/{packageName}/orders/{orderId}:refund — scope: orders.refund
curl -sS -X POST "$API/s2s/v1/apps/com.example.game/orders/$ORDER_ID:refund" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Idempotency-Key: refund-$ORDER_ID-1" \
-H 'content-type: application/json' \
-d '{"amountRials": 50000}'
{ "refundId": "0b9d5c3e-8a41-4f0e-a3b2-61c7d9e2f810", "amountRials": 50000 }
- بدون
amountRialsبازپرداخت کامل است؛ با آن، جزئی. - مجموع بازپرداختها نمیتواند از مبلغ سفارش بیشتر شود (
REFUND_EXCEEDS_AMOUNT). - حتماً
Idempotency-Keyبفرستید. اگر پاسخ را بهخاطر خطای شبکه دریافت نکردید، همان درخواست را با همان کلید و همان بدنه دوباره بفرستید؛ همان پاسخ برمیگردد و بازپرداخت دوبار انجام نمیشود. - پس از بازپرداخت، رویداد
purchase.refundedبه Webhook شما فرستاده میشود.
۸. خطاها
همهٔ پاسخهای غیر-2xx این شکل را دارند؛ message فارسی و قابل نمایش است:
{ "error": { "code": "PURCHASE_NOT_FOUND", "message": "خرید پیدا نشد.", "details": {} } }
| HTTP | code |
معنی |
|---|---|---|
| 400 / 422 | VALIDATION_FAILED |
ورودی نامعتبر؛ جزئیات در details.fields |
| 401 | UNAUTHORIZED |
توکن نامعتبر، منقضی یا کلاینت باطلشده؛ توکن تازه بگیرید |
| 403 | FORBIDDEN |
scope کافی نیست یا برنامه متعلق به سازمان شما نیست |
| 404 | PURCHASE_NOT_FOUND / NOT_FOUND |
خرید یا سفارش با این مشخصات برای این بسته وجود ندارد |
| 409 | ALREADY_CONSUMED |
خرید قبلاً مصرف شده است |
| 409 | REFUND_EXCEEDS_AMOUNT |
مبلغ بازپرداخت بیش از مبلغ باقیماندهٔ سفارش است |
| 409 | CONFLICT |
وضعیت فعلی اجازهٔ این کار را نمیدهد |
| 429 | RATE_LIMITED |
درخواست بیش از حد مجاز |
| 503 | BILLING_DISABLED / FEATURE_DISABLED / UPSTREAM_UNAVAILABLE |
سرویس موقتاً در دسترس نیست |
| 500 | INTERNAL |
خطای داخلی |
۹. Idempotency و تلاش دوباره
- درخواستهای خواندنی (
GET) را میتوانید آزادانه تکرار کنید. - برای درخواستهای مالی (بازپرداخت) سرآیند
Idempotency-Keyبفرستید: کلید یکسان + بدنهٔ یکسان = همان پاسخ. - در پاسخ
429و5xxبا backoff نمایی و jitter تلاش دوباره کنید. سقف نرخ درخواست در پیکربندی بلهاستور تعریف میشود (قابل تنظیم)؛ به مقدار مشخصی وابسته نشوید.
۱۰. نمونه با Python
import time, requests
API = "https://api.<domain>"
_token = {"value": None, "exp": 0}
def access_token(client_id: str, client_secret: str) -> str:
if _token["value"] and time.time() < _token["exp"] - 60:
return _token["value"]
r = requests.post(f"{API}/s2s/oauth/token", auth=(client_id, client_secret),
data={"grant_type": "client_credentials"}, timeout=5)
r.raise_for_status()
body = r.json()
_token.update(value=body["access_token"], exp=time.time() + body["expires_in"])
return _token["value"]
def verify_purchase(package: str, purchase_token: str, expected_sku: str, token: str) -> dict:
r = requests.get(f"{API}/s2s/v1/apps/{package}/purchases/{purchase_token}",
headers={"Authorization": f"Bearer {token}"}, timeout=5)
if r.status_code == 404:
raise ValueError("purchase not found")
r.raise_for_status()
p = r.json()
if p["productId"] != expected_sku or p["purchaseState"] not in ("PURCHASED", "ACKNOWLEDGED") \
or p["refundState"] != "NONE":
raise ValueError(f"purchase not valid: {p}")
return p # then: check p["orderId"] is unused, grant, acknowledge/consume
موضوعات مرتبط
- Webhookها: دریافت رویدادهای خرید، بازپرداخت و اشتراک
- تأیید توکن خرید: بررسی امضای ES256 بدون فراخوانی شبکه
- SDK اندروید