Wallet - FLEX

Overview

The Wallet API allows a partner to operate on a partner-scoped wallet reference. Each wallet reference represents a user identity mapped into your institution context through a PartnerWallet mapping, while your own partner balance is exposed as a Wallet ledger. These endpoints support:

Retrieving your authenticated partner wallet
Creating a partner-scoped wallet with KYC information
Retrieving the wallet profile by reference
Viewing the wallet transaction summary
Debiting the referenced wallet into your partner wallet
Crediting the referenced wallet from your partner wallet
Sending P2P transfers from a referenced wallet to a PayTag recipient
Creating a static virtual account on a referenced wallet
Creating a dynamic virtual account on a referenced wallet
Listing wallet transactions and retrieving a single wallet transaction
Reversing an earlier wallet transaction by reference

All wallet endpoints require partner authentication headers:

x-client-id
x-api-key

Successful wallet movements generate partner webhook callbacks: wallet.debited and wallet.credited. See the Webhooks page for payloads and signature verification.

Wallet Endpoints

Get Partner Wallet

GET /partner/wallet - Fetch the authenticated partner wallet tied to your API credentials

Create Wallet

POST /partner/wallet - Provision a partner-scoped wallet with KYC information

Get Wallet

GET /partner/wallet/{reference} - Fetch a partner-scoped wallet by reference

Wallet Summary

GET /partner/wallet/{reference}/summary - Retrieve inflow/outflow summary

Debit Wallet

POST /partner/wallet/{reference}/debit - Move funds from the referenced wallet into your partner wallet

Credit Wallet

POST /partner/wallet/{reference}/credit - Move funds from your partner wallet into the referenced wallet

P2P Transfer

POST /partner/wallet/{reference}/p2p - Transfer funds from the referenced wallet to a PayTag recipient

Create Static Account

POST /partner/wallet/{reference}/static-account - Create a persistent virtual account for wallet funding

Create Dynamic Account

POST /partner/wallet/{reference}/dynamic-account - Generate a temporary virtual account for a transaction

List Wallet Transactions

GET /partner/wallet/{reference}/transactions - Get paginated wallet transactions for a referenced wallet

Get Wallet Transaction

GET /partner/wallet/{reference}/transactions/{transactionReference} - Retrieve a wallet transaction by reference

Reverse Wallet Transaction

POST /partner/wallet/{reference}/transactions/{transactionReference}/reverse - Reverse a previous wallet transaction

Get Partner Wallet

Retrieve the wallet owned by the authenticated partner. This endpoint does not require a wallet reference because the wallet ledger is resolved directly from your partner credentials. Endpoint: GET /partner/wallet

Request Example

cURL

curl --request GET \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

Returns the authenticated Wallet ledger for your partner context, not the PartnerWallet mapping object used for referenced customer-scoped wallets.

{
  "ID": 1,
  "Type": {
    "Name": "Escrow"
  },
  "PayTag": {
    "Tag": "@partnerdemo",
    "Name": "Partner Demo Ltd"
  },
  "CreatedAt": "2026-09-01T10:00:00Z",
  "UpdatedAt": "2026-09-01T10:00:00Z",
  "Metadata": {
    "alias": "Partner Demo Ltd"
  },
  "TotalAmount": 125000,
  "Currency": "NGN",
  "SuspendedAmount": 0,
  "BlockedAmount": 0,
  "Status": "Enabled",
  "AvailableAmount": 125000,
  "Amount": 125000,
  "Name": "Partner Demo Ltd",
  "Nuban": "0000000001"
}

Use this endpoint when you need the wallet currently attached to your partner account itself. Use GET /partner/wallet/{reference} to retrieve a customer-scoped PartnerWallet that was provisioned under your institution context.

Create Wallet

Create a new partner-scoped PartnerWallet mapping with customer KYC information. Endpoint: POST /partner/wallet Request Body:

Field	Type	Required	Description
currency	string	No	Wallet currency (`NGN` or `FP`)
profileId	number	No	KYC profile ID to attach
kyc.firstName	string	Yes	Customer first name
kyc.lastName	string	Yes	Customer last name
kyc.otherName	string	Yes	Customer other/middle name

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --data '{
    "currency": "NGN",
    "profileId": 3,
    "kyc": {
      "firstName": "Jane",
      "lastName": "Doe",
      "otherName": "A"
    }
  }'

Response

Returns the created PartnerWallet mapping including the partner-scoped Reference and underlying Wallet ledger.

Authentication

Headers:

x-client-id: Your partner ID
x-api-key: Your partner API key

Wallet Reference

The reference path parameter is the partner wallet reference assigned to the user wallet in your partner context. You should store this reference when a wallet is provisioned or linked for your institution.

