PayTag

Overview

The Partner PayTag API lets you search the FLEX ecosystem for PayTags, resolve a PayTag profile, look up an existing PayTag by BVN, link an existing PayTag into your partner context, and create a new PayTag-backed partner wallet.

All Partner PayTag endpoints require partner authentication headers:

x-client-id
x-api-key

PayTag Endpoints

Search PayTags

GET /partner/paytag/search?q={identifier} - Search by tag, email, or phone prefix

Resolve PayTag

GET /partner/paytag/{tag} - Fetch a PayTag profile by tag

Get PayTag by BVN

GET /partner/paytag/bvn/{bvn} - Fetch the PayTag currently linked to a BVN

Link Existing PayTag

POST /partner/paytag/bvn/{bvn} - Create a partner wallet mapping for an existing BVN-linked PayTag

Create Partner PayTag

POST /partner/paytag - Create a new PayTag-backed partner wallet from customer details

Search PayTags

Search PayTags across the FLEX ecosystem using a query prefix. Endpoint: GET /partner/paytag/search Query Parameters:

Parameter	Type	Required	Description
q	string	Yes	Identifier prefix to search by tag, email, or phone

Request Example

cURL

curl --request GET \
  --url 'https://staging-api.yourflexpay.com/v2/partner/paytag/search?q=jane' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

{
  "items": [
    {
      "Tag": "janedoe",
      "Name": "Jane Doe",
      "Email": "jane@example.com",
      "Phone": "08012345678",
      "ImageUrl": "https://example.com/avatar.jpg"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}

Resolve PayTag

Resolve a specific PayTag profile by tag value. Endpoint: GET /partner/paytag/{tag} Path Parameters:

tag (required): PayTag value to resolve

Request Example

cURL

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

Response

{
  "Tag": "janedoe",
  "Name": "Jane Doe",
  "Email": "jane@example.com",
  "Phone": "08012345678",
  "ImageUrl": "https://example.com/avatar.jpg"
}

Get PayTag by BVN

Find the PayTag currently associated with a BVN. Endpoint: GET /partner/paytag/bvn/{bvn} Path Parameters:

bvn (required): Customer BVN

Request Example

cURL

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

Response

Returns the same PayTag structure as the resolve endpoint.

Link Existing PayTag by BVN

Use an already-existing BVN-linked PayTag to create a PartnerWallet mapping in your institution context. Endpoint: POST /partner/paytag/bvn/{bvn} Path Parameters:

bvn (required): Customer BVN

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/paytag/bvn/12345678901 \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

Response

Returns a PartnerWallet mapping containing the linked PayTag, generated partner reference, and underlying wallet.

{
  "ID": 42,
  "Reference": "PW-ABC123",
  "PayTag": {
    "Tag": "janedoe",
    "Name": "Jane Doe"
  },
  "Wallet": {
    "ID": 901,
    "Currency": "NGN"
  },
  "CreatedAt": "2026-10-06T10:00:00Z",
  "UpdatedAt": "2026-10-06T10:00:00Z"
}

Create Partner PayTag

Create a new PayTag-backed partner wallet using customer identity details. Endpoint: POST /partner/paytag Request Body:

Field	Type	Required	Description
firstName	string	Yes	Customer first name
lastName	string	Yes	Customer last name
otherName	string	Yes	Customer other/middle name
email	string	Yes	Customer email
phone	string	Yes	Customer phone
bvn	string	Yes	Customer BVN
tag	string	No	Desired PayTag
dateOfBirth	string	No	Customer date of birth
imageUrl	string	No	Profile image URL
gender	string	No	`Male` or `Female`
address	string	No	Customer address

Request Example

cURL

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/partner/paytag \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --data '{
    "firstName": "Jane",
    "lastName": "Doe",
    "otherName": "A",
    "email": "jane@example.com",
    "phone": "08012345678",
    "bvn": "12345678901",
    "tag": "janedoe"
  }'

Response

Returns the created PartnerWallet mapping for the new PayTag and scoped wallet.

Common Error Cases

Status Code	Description
`400`	Invalid payload, invalid PayTag, or a PayTag already exists for the BVN
`401`	Invalid partner credentials
`404`	PayTag or BVN-linked PayTag not found
`500`	Unexpected server error

Best Practices

Search or resolve a PayTag before linking by BVN so your integration can display a confirmation screen to operators.

Store the returned PartnerWallet.Reference after linking or creating a PayTag so you can use wallet endpoints later.

Partner Overview

General partner API capabilities and authentication

Wallet API

Operate on partner-scoped wallets created from PayTags

Terminal API

Handle partner terminal collection flows

OpenAPI Spec

Complete machine-readable API schema

PayTag SSO

Merchant

Partner

Switch

Overview

PayTag Endpoints

Search PayTags

Resolve PayTag

Get PayTag by BVN

Link Existing PayTag

Create Partner PayTag

Search PayTags

Request Example

Response

Resolve PayTag

Request Example

Response

Get PayTag by BVN

Request Example

Response

Link Existing PayTag by BVN

Request Example

Response

Create Partner PayTag

Request Example

Response

Common Error Cases

Best Practices

Partner Overview

Wallet API

Terminal API

OpenAPI Spec

​Overview

​PayTag Endpoints

Search PayTags

Resolve PayTag

Get PayTag by BVN

Link Existing PayTag

Create Partner PayTag

​Search PayTags

​Request Example

​Response

​Resolve PayTag

​Request Example

​Response

​Get PayTag by BVN

​Request Example

​Response

​Link Existing PayTag by BVN

​Request Example

​Response

​Create Partner PayTag

​Request Example

​Response

​Common Error Cases

​Best Practices

​Related Pages

Partner Overview

Wallet API

Terminal API

OpenAPI Spec

Overview

PayTag Endpoints

Search PayTags

Request Example

Response

Resolve PayTag

Request Example

Response

Get PayTag by BVN

Request Example

Response

Link Existing PayTag by BVN

Request Example

Response

Create Partner PayTag

Request Example

Response

Common Error Cases

Best Practices

Related Pages