Challenges

Cancel a challenge

POST https://api.xipid.org/challenges/{id}/cancel

Closes an open challenge as canceled: the page then tells the person the request was withdrawn, and the outcome challenge.canceled is posted to the callback URL.

Scope: any live key of the brand.

Limits: 1,000 requests a minute per key and 2,000 requests a minute per source address; every answer says what is left in X-RateLimit-Remaining, and a refusal when to come back in Retry-After.

Idempotency: takes an Idempotency-Key, which it requires: a retry under the same key is answered what the first request was, for 24 hours, and the key sent with another request is refused.

Changes: 2026-09-26: added.

Parameters

• id in the path, required, ULID

  XipID's id for the challenge.

• Idempotency-Key a header, required, string, at most 512 characters

  The operation's key, 1 to 255 characters, best a UUID, in double quotes as a structured field string: a retry of the operation sends it again, and is answered what the first request was, for 24 hours.

• Xip-Version a header, optional, string, one of the values below

  The version to answer in; when absent, the version the brand's org is pinned to.

  • 2026-09-26: The first version: challenges, subjects and events, and the signed outcome.

Answers

200 OK

The challenge, canceled.

Its headers: X-Request-Id, Xip-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

• id ULID

• brand_id ULID

• status string, one of the values below

  Where the challenge is in its life; the last five are final.

  • created: Made; the text with its link is not sent yet.
  • sent: The text with the link went to the person's phone.
  • opened: The person opened the link and is reading the request.
  • approving: The person approved, and the checks the policy asks for are running.
  • verified: The person approved and every check passed. Final.
  • check_failed: A check the policy asks for did not pass. Final.
  • declined: The person declined. Final.
  • expired: No decision came before expires_at. Final.
  • canceled: The brand canceled it, or its text could not be sent. Final.

• subject object

  • id ULID

  • pairwise_id pairwise identifier

  • reference string

  • tier number, one of the values below, optional

    How far the person's identity is verified.

    • 0: Their phone and email are verified.
    • 1: A selfie too, which keeps their reference face.
    • 2: A government document too.

• request object

  • type string, one of the values below

    What the brand asks the person to approve.

    • wire: A wire transfer.
    • beneficiary_change: A change to whom a payment goes.
    • withdrawal: A withdrawal of funds.
    • password_reset: A reset of a password.
    • address_change: A change of address.
    • other: Anything else; the title says what.

  • title string, at most 120 characters

  • summary string, at most 280 characters, optional

  • money object, optional

    • amount_minor integer, at least 0

    • currency currency, ISO 4217

  • counterparty string, at most 200 characters, optional

  • reference string, at most 120 characters, optional

  • requested_at instant, RFC 3339

• policy object

  • checks array of string, one of the values below

    • liveness: The selfie is of a live person at the phone, not a photo or a recording.
    • face_match: The selfie's face matches the person's reference face.

  • allow_decline boolean

  • allow_note boolean

  • expires_in_seconds integer, 60 to 3,600

• callback object

  • url URL, at most 2,048 characters

• metadata map, each value string, optional

• agent object, optional

  • id ULID

  • key string

  • version integer

  • name string

  • org object

    • name string

  • credential_id ULID

• checks array of one of the shapes below

  • One shape

    • check string, one of the values below

      A check the page runs before an approval counts.

      • liveness: The selfie is of a live person at the phone, not a photo or a recording.
      • face_match: The selfie's face matches the person's reference face.

    • passed always true

    • score number, 0 to 1, optional

    • mode string, one of the values below, optional

      The liveness mode the vendor says ran.

      • movement_and_light: Colored lights flashed on the screen during the selfie.
      • movement: No lights, for a device that asks for reduced motion; the vendor rates it the less accurate.

    • checked_at instant, RFC 3339

  • One shape

    • check string, one of the values below

      A check the page runs before an approval counts.

      • liveness: The selfie is of a live person at the phone, not a photo or a recording.
      • face_match: The selfie's face matches the person's reference face.

    • passed always false

    • score number, 0 to 1, optional

    • mode string, one of the values below, optional

      The liveness mode the vendor says ran.

      • movement_and_light: Colored lights flashed on the screen during the selfie.
      • movement: No lights, for a device that asks for reduced motion; the vendor rates it the less accurate.

    • reason string, one of the values below

      Why the check did not pass.

      • below_threshold: It scored under the threshold XipID holds it to.
      • no_face: The vendor found no face to score.
      • capture_failed: The selfie did not complete.
      • reference_missing: The brand deleted the reference face while the challenge was open.

    • checked_at instant, RFC 3339

