Plexy Wallet API

Authorize

POST /v1/wallet/authorize
Creates a new wallet authorization transaction.

Get Transaction

GET /v1/wallet/transaction/{wallet_transaction_id}
Returns the status/details of a previously created transaction.

List Transactions

GET /v1/wallet/transactions/
Returns a list of wallet transactions.

Idempotency

Use Idempotency-Key to safely retry POST without creating duplicates.

Idempotency (POST only)

POST /v1/wallet/authorize supports idempotency via a header:

Header	Required	Example	Notes
`Idempotency-Key`	Yes	`8b7f2a7e-2c5b-4d6e-9c3f-acde12345678`	Unique per logical operation; reusing the same key should return the same result (expected).

Recommendation: use a UUID v4 as Idempotency-Key.

Do not reuse the same Idempotency-Key for different orders.

Data Model

WalletTransaction

Field	Type	Description
`walletTransactionId`	string	Unique identifier of the wallet transaction.
`walletTransactionStatus`	string	Current status of the wallet transaction.
`orderReference`	string	Merchant-side order reference.
`amount`	integer	Amount in minor units (e.g., cents/tiyn).
`currency`	string	Currency code (e.g., `KZT`, `USD`).

TransactionStatus

NEW, PROCESSING, SUCCESS, FAILED

Typical Flow

Authorize a transaction

Call POST /v1/wallet/authorize with amount + customer identifiers + orderReference.

Receive transaction id

Store walletTransactionId returned in the response.

Capture / Cancel

To finalize debit — POST /v1/wallet/{wallet_transaction_id}/capture.
To cancel — POST /v1/wallet/{wallet_transaction_id}/cancel.

Refund (if applicable)

To refund — POST /v1/wallet/{wallet_transaction_id}/refund.

Poll transaction status

Call GET /v1/wallet/transaction/{wallet_transaction_id} until it reaches a terminal state (e.g., SUCCESS/FAILED).

Reconcile

Match by orderReference and persist final status in your system.

Endpoint: Authorize

`POST /v1/wallet/authorize`

Auth: Authorization: <Merchant Api-Key>
Idempotency: Idempotency-Key: <uuid>

Request Body

Field	Type	Required	Description
`amount`	integer	Yes	Amount in minor units (e.g., cents/tiyn).
`phoneNumber`	string	Yes	Customer phone number.
`iin`	string	Yes	Customer IIN (Kazakhstan personal identifier).
`orderReference`	string	Yes	Merchant order reference (recommended unique).
`currency`	string	Yes	Currency code.

amount is in minor units. Example: for KZT 1,234.56, send 123456 if your minor unit is 1/100.

Response Body (200/201)

Field	Type	Description
`walletTransactionId`	string	New wallet transaction id.
`walletTransactionStatus`	string	Current status (likely initial).
`orderReference`	string	Echo of the request field.
`amount`	integer	Echo of the request amount.
`currency`	string	Echo of the request currency.

Examples

cURL

HTTP

Response

Endpoint: Capture

`POST /v1/wallet/{wallet_transaction_id}/capture`

Auth: Authorization: <Merchant Api-Key>

Path Parameters

Name	Required	Description
`wallet_transaction_id`	Yes	Identifier of the wallet transaction.

Request Body

Field	Type	Required	Description
`amount`	integer	Yes	Capture amount in minor units.

Response Body

Field	Type	Description
`walletTransactionId`	string	Wallet transaction id.
`walletTransactionStatus`	string	Current status after operation.
`orderReference`	string	Merchant order reference.
`amount`	integer	Amount processed for this operation (minor units).
`currency`	string	Currency code.

{
  "walletTransactionId": "wt_01JDM3Z7V8H8Q2X9K0R1ABCD12",
  "walletTransactionStatus": "SUCCESS",
  "orderReference": "ORDER-100045",
  "amount": 15000,
  "currency": "KZT"
}

Endpoint: Refund

`POST /v1/wallet/{wallet_transaction_id}/refund`

Auth: Authorization: <Merchant Api-Key>

Path Parameters

Name	Required	Description
`wallet_transaction_id`	Yes	Identifier of the wallet transaction.

Request Body

Field	Type	Required	Description
`amount`	integer	Yes	Refund amount in minor units.

Response Body

Field	Type	Description
`walletTransactionId`	string	Wallet transaction id.
`walletTransactionStatus`	string	Current status after operation.
`orderReference`	string	Merchant order reference.
`amount`	integer	Amount processed for this operation (minor units).
`currency`	string	Currency code.

{
  "walletTransactionId": "wt_01JDM3Z7V8H8Q2X9K0R1ABCD12",
  "walletTransactionStatus": "SUCCESS",
  "orderReference": "ORDER-100045",
  "amount": 5000,
  "currency": "KZT"
}

