Skip to main content

Recipe 0: Account Preflight + Encryption

Goal​

Before any quote or transaction call, confirm the account context and prepare encrypted values.

Choose the Correct PW Account for Session Minting​

When you call GET /account/account, use the PW account that matches your transaction role:

  • p2p: mint from the source wallet (the debit_party PW user).
  • cashout: mint from the debit_party PW user.
  • deposit: mint from the credit_party PW user.
  • inttransfer: mint from the PW-side participant in the transfer (either debit_party or credit_party, depending on your flow).

session_token_enc must represent that PW account context.

Step 0A: Get account standing and mint session_token​

Call GET /account/account first for the correct PW user context listed above.

curl -X GET 'https://sandbox-api.paywise.co/account/account?version=2024-10-01&mobile_number=15550001001&institution_name=DemoBank&first_name=Jane&last_name=Doe' \
  -H 'PW-subscription-key: <your_key>' \
  -H 'PW-origin-country: US' \
  -H 'PW-request-date: 2026-02-13 18:00:00' \
  -H 'PW-ip-address: 203.0.113.10' \
  -H 'User-Agent: your-app/1.0'

Use the returned session_token for encryption.

Step 0B: If account is missing, create Level 0 profile​

If account lookup indicates no profile, call POST /account/personal_account.

Level 0 means: user can be created and start limited actions, but must complete KYC for full capability.

Step 1: Encrypt session_token with your pre-shared encryption key​

Generate:

  • Input: session_token (plaintext from account response)
  • Output: session_token_enc (encrypted base64 payload)

Use a local helper package from Client-side Encryption Helpers.

Step 2: Use session_token_enc for quote and transaction creation​

Use encrypted token in both:

  • POST /institution/quote
  • POST /institution/transaction

Step 3: Encrypt transaction id for status checks​

For transaction status polling, encrypt your transaction id:

  • Input: transaction_id
  • Output: transaction_id_enc

Then call GET /institution/transaction with transaction_id_enc.

Copy-Paste Payload Shapes​

Quote request body​

{
  "session_token_enc": "<encrypted_base64>",
  "request_amount": "150.00",
  "request_currency": "USD",
  "institution_name": "DemoBank",
  "debit_party": [
    {
      "key": "msisdn",
      "value": "15550001011"
    }
  ],
  "credit_party": [
    {
      "key": "msisdn",
      "value": "15550001012"
    }
  ]
}

Transaction create body​

{
  "session_token_enc": "<encrypted_base64>",
  "transaction_id": "TXN-001-CLIENT-IDEMPOTENCY",
  "transaction_date": "2026-02-13T18:10:00.000Z",
  "amount": "150.00",
  "sender_currency": "USD",
  "sender_amount": "150.00",
  "description": "Transfer",
  "transaction_type": "p2p",
  "fees": [
    {
      "fee_type": "service_fee",
      "fee_amount": "0.00",
      "fee_currency": "USD"
    }
  ],
  "debit_party": [
    {
      "key": "msisdn",
      "value": "15550001011"
    }
  ],
  "credit_party": [
    {
      "key": "msisdn",
      "value": "15550001012"
    }
  ],
  "sender_kyc": {
    "full_name": "Casey Example",
    "country": "US"
  },
  "recipient_kyc": {
    "full_name": "Jordan Example",
    "country": "US"
  }
}

Transaction status query​

curl -X GET 'https://sandbox-api.paywise.co/institution/transaction?version=2024-10-01&institution_name=DemoBank&transaction_id_enc=<encrypted_base64>' \
  -H 'PW-subscription-key: <your_key>' \
  -H 'PW-origin-country: US' \
  -H 'PW-request-date: 2026-02-13 18:12:00' \
  -H 'PW-ip-address: 203.0.113.10' \
  -H 'User-Agent: your-app/1.0'