API Guide | SimGuyz

Authentication

Send your API token in the Authorization header. Use Idempotency-Key on all charge endpoints.

Authorization: Bearer sg_test_xxxxx
Idempotency-Key: your-unique-request-key

Test and Production

Recommended flow: integrate with sg_test_... first, verify responses, then move to sg_live_... after production is enabled.

Use sg_test_... for sandbox.
Use sg_live_... for production.
Sandbox supports safe testing for topups, activations, eSIM, and labels where available.
Production uses your live wallet and real provider connectivity.

Integration Flow

Step 1

Open API Tokens

Use the assigned token visible in your portal.

Step 2

Load Catalogs

Read client SKU values from the catalog endpoints.

Step 3

Send Request

Submit topup, activation, eSIM, or shipping payload.

Step 4

Track Status

Use transaction lookup and job status endpoints where needed.

Endpoints

Identifier Map

Product	Field To Send	Example	Get It From
TopUp	`sku`	`YOUR_TOPUP_SKU`	`GET /api/v1/catalog/topups`
LinkUp Activation	`sku`	`YOUR_LINKUP_SKU`	`GET /api/v1/catalog/activations`
Travel eSIM	`plan_id`	`123`	`GET /api/v1/catalog/esim`
T-Mobile Activation	`plan_id`	`TMO_STD_1`	`GET /api/v1/catalog/activations`
Shipping Label	Request body only	`from_address`, `to_address`, `parcel`	Direct request body

Available Endpoints

GET

/api/v1/wallet

Read API wallet balance and billing mode.

GET

/api/v1/transactions/{id}

Read saved transaction status and response.

GET

/api/v1/catalog/topups

Load visible topup SKU values.

POST

/api/v1/topups

Submit topup request.

GET

/api/v1/catalog/activations

Load LinkUp and T-Mobile SKU values.

POST

/api/v1/activations/linkup

Submit LinkUp physical or eSIM activation.

POST

/api/v1/activations/tmobile

Submit T-Mobile activation request.

GET

/api/v1/catalog/esim

Load Travel eSIM plans.

POST

/api/v1/esim/orders

Create Travel eSIM order.

POST

/api/v1/shipping/labels

Create label and tracking response.

Request and Response JSON

Download Postman

Wallet

Request

curl "http://www.simguyz.com/api/v1/wallet" \
  -H "Authorization: Bearer sg_test_xxxxx"

Response JSON

{
  "request_id": "req_7f2b9ab1",
  "status": "success",
  "environment": "test",
  "client_id": 12,
  "client_name": "WEST COAST WIRELESS",
  "billing_mode": "prepaid",
  "balance": "10000.00",
  "currency": "USD"
}

Transaction Lookup

Request

curl "http://www.simguyz.com/api/v1/transactions/145" \
  -H "Authorization: Bearer sg_test_xxxxx"

Response JSON

{
  "request_id": "req_34be8d90",
  "status": "success",
  "transaction": {
    "id": 145,
    "environment": "test",
    "product_type": "topup",
    "product_key": "100039",
    "provider": "surgepays",
    "status": "success",
    "sell_price": "8.40",
    "provider_cost": "7.20",
    "response": {
      "sku": "YOUR_TOPUP_SKU",
      "account_number": "5551234567",
      "amount": "10.00"
    }
  }
}

Topup

Request

{
  "sku": "YOUR_TOPUP_SKU",
  "account_number": "5551234567",
  "amount": "10.00",
  "external_id": "topup_1001"
}

Success Response JSON

{
  "request_id": "req_8413a912",
  "status": "success",
  "transaction_id": "145",
  "product_type": "topup",
  "provider": "surgepays",
  "amount_charged": "8.40",
  "environment": "test",
  "data": {
    "provider_status": "approved",
    "provider_transaction_id": "test_145",
    "sku": "YOUR_TOPUP_SKU",
    "account_number": "5551234567",
    "amount": "10.00",
    "balance_after": "9991.60"
  }
}

Failed Response JSON

{
  "request_id": "req_8413a912",
  "status": "failed",
  "transaction_id": "145",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is too low."
  },
  "environment": "live"
}

LinkUp Activation

Physical activation needs sim, area_code, and zip. For eSIM, send esim, imei, email, area_code, and zip.

Request

{
  "sku": "YOUR_LINKUP_SKU",
  "sim": "1234567890123456789",
  "area_code": "213",
  "zip": "90001",
  "imei": "123456789012345",
  "external_id": "linkup_1001"
}

Success Response JSON

{
  "request_id": "req_7021c8de",
  "status": "success",
  "transaction_id": "244",
  "product_type": "activation",
  "product_key": "8016",
  "provider": "linkup",
  "amount_charged": "12.50",
  "environment": "live",
  "data": {
    "provider_status": "APPROVED",
    "provider_transaction_id": "LKP993821",
    "phone_number": "2135559821",
    "sku": "YOUR_LINKUP_SKU",
    "balance_after": "756.39"
  }
}