Endpoint: Cancel

`POST /v1/wallet/{wallet_transaction_id}/cancel`

Auth: Authorization: <Merchant Api-Key>

Path Parameters

Name	Required	Description
`wallet_transaction_id`	Yes	Identifier of the wallet transaction.

Request Body

Field	Type	Required	Description
`amount`	integer	Yes	Cancel amount in minor units (if partial cancel is supported).

Response Body

Field	Type	Description
`walletTransactionId`	string	Wallet transaction id.
`walletTransactionStatus`	string	Current status after operation.
`orderReference`	string	Merchant order reference.
`amount`	integer	Amount processed for this operation (minor units).
`currency`	string	Currency code.

{
  "walletTransactionId": "wt_01JDM3Z7V8H8Q2X9K0R1ABCD12",
  "walletTransactionStatus": "SUCCESS",
  "orderReference": "ORDER-100045",
  "amount": 15000,
  "currency": "KZT"
}

Endpoint: Get Wallet Transaction

`GET /v1/wallet/transaction/{wallet_transaction_id}`

Auth: Authorization: <Merchant Api-Key>

Path Parameters

Name	Required	Description
`wallet_transaction_id`	Yes	Identifier returned from Authorize.

Response Body (200)

Returns WalletTransaction:

{
  "walletTransactionId": "wt_01JDM3Z7V8H8Q2X9K0R1ABCD12",
  "walletTransactionStatus": "SUCCESS",
  "orderReference": "ORDER-100045",
  "amount": 15000,
  "currency": "KZT"
}

Endpoint: List Wallet Transactions

`GET /v1/wallet/transactions/`

Auth: Authorization: <Merchant Api-Key>

Query Parameters

Name	Type	Required	Description
`limit`	integer	No	Max items to return (e.g., 20–100).
`cursor`	string	No	Cursor for pagination.
`orderReference`	string	No	Filter by merchant order reference.
`status`	string	No	Filter by transaction status.

Response Example

{
  "items": [
    {
      "walletTransactionId": "wt_01JDM3Z7V8H8Q2X9K0R1ABCD12",
      "walletTransactionStatus": "SUCCESS",
      "orderReference": "ORDER-100045",
      "amount": 15000,
      "currency": "KZT"
    },
    {
      "walletTransactionId": "wt_01JDM40A2K9Q9B8F1Z2XEFGH34",
      "walletTransactionStatus": "PROCESSING",
      "orderReference": "ORDER-100046",
      "amount": 15000,
      "currency": "KZT"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjJ9"
}

Field Notes

amount (minor units): What does “minor” mean?

iin: What is IIN?

Wallet

Plexy Wallet API#

Idempotency (POST only)#

Data Model#

WalletTransaction#

TransactionStatus#

Typical Flow#

Endpoint: Authorize#

POST /v1/wallet/authorize#

Request Body#

Response Body (200/201)#

Examples#

Endpoint: Capture#

POST /v1/wallet/{wallet_transaction_id}/capture#

Path Parameters#

Request Body#

Response Body#

Endpoint: Refund#

POST /v1/wallet/{wallet_transaction_id}/refund#

Path Parameters#

Request Body#

Response Body#

Endpoint: Cancel#

POST /v1/wallet/{wallet_transaction_id}/cancel#

Path Parameters#

Request Body#

Response Body#

Endpoint: Get Wallet Transaction#

GET /v1/wallet/transaction/{wallet_transaction_id}#

Path Parameters#

Response Body (200)#

Endpoint: List Wallet Transactions#

GET /v1/wallet/transactions/#

Query Parameters#

Response Example#

Field Notes#

Plexy Wallet API

Idempotency (POST only)

Data Model

WalletTransaction

TransactionStatus

Typical Flow

Endpoint: Authorize

`POST /v1/wallet/authorize`

Request Body

Response Body (200/201)

Examples

Endpoint: Capture

`POST /v1/wallet/{wallet_transaction_id}/capture`

Path Parameters

Request Body

Response Body

Endpoint: Refund

`POST /v1/wallet/{wallet_transaction_id}/refund`

Path Parameters

Request Body

Response Body

Endpoint: Cancel

`POST /v1/wallet/{wallet_transaction_id}/cancel`

Path Parameters

Request Body

Response Body

Endpoint: Get Wallet Transaction

`GET /v1/wallet/transaction/{wallet_transaction_id}`

Path Parameters

Response Body (200)

Endpoint: List Wallet Transactions

`GET /v1/wallet/transactions/`

Query Parameters

Response Example

Field Notes