Skip to content
GPAS Docs

WalletSessionId

WalletSessionId

Overview

The WalletSessionId parameter represents a session that allows grouping movements in a wallet. It also allows giving permission to another system to operate debits and credits while the session is open.

Purpose

The WalletSessionId serves several important functions:

  1. Session Management: Establishes a session context for a series of related operations
  2. Transaction Grouping: Allows related transactions to be grouped together
  3. Authorization: Grants temporary permission for GPAS to perform operations on a wallet
  4. Audit Trail: Facilitates tracking and auditing of related transactions

Lifecycle

  1. Creation: A WalletSessionId is created when GPAS calls the Sessions method
  2. Usage: The WalletSessionId is used in subsequent API calls (balance, debit, credit, rollback)
  3. Termination: The session is closed when GPAS calls the Close method

Implementation Requirements

When implementing the OAS API, ensure that:

  1. The WalletSessionId is validated in every API call that requires it
  2. Operations are only permitted if the provided WalletSessionId is valid and active
  3. All transactions performed within a session are properly associated with that session
  4. If an invalid or expired WalletSessionId is provided, an appropriate error response is returned

Error Handling

If an invalid WalletSessionId is provided, the OAS should return an error response:

  • HTTP Status Code: 400
  • Error Code: 1004
  • Error Type: INVALID_WALLET_SESSION
  • Message: “Invalid wallet session”

Example Usage

The WalletSessionId is typically included as a query parameter in API calls:

GET /wallets/my/balance?walletSessionId=3fa85f64-5717-4562-b3fc-2c963f66afa6
HEADER
x-parent-system-id: BL13GT
x-signature: 52D7382EB6D253CECBD0414AE0CF5B673C9D2D0C
POST /movements/debit?walletSessionId=3fa85f64-5717-4562-b3fc-2c963f66afa6
HEADER
x-parent-system-id: BL13GT
x-signature: 963510BBB54BFB7916BF7D5937539A8AB5E3A633

Best Practices

  1. Session Timeout: Implement a reasonable timeout for wallet sessions to prevent security issues
  2. Validation: Always validate that the WalletSessionId exists and is active before processing requests
  3. Logging: Log all operations performed within a session for audit purposes
  4. Cleanup: Properly clean up resources when a session is closed