Create personal account profile

Accepts JSON or multipart data. When callback_url is provided, DevHouse sends a POST callback after onboarding completes.

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/personal_account

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)

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

{
  "first_name": "First",
  "last_name": "Last",
  "email": "[email protected]",
  "mobile_number": "18680001234",
  "institution_name": "ExampleInstitution",
  "callback_url": "https://example.test/callback",
  "authorisation_token": "AUTH_TOKEN_REDACTED"
}

Downloads

Onboarding-completion callback

Include both optional fields below to receive a callback after onboarding completes:

callback_url: HTTPS callback endpoint, maximum 200 characters. It must return an HTTP 2xx response.
authorisation_token: institution token, 10–40 characters.

DevHouse sends a POST request to callback_url with these mandatory headers:

authorisation-token: the institution token encrypted using the institution's shared encryption/decryption key. Decrypt it before use and never log its plaintext value.
pw-signature: callback signature generated by PayWise.

The JSON body contains the top-level fields version, request_timestamp, request_id, institution_name, and account. The account object contains mobile_number, account_status, account_level, funds_access_status, and onboarding_status. A completed onboarding reports account.onboarding_status: "completed".

Example callback body:

{
  "version": "2024-10-08",
  "request_timestamp": "2014-10-08 16:01:31",
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "institution_name": "ExampleInstitution",
  "account": {
    "mobile_number": "+18681234567",
    "account_status": "good standing",
    "account_level": "level_1",
    "funds_access_status": "enabled",
    "onboarding_status": "completed"
  }
}

The rendered request example above shows the minimal JSON path. Use multipart/form-data when you are sending onboarding artefacts or additional KYC fields beyond the base profile fields.

Responses

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

Example: success

{
  "status": "success",
  "code": 200,
  "message": "Personal account profile created successfully",
  "request_id": "b3a41b80-4e1a-4081-9b19-cec26ad14ae1",
  "timestamp": "2026-02-12T16:20:59.891Z",
  "data": {
    "account_id": "pw-personal-demo-0001",
    "account_status": "pending_review",
    "account_type": "personal",
    "mobile_number": "+18680001234",
    "email": "[email protected]"
  }
}

400 - Wrapper-normalized response envelope (400)

Example: error

{
  "status": "error",
  "code": 400,
  "message": "mobile_number is required",
  "request_id": "42492887-64d8-4919-a232-ab51ba7a5933",
  "timestamp": "2026-02-12T16:20:59.942Z"
}

Notes

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

Endpoint​

Query Parameters​

Header Parameters​

Header Constraints​

Request Body​

Downloads​

Onboarding-completion callback​

Responses​

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

Example: success​

400 - Wrapper-normalized response envelope (400)​

Example: error​

Notes​