Quartermaster eSIM

Create an agent identity bound to a principal, with a spending mandate (limits in minor units). Returns agent_key once; send it on every later call. The first agent of a new principal_id also receives principal_key (once): the principal owns the wallet, and every later register_agent for that principal_id must present principal_key (argument or X-Principal-Key header), else PRINCIPAL_KEY_REQUIRED. New agents are capped by the registration policy (see get_policies).

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{3,128}$"
    },
    "principal_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:@-]{3,128}$"
    },
    "principal_key": {
      "description": "Required if the principal already exists (or X-Principal-Key header)",
      "type": "string",
      "maxLength": 256
    },
    "mandate": {
      "type": "object",
      "properties": {
        "currency": {
          "default": "USD",
          "type": "string",
          "pattern": "^[A-Z]{3}$"
        },
        "max_per_tx": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "max_per_day": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "max_per_month": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "allowed_categories": {
          "default": [
            "esim"
          ],
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "esim"
            ],
            "description": "Product category"
          }
        },
        "expiry": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "description": "ISO 8601; at most 365 days ahead"
        }
      },
      "required": [
        "max_per_tx",
        "max_per_day",
        "max_per_month",
        "expiry"
      ]
    }
  },
  "required": [
    "agent_id",
    "principal_id",
    "mandate"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Replace your principal's principal_key. Needs your agent credentials and the current principal_key (argument or X-Principal-Key header). Returns the new key once; the old one stops working. Existing agents are unaffected. A principal registered before keys existed has none: any of its agents can call this without principal_key to mint the first one.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "principal_key": {
      "description": "Current principal_key (or X-Principal-Key header)",
      "type": "string",
      "maxLength": 256
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns every policy as machine-readable JSON (mandate, refund, dispute, supplier trust, registration), the store terms and the product/agent JSON Schemas, so you can reason about terms before buying.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search eSIM data plans from trusted suppliers. Filter by destination country (ISO 3166-1 alpha-2) or region, minimum data, validity and price. Results are sorted by final price unless sort says otherwise. Suppliers below the trust threshold are excluded and listed in excluded_suppliers.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "country": {
      "description": "Destination country, e.g. JP",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "region": {
      "type": "string",
      "enum": [
        "EUROPE",
        "ASIA",
        "MIDDLE_EAST",
        "NORTH_AMERICA",
        "LATIN_AMERICA",
        "OCEANIA",
        "AFRICA",
        "GLOBAL"
      ],
      "description": "Commercial coverage region"
    },
    "category": {
      "type": "string",
      "enum": [
        "esim"
      ],
      "description": "Product category"
    },
    "min_data_gb": {
      "description": "Minimum data in GB; unlimited plans always qualify",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "unlimited_only": {
      "type": "boolean"
    },
    "min_validity_days": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_validity_days": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "max_price_minor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "include_out_of_stock": {
      "type": "boolean"
    },
    "sort": {
      "type": "string",
      "enum": [
        "price",
        "price_per_gb",
        "validity"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lock the final price for one product for a short time (quote_ttl_seconds in store terms). Also returns a mandate pre-check and the refund terms, so you know before buying whether the purchase will be allowed.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "product_id": {
      "type": "string"
    }
  },
  "required": [
    "product_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Buy the product in a quote. Enforces the mandate and the wallet policy, holds the amount in the principal's wallet, orders from the supplier, debits the wallet, and returns the order with the eSIM delivery payload and a signed receipt. If the wallet is short, fails with WALLET_INSUFFICIENT_FUNDS and a ready top-up link for the principal. idempotency_key is required: reusing it returns the original order and never charges twice.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "quote_id": {
      "type": "string"
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "description": "Unique per purchase attempt, e.g. a UUID"
    }
  },
  "required": [
    "quote_id",
    "idempotency_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Balance, available funds (balance minus pending holds), open top-up links, recent top-ups and recent ledger entries of the wallet of the principal you act for. Shared by all of the principal's agents. Amounts in minor units.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "limit": {
      "description": "Recent entries to return (default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a hosted payment URL to hand to your human principal. They pay in ILS on the acquirer's page (PayPlus); you never see card data. amount_minor is in `currency`: USD (the wallet credit you want; the ILS charge is computed at today's rate) or ILS (the exact charge). The wallet is credited in USD at the rate in force when payment is confirmed. Limits are in the topup policy.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "amount_minor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Minor units of currency, e.g. 2000 = 20.00"
    },
    "currency": {
      "default": "USD",
      "type": "string",
      "enum": [
        "USD",
        "ILS"
      ]
    }
  },
  "required": [
    "amount_minor"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Current order state, eSIM delivery payload, activation and data usage from the supplier, receipts and disputes.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "order_id": {
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

For one of your own delivered orders whose activation code (QR / LPA) does not install: asks the supplier for a fresh code and returns the new delivery payload. The previous code may stop working. Not every supplier supports it (NOT_SUPPORTED_BY_SUPPLIER); then open a dispute with reason not_working.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "order_id": {
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Reasons "unused" and "changed_plans" are voluntary refunds under the refund policy. Reasons "not_delivered", "not_working" and "duplicate_purchase" open a dispute under the dispute policy, which can refund fully, partially, reject, or escalate to a human. Denials return error.code = the policy reason_code.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "order_id": {
      "type": "string"
    },
    "reason": {
      "type": "string",
      "enum": [
        "unused",
        "changed_plans",
        "not_delivered",
        "not_working",
        "duplicate_purchase"
      ]
    },
    "details": {
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "order_id",
    "reason"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check a receipt's signature and that it matches its hash-chained ledger entry.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "receipt": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "receipt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Sandbox only. Acts as the principal paying a get_topup_link URL: the mock provider sends a PayPlus-format IPN through the same webhook path production uses, and the wallet is credited. outcome "declined" simulates a failed card.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "topup_id": {
      "type": "string"
    },
    "outcome": {
      "type": "string",
      "enum": [
        "approved",
        "declined"
      ]
    }
  },
  "required": [
    "topup_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Sandbox only. Marks the order's eSIM as installed and used, as if the traveler activated it. Use it to exercise refund and dispute rules.

{
  "type": "object",
  "properties": {
    "agent_id": {
      "description": "Your agent id (or X-Agent-Id header)",
      "type": "string"
    },
    "principal_id": {
      "description": "The principal you act for (or X-Principal-Id header)",
      "type": "string"
    },
    "agent_key": {
      "description": "Secret returned by register_agent (or X-Agent-Key header)",
      "type": "string"
    },
    "order_id": {
      "type": "string"
    },
    "data_used_mb": {
      "default": 120,
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}