UniPin TopUp API

Overview

Two ways to place an order. Sync holds the connection open and returns the result directly. Callback accepts the order immediately with 202 Accepted and posts the result to a URL you provide once the vouchers have been processed.

Authentication

Every request needs your API token, a UUID issued with your account. Send it in any one of three ways — the server checks the header first, then the query string, then the body.

The Bearer prefix is optional in the header, and any body field holding a UUID is accepted, so an existing apikey field keeps working.

curl -X POST https://your-domain.com/topup-sync \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"orderid":"ORD-1001","playerid":"850059596","code":"BDMB-T-S-02762503 6451-1144-9921-7716"}'

Places the order and returns the full result in the same response. Use this when your client can wait — a single voucher typically takes a few seconds.

Request body

{
  "orderid": "ORD-1001",
  "playerid": "850059596",
  "code": "BDMB-T-S-02762503 6451-1144-9921-7716"
}

{
  "orderid": "ORD-1002",
  "playerid": "850059596",
  "code": [
    "BDMB-T-S-02762503 6451-1144-9921-7716",
    "UPBD-Q-S-02762504 1111-2222-3333-4444"
  ]
}

Response — 200 OK

{
  "status": "success",
  "orderid": "ORD-1002",
  "username": "NabilFF",
  "total": 2,
  "success": 1,
  "failed": 1,
  "batch": [
    { "uc": "BDMB-T-S-02762503 6451-1144-9921-7716", "ok": false, "detail": "Used Uc Code" },
    { "uc": "UPBD-Q-S-02762504 1111-2222-3333-4444", "ok": true,  "detail": "Success" }
  ],
  "time_taken": "9.42s",
  "copyright": "Xtreme Dev"
}

Same fields as /topup-sync, plus url — the address the result is posted to. The request returns immediately; processing continues in the background.

curl -X POST https://your-domain.com/topup \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"orderid":"ORD-1003","playerid":"850059596","code":"BDMB-T-S-02762503 6451-1144-9921-7716","url":"https://your-site.com/callback"}'

Immediate response — 202 Accepted

{
  "status": "accepted",
  "orderid": "ORD-1003",
  "message": "Order queued. Result will be posted to your callback URL."
}

Reply 2xx from your callback endpoint to acknowledge. A failed delivery is retried up to 3 times.

Callback Payloads

Three outcomes are posted to your url. A single-code order is never partial — it is either success or failed.

{
  "status": "success",
  "orderid": "ORD-1001",
  "nickname": "NabilFF",
  "content": "✅ Success",
  "batch": [
    {
      "uc": "BDMB-T-S-...",
      "ok": true,
      "detail": "✅ Success"
    }
  ],
  "time_taken": "4.71s",
  "copyright": "Xtreme Dev"
}

{
  "status": "partial",
  "orderid": "ORD-1002",
  "nickname": "NabilFF",
  "content": {
    "batch": [
      {
        "uc": "BDMB-T-S-...",
        "ok": true,
        "detail": "✅ Success"
      },
      {
        "uc": "UPBD-Q-S-...",
        "ok": false,
        "detail": "❌ Used Uc Code"
      }
    ]
  },
  "time_taken": "9.42s",
  "copyright": "Xtreme Dev"
}

{
  "status": "failed",
  "orderid": "ORD-1004",
  "nickname": null,
  "content": "❌ Invalid Player ID",
  "batch": [],
  "time_taken": "1.12s",
  "copyright": "Xtreme Dev"
}

Returns your account state and remaining credits. Pass your own token as the path segment.

curl https://your-domain.com/status/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

{
  "status": "success",
  "data": {
    "name": "Default Shop",
    "account_status": "active",
    "credits": {
      "max_limit": 1000,
      "limit_left": 742,
      "used_this_month": 258
    },
    "expiry_date": null,
    "is_expired": false
  }
}

expiry_date is null on accounts with no expiry.

Credits

Credits are consumed per code, not per request. An order that never reached the redemption step costs nothing.

Packages

The denomination is read from the voucher serial — send the code as it is and the right package is chosen automatically. Both payment methods are supported for every package.

# both of these redeem the 25 Diamond package
BDMB-T-S-02762503 6451-1144-9921-7716   # UniPin Voucher
UPBD-Q-S-02762504 1111-2222-3333-4444   # Up Gift Card

Error Codes

Errors return {"error": "...", "status": "error"} with the matching HTTP status. Nothing is charged unless the order reached redemption.

{
  "error": "Missing / Invalid API token",
  "status": "error"
}