Get Wallet

Retrieve the wallet profile linked to your partner for the supplied wallet reference. This endpoint returns the PartnerWallet mapping for a referenced customer-scoped wallet, including the nested Wallet ledger. Endpoint: GET /partner/wallet/{reference} Path Parameters:

reference (required): Partner wallet reference

Request Example

cURL

curl --request GET \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123 \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

{
  "ID": 42,
  "Reference": "PW-ABC123",
  "RevokedAt": null,
  "PayTag": {
    "Tag": "@janedoe"
  },
  "Wallet": {
    "ID": 901,
    "Currency": "NGN"
  },
  "KycProfile": {
    "ID": 3,
    "Name": "Tier 2"
  },
  "CreatedAt": "2026-09-01T10:00:00Z",
  "UpdatedAt": "2026-09-01T10:00:00Z"
}

Wallet Summary

Retrieve a high-level inflow and outflow summary for the referenced wallet. Endpoint: GET /partner/wallet/{reference}/summary Path Parameters:

reference (required): Partner wallet reference

Request Example

cURL

curl --request GET \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/summary \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

{
  "All": {
    "Inflow": {
      "Count": 12,
      "Total": 125000
    },
    "Outflow": {
      "Count": 7,
      "Total": 42000
    }
  }
}

Debit Wallet

Debit the referenced wallet and move the value into your partner wallet. Endpoint: POST /partner/wallet/{reference}/debit Path Parameters:

reference (required): Partner wallet reference

Request Body:

Field	Type	Required	Description
amount	number	Yes	Amount to debit
comment	string	No	Transfer narration
reference	string	No	Your external reference
currency	string	No	Wallet currency, e.g. `NGN`
metadata	object	No	Additional metadata

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/debit \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --data '{
    "amount": 5000,
    "comment": "Cash-out at agent",
    "reference": "PARTNER-DEBIT-1001",
    "metadata": {
      "channel": "agent"
    }
  }'

Response

Returns a wallet transaction detail object containing Reference, Status, Amount, Fee, Net, Sender, Recipient, and Metadata.

Credit Wallet

Credit the referenced wallet from your partner wallet balance. Endpoint: POST /partner/wallet/{reference}/credit Path Parameters:

reference (required): Partner wallet reference

Request Body: Uses the same payload as the debit endpoint.

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/credit \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --data '{
    "amount": 2500,
    "comment": "Incentive payout",
    "reference": "PARTNER-CREDIT-2042",
    "metadata": {
      "campaign": "Q3-bonus"
    }
  }'

Response

Returns the same wallet transaction detail structure as the debit endpoint.

P2P Transfer

Transfer funds from the referenced partner wallet to a recipient identified by PayTag. Endpoint: POST /partner/wallet/{reference}/p2p Path Parameters:

reference (required): Partner wallet reference

Request Body:

Field	Type	Required	Description
amount	number	Yes	Amount to transfer
recipient	string	Yes	Recipient PayTag or qualified directory address
comment	string	No	Transfer narration
reference	string	No	Your external reference
currency	string	No	Wallet currency, e.g. `NGN`
metadata	object	No	Additional metadata
hostId	number	No	Optional source host context
recipientHostId	number	No	Optional recipient host context

The recipient value is resolved through the PayTag directory and may refer to a tag outside the local FLEX tag set. Use the exact canonical tag returned from the PayTag search or resolve endpoints.

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/p2p \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --data '{
    "amount": 3500,
    "recipient": "janedoe@flex",
    "comment": "Wallet to wallet transfer",
    "reference": "PARTNER-P2P-1001",
    "metadata": {
      "channel": "api"
    }
  }'

Response

Returns the same wallet transaction detail structure as debit and credit wallet operations.

Create Dynamic Virtual Account

Create a dynamic (temporary) virtual account linked to the referenced wallet. Endpoint: POST /partner/wallet/{reference}/dynamic-account Path Parameters:

reference (required): Partner wallet reference

Request Body: Uses the same payload as debit/credit (WalletTransferDto) to define amount, reference, and metadata.

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/dynamic-account \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --data '{
    "amount": 5000,
    "reference": "PARTNER-DYN-1001"
  }'

Response

Returns a WalletDynamicVirtualAccount payload containing account name/number, bank name, and expiry details.

Create Static Virtual Account

Create a static (persistent) virtual account linked to the referenced wallet. Endpoint: POST /partner/wallet/{reference}/static-account Path Parameters:

reference (required): Partner wallet reference

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/static-account \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

Returns a WalletStaticVirtualAccount payload containing account name/number, bank name, and status.

