Skip to main content

Create account session

Resolves account status from lookup details and returns a short-lived session token for downstream account operations.

Endpoint​

POST /account/account_session

Query Parameters​

  • version (string, required) - API contract version. Use exactly 2024-10-01.
  • diagnostics (boolean, optional) - Non-production docs only. Set true to include extra diagnostic metadata (for example observed_client_ip).

Header Parameters​

  • PW-subscription-key (string, required)
  • PW-origin-country (string, required)
  • PW-request-date (string, required)
  • PW-ip-address (string, required)
  • User-Agent (string, required)
  • PW-request-id (string, required) - Caller-generated UUID used for idempotent tracing through PayWise account_session.
  • Accept (string, optional) - If provided, must include application/json.

Request Body​

{
  "lookup_type": "MOBILE",
  "lookup_value": "18681112220",
  "institution_name": "PayWiseDAP",
  "first_name": "Icon",
  "last_name": "Gilbert",
  "email": "[email protected]"
}

Responses​

200 - Wrapper-normalized response envelope (success cases).​

Example: success​

{
  "status": "success",
  "code": 200,
  "message": "Account is in good standing.",
  "request_id": "9d9078a9-fdf2-43cc-8e5a-f6264cd4a2fb",
  "timestamp": "2026-03-01T18:42:11.913Z",
  "data": {
    "request_id": "9d9078a9-fdf2-43cc-8e5a-f6264cd4a2fb",
    "version": "20241001",
    "lookup": {
      "type": "MOBILE",
      "value_masked": "******2220"
    },
    "account": {
      "account_status": "available",
      "account_number": "001234567890",
      "account_type": "personal",
      "display_name": "Icon Gilbert",
      "country": "TT"
    },
    "session": {
      "session_token": "H6QJ4F5JY4",
      "expires_at": "2026-03-01T18:57:11.913Z",
      "ttl_seconds": 900,
      "single_use": false
    }
  }
}

409 - Wrapper-normalized response envelope (409)​

Example: error​

{
  "status": "error",
  "code": 409,
  "message": "Multiple matches found. Please use the email key in the body.",
  "request_id": "9d9078a9-fdf2-43cc-8e5a-f6264cd4a2fb",
  "timestamp": "2026-03-01T18:42:12.215Z",
  "data": {
    "error_code": "AMBIGUOUS_MATCH",
    "lookup_type": "MOBILE"
  }
}

Notes​

This endpoint page is generated from openapi/pw-wrappers.2024-10-01.yaml.