• consent object, optional

  • agreed_at instant, RFC 3339

  • notice_version string, one of the values below

    The notice the person agreed to before the selfie, by its version.

    • request-selfie-2026-11-02: A request's selfie notice of November 2, 2026, for a brand that keeps no frames.
    • person-selfie-2026-11-02: The notice of November 2, 2026, before the selfie that takes a person to Tier 1.
    • request-selfie-frames-2026-11-02: A request's selfie notice of November 2, 2026, for a brand that keeps frames, which says so and that the brand may get them only if the request is disputed.

• note string, optional

• text object, optional

  • provider_message_id string, optional

  • status string, one of the values below

    What became of the text, as the channel reports it; the last three are final.

    • accepted: The provider took the text.
    • queued: The provider holds the text before the carrier has it.
    • sending: The text is on its way to the carrier.
    • sent: The carrier has the text.
    • delivered: The phone received the text. Final.
    • undelivered: The carrier could not deliver the text. Final.
    • failed: The provider could not send the text. Final.

  • error_code string, optional

• created_at instant, RFC 3339

• sent_at instant, RFC 3339, optional

• opened_at instant, RFC 3339, optional

• decided_at instant, RFC 3339, optional

• expires_at instant, RFC 3339

{
  "id": "01JD2R5W8Y3K6M9P2S5V8X1Z4B",
  "brand_id": "01JD2R1A3C5E7G9J1K3M5N7P9Q",
  "status": "canceled",
  "subject": {
    "id": "01JD2R2B4D6F8H0J2K4M6N8P0Q",
    "pairwise_id": "Vb3kQ9xR2mTz7LpW4nYc8d",
    "reference": "acct_4417"
  },
  "request": {
    "type": "wire",
    "title": "Wire to Ridgeline Fabrication",
    "summary": "The first payment on invoice 2291.",
    "money": {
      "amount_minor": 4500000,
      "currency": "USD"
    },
    "counterparty": "Ridgeline Fabrication",
    "reference": "INV-2291",
    "requested_at": "2026-11-19T18:04:00.000Z"
  },
  "policy": {
    "checks": [
      "liveness",
      "face_match"
    ],
    "allow_decline": true,
    "allow_note": true,
    "expires_in_seconds": 600
  },
  "callback": {
    "url": "https://acme-bank.example/xipid/outcomes"
  },
  "metadata": {
    "branch": "downtown"
  },
  "checks": [],
  "text": {
    "status": "sent"
  },
  "created_at": "2026-11-19T18:04:00.512Z",
  "sent_at": "2026-11-19T18:04:01.204Z",
  "expires_at": "2026-11-19T18:14:00.512Z",
  "decided_at": "2026-11-19T18:05:02.140Z"
}

Errors

• json_invalid, 400: The request body is not valid JSON.
• parameter_invalid, 400: The request contains invalid parameters.
• parameter_unknown, 400: The request contains a parameter this route does not take.
• idempotency_key_missing, 400: This route requires an Idempotency-Key header.
• version_invalid, 400: Xip-Version names no released version of this API.
• authentication_required, 401: Authentication is required.
• authentication_failed, 401: The credential is invalid, expired or revoked.
• insufficient_scope, 403: The credential does not allow this operation.
• resource_not_found, 404: No such resource.
• idempotency_key_in_use, 409: The first request with this Idempotency-Key is still running.
• challenge_closed, 409: The challenge is already closed.
• content_too_large, 413: The request body is larger than this route accepts.
• media_type_unsupported, 415: This route does not accept that Content-Type.
• idempotency_key_reused, 422: This Idempotency-Key was used for a different request.
• rate_limit_exceeded, 429: Too many requests; try again later.
• internal_error, 500: Something went wrong on our side.
• service_unavailable, 503: The service is temporarily unavailable.