{
  "ID": 415,
  "Reference": "STV-001-ABC",
  "AccountNumber": "1234567890",
  "AccountName": "Jane Doe",
  "BankName": "FLEX Settlement Bank",
  "Status": "Enabled"
}

List Wallet Transactions

Retrieve paginated transactions for a referenced partner wallet. Endpoint: GET /partner/wallet/{reference}/transactions Path Parameters:

reference (required): Partner wallet reference

Query Parameters:

limit, offset
search, reference
status, currency
startDate, endDate (format: YYYYMMDD)

Request Example

cURL

curl --request GET \
  --url 'https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/transactions?limit=20&offset=0&status=Successful' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

Returns a paginated response of wallet transaction detail objects.

Get Wallet Transaction

Retrieve a specific wallet transaction under a referenced partner wallet. Endpoint: GET /partner/wallet/{reference}/transactions/{transactionReference} Path Parameters:

reference (required): Partner wallet reference
transactionReference (required): Wallet transaction reference

Reverse Wallet Transaction

Reverse a previous partner wallet transaction by transaction reference. Endpoint: POST /partner/wallet/{reference}/transactions/{transactionReference}/reverse Path Parameters:

reference (required): Partner wallet reference
transactionReference (required): Wallet transaction reference to reverse

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/wallet/PW-ABC123/transactions/TRF-1756747777777/reverse \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

Returns a wallet transaction detail object for the generated reversal transaction.

{
  "Amount": 5000,
  "Fee": 0,
  "Net": 5000,
  "Reference": "REV-TRF-1756747777777",
  "ExternalReference": "TRF-1756747777777",
  "Status": "Successful",
  "Comment": "Reverse for TRF-1756747777777",
  "Sender": {
    "Name": "Partner Wallet",
    "Amount": 5000,
    "Fee": 0,
    "Currency": "NGN"
  },
  "Recipient": {
    "Name": "Jane Doe",
    "Amount": 5000,
    "Fee": 0,
    "Currency": "NGN"
  },
  "Date": "2026-09-01T13:05:00Z",
  "Metadata": {
    "InitialTransaction": "TRF-1756747777777"
  }
}

Common Error Cases

Status Code	Description
`400`	Invalid request, unsupported reversal target, or transaction does not belong to the partner wallet context
`401`	Invalid partner credentials
`404`	Wallet reference or transaction reference not found
`500`	Unexpected server error

Best Practices

Persist both the partner wallet reference and the returned transaction Reference values for reconciliation and reversal workflows.

Use your own reference in debit and credit requests so you can map FLEX transaction outcomes back to your internal ledger.

Resolve recipient PayTags through the Partner PayTag API before submitting a P2P transfer, especially when your users can transfer to tags that may live outside the local FLEX instance.

Only reverse completed partner wallet transfer flows that were initiated from your institution context.

Partner Overview

General partner API capabilities and authentication

Transactions API

Cross-partner transaction reporting and lookup

Webhooks

Partner transaction and wallet event callback payloads

OpenAPI Spec

Complete machine-readable API schema

​Overview

​Wallet Endpoints

Get Partner Wallet

Create Wallet

Get Wallet

Wallet Summary

Debit Wallet

Credit Wallet

P2P Transfer

Create Static Account

Create Dynamic Account

List Wallet Transactions

Get Wallet Transaction

Reverse Wallet Transaction

​Get Partner Wallet

​Request Example

​Response

​Create Wallet

​Request Example

​Response

​Authentication

​Wallet Reference

​Get Wallet

​Request Example

​Response

​Wallet Summary

​Request Example

​Response

​Debit Wallet

​Request Example

​Response

​Credit Wallet

​Request Example

​Response

​P2P Transfer

​Request Example

​Response

​Create Dynamic Virtual Account

​Request Example

​Response

​Create Static Virtual Account

​Request Example

​Response

​List Wallet Transactions

​Request Example

​Response

​Get Wallet Transaction

​Reverse Wallet Transaction

​Request Example

​Response

​Common Error Cases

​Best Practices

​Related Pages

Partner Overview

Transactions API

Webhooks

OpenAPI Spec

Overview

Wallet Endpoints

Get Partner Wallet

Request Example

Response

Create Wallet

Request Example

Response

Authentication

Wallet Reference

Get Wallet

Request Example

Response

Wallet Summary

Request Example

Response

Debit Wallet

Request Example

Response

Credit Wallet

Request Example

Response

P2P Transfer

Request Example

Response

Create Dynamic Virtual Account

Request Example

Response

Create Static Virtual Account

Request Example

Response

List Wallet Transactions

Request Example

Response

Get Wallet Transaction

Reverse Wallet Transaction

Request Example

Response

Common Error Cases

Best Practices

Related Pages