Create account session

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

Account API access is restricted

Portal-created sandbox test app accounts do not grant your project direct Account API access.

If your project is not approved for Account API access, /account/* calls return HTTP 403 with PW_ACCOUNT_ACCESS_REQUIRED.

See /getting-started/sandbox-account-setup.

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) - UTC request timestamp formatted as YYYY-MM-DD HH:mm:ss.
• 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.

Header Constraints

Key	Description	Example	Data type	Requirement	Field Length
PW-subscription-key	Developer key available after portal registration. Production key is shared on request.	eed0d85c530c4b26a91d09b783d8fab3	string	mandatory	32
PW-origin-country	ISO Alpha-2 country code where the transaction is created.	TT	string	mandatory	2
PW-request-date	Current request timestamp. Format: YYYY-MM-DD HH:mm:ss (UTC).	2014-10-08 16:01:31	string	mandatory	19
PW-ip-address	Fixed institution IP used for PayWise network-level validation.	255.255.255.255	string	conditional	8-16
User-Agent	In programmable environments, this avoids running into Cloudflare issues.	Mozilla/5.0 (Windows NT 10.0; Win64; x64)	string	mandatory	255

Request Body

{
  "lookup_type": "MOBILE",
  "lookup_value": "18680001234",
  "institution_name": "ExampleInstitution",
  "first_name": "First",
  "last_name": "Last",
  "email": "[email protected]"
}

Downloads

• Download Postman-ready request body
• Download Postman-ready response (200)
• Download Postman-ready response (200 unavailable)
• Download Postman-ready response (404 unknown)
• Download Postman-ready response (409 error)

Response semantics

For this endpoint, an HTTP 200 does not always mean a usable account session was issued.

Callers must inspect:

• data.account.account_status
• data.session.session_token

Current public behavior:

• available -> HTTP 200, status: "success", usable data.session.session_token
• unavailable -> HTTP 200, status: "success", data.session: null
• unknown -> HTTP 404, status: "error"
• ambiguous match -> HTTP 409, status: "error"

If data.account.account_status !== "available", do not assume the account can be used for downstream session-based operations.

Example: unavailable account still returns HTTP 200

{
  "status": "success",
  "code": 200,
  "message": "Account is currently unavailable or not active. Please try again later or contact PayWise Support.",
  "request_id": "3fc9cf50-444f-4c1f-b687-e836d47331b7",
  "timestamp": "2026-08-23T18:17:06.000Z",
  "data": {
    "request_id": "3fc9cf50-444f-4c1f-b687-e836d47331b7",
    "version": "2024-10-01",
    "lookup": {
      "type": "EMAIL",
      "value_masked": "gl**********@email.com"
    },
    "account": {
      "account_status": "unavailable",
      "account_number": null,
      "account_type": "personal",
      "display_name": "Gloria Joseph",
      "country": "TT"
    },
    "session": null,
    "resolution": {
      "usable": false,
      "reason_code": "ACCOUNT_UNAVAILABLE"
    }
  }
}

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": "2024-10-01",
    "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
    }
  }
}

Example: unavailable

{
  "status": "success",
  "code": 200,
  "message": "Account is currently unavailable or not active. Please try again later or contact PayWise Support.",
  "request_id": "3fc9cf50-444f-4c1f-b687-e836d47331b7",
  "timestamp": "2026-08-23T18:17:06.000Z",
  "data": {
    "request_id": "3fc9cf50-444f-4c1f-b687-e836d47331b7",
    "version": "2024-10-01",
    "lookup": {
      "type": "EMAIL",
      "value_masked": "gl**********@email.com"
    },
    "account": {
      "account_status": "unavailable",
      "account_number": null,
      "account_type": "personal",
      "display_name": "Gloria Joseph",
      "country": "TT"
    },
    "session": null,
    "resolution": {
      "usable": false,
      "reason_code": "ACCOUNT_UNAVAILABLE"
    }
  }
}

404 - Wrapper-normalized response envelope (404)

Example: unknown

{
  "status": "error",
  "code": 404,
  "message": "Account not found",
  "request_id": "3fc9cf50-444f-4c1f-b687-e836d47331b7",
  "timestamp": "2026-08-23T18:15:20.000Z",
  "data": {
    "errorCode": "ACCOUNT_NOT_FOUND",
    "request_id": "3fc9cf50-444f-4c1f-b687-e836d47331b7",
    "details": {
      "lookup_type": "EMAIL"
    }
  }
}

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": {
    "errorCode": "AMBIGUOUS_MATCH",
    "request_id": "9d9078a9-fdf2-43cc-8e5a-f6264cd4a2fb",
    "details": {
      "lookup_type": "MOBILE"
    }
  }
}

Notes

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