Validation Error JSON

{
  "request_id": "req_7021c8de",
  "status": "failed",
  "transaction_id": "244",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "For LinkUp physical activation, sim is required."
  },
  "environment": "test"
}

LinkUp eSIM Activation

Request

{
  "sku": "YOUR_LINKUP_ESIM_SKU",
  "esim": "2",
  "area_code": "213",
  "zip": "90001",
  "imei": "123456789012345",
  "email": "customer@example.com",
  "external_id": "linkup_esim_1001"
}

Success Response JSON

{
  "request_id": "req_31bd88f0",
  "status": "success",
  "transaction_id": "245",
  "product_type": "activation",
  "provider": "linkup",
  "amount_charged": "14.00",
  "environment": "live",
  "data": {
    "provider_status": "APPROVED",
    "provider_transaction_id": "LKE992191",
    "phone_number": "2135551122",
    "qr_code": "base64-or-url-value",
    "sku": "YOUR_LINKUP_ESIM_SKU"
  }
}

Travel eSIM

Request

{
  "plan_id": "123",
  "user_id": "dealer@example.com",
  "external_id": "esim_1001"
}

Success Response JSON

{
  "request_id": "req_0aa9e811",
  "status": "success",
  "transaction_id": "302",
  "product_type": "esim",
  "product_key": "yesim:123",
  "provider": "yesim",
  "amount_charged": "18.50",
  "environment": "live",
  "data": {
    "plan_id": "123",
    "iccid": "8901000000000000000",
    "qr_code": "LPA:1$example$code",
    "balance_after": "723.89"
  }
}

T-Mobile Activation

Request

{
  "plan_id": "TMO_STD_1",
  "sim": "1234567890123456789",
  "pin": "264626",
  "zip_code": "90001",
  "external_id": "tmobile_1001"
}

Accepted / Processing Response JSON

{
  "request_id": "req_8bf0ac44",
  "status": "success",
  "transaction_id": "415",
  "product_type": "activation",
  "product_key": "tmobile:TMO_STD_1",
  "provider": "tmobile",
  "amount_charged": "11.00",
  "environment": "live",
  "data": {
    "job_id": "tm_5042",
    "plan_id": "TMO_STD_1",
    "sku": "YOUR_TMO_SKU"
  }
}

Shipping Label

Request

{
  "from_address": {
    "name": "Sender Name",
    "street1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "country": "US"
  },
  "to_address": {
    "name": "Receiver Name",
    "street1": "456 Oak St",
    "city": "Houston",
    "state": "TX",
    "zip": "77001",
    "country": "US"
  },
  "parcel": {
    "length": 8,
    "width": 6,
    "height": 4,
    "weight": 16
  }
}

Success Response JSON

{
  "request_id": "req_21be11d2",
  "status": "success",
  "transaction_id": "510",
  "product_type": "shipping",
  "product_key": "label",
  "provider": "easypost",
  "amount_charged": "4.50",
  "environment": "live",
  "data": {
    "label_id": "shp_123456",
    "tracking_number": "1Z999AA10123456784",
    "label_url": "https://label.example/123.pdf",
    "balance_after": "719.39"
  }
}

Common Error Codes

Code	Meaning
`AUTH_MISSING`	Bearer token was not sent.
`AUTH_INVALID`	Token is invalid.
`SCOPE_DENIED`	Token does not include required scope.
`IDEMPOTENCY_REQUIRED`	Charge endpoint needs `Idempotency-Key`.
`IDEMPOTENCY_CONFLICT`	Same key reused with different payload.
`INSUFFICIENT_BALANCE`	Wallet balance is too low.
`VALIDATION_ERROR`	Required request fields are missing or invalid.
`UPSTREAM_DECLINED`	Provider rejected the request.
`UPSTREAM_ERROR`	Provider connection failed or bad response.
`LIVE_BRIDGE_DISABLED`	Async live bridge is not enabled for that flow yet.

Webhook Format

Use this payload shape for async transaction updates and webhook deliveries.

Webhook Payload

{
  "event": "transaction.success",
  "environment": "test",
  "transaction_id": "123",
  "request_id": "req_xxxxx",
  "product_type": "topup",
  "provider": "linkup",
  "status": "success",
  "data": {}
}

Rules and Notes

Full token value is shown only once when created or replaced.
Always save and reuse your own unique external_id and Idempotency-Key.
Use test token first, then move to production after approval.
Live MobileX and live T-Mobile remain gated until callback-to-wallet reconciliation is fully enabled.

SimGuyz API Guide

Authentication

Test and Production

Integration Flow

Endpoints

Identifier Map

Available Endpoints

Request and Response JSON

Wallet

Transaction Lookup

Topup

LinkUp Activation

LinkUp eSIM Activation

Travel eSIM

T-Mobile Activation

Shipping Label

Common Error Codes

Webhook Format

Rules and Notes