YevlenYevlen
Browse documentation

Vouchers

Voucher quickstart

Use an independent application and sop_ token to manage templates, issuance, verification, redemption, and reversal.

Prepare the integration

  1. Sign in to the Open Platform console and create an application.
  2. Create a voucher template in the application and submit it for review. Only approved templates can be issued.
  3. Generate an sop_ token with the least scopes required by the service. The full token is shown once.

Issue to a specific user

Issue from your server with vouchers:issue. recipient_user_id must come from user authorization or an existing business relationship and must not be enumerated.

curl -X POST "$API/api/v1/open-platform/vouchers/issue" \
  -H "Authorization: Bearer $OPEN_PLATFORM_TOKEN" \
  -H "Idempotency-Key: order_20260903_001" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "external_issue_id": "benefit_20260903_001",
    "recipient_user_id": "AUTHORIZED_SOCHAT_USER_ID"
  }'
Use a unique Idempotency-Key for each business action. Network retries must reuse the same key and request body.

Verify, redeem, and reverse

Verification is read-only. Redemption and reversal change voucher state and must be called from trusted servers with separate idempotency keys.

POST /api/v1/open-platform/vouchers/verify
POST /api/v1/open-platform/vouchers/redeem
GET  /api/v1/open-platform/vouchers/redemptions/:redemptionId
POST /api/v1/open-platform/vouchers/redemptions/:redemptionId/reverse

Optional: deliver through a bot

Link an approved bot owned by the same account to deliver application vouchers in private chats. These calls use the Bot Token and bot endpoint.

POST /api/v1/bots/vouchers/issue
Authorization: Bearer sbot_...

{
  "chat_id": "PRIVATE_CHAT_ID",
  "template_id": "APPLICATION_TEMPLATE_ID",
  "external_issue_id": "benefit_20260903_002"
}

Unlinking only disables bot delivery. It does not delete the application, templates, issued vouchers, or sop_ tokens.

Security and business boundaries

  • Keep sop_ tokens and Bot Tokens on trusted servers only.
  • Issue only to authorized users or users with an existing business relationship, and retain authorization evidence.
  • Treat voucher codes and QR data as redemption credentials and prevent unrelated parties from accessing them.
  • Developers own benefits, redemption rules, fulfillment, and support. The platform does not sell vouchers or collect payment.
Create applicationView API