Overview Use this endpoint to authenticate a merchant user with their email and password. On success, you receive an accessToken and refreshToken in the response headers, along with user and merchant details in the response body.
Email and password values must be Base64-encoded before sending. The server decodes them before validation.
Endpoint POST https://api.tagpay.ng/v1/auth/login
Request Header Value Required Content-Typeapplication/jsonYes
Body Parameters The merchant’s email address, Base64-encoded. Must be a valid email format.
The merchant’s account password, Base64-encoded. Minimum 6 characters.
Optional device and session metadata used for activity logging and fraud detection. A unique fingerprint string identifying the device. Maximum 255 characters.
A unique identifier for the device. Maximum 255 characters.
The IANA timezone string for the user’s device (e.g. Africa/Lagos). Maximum 100 characters.
The user’s preferred language code (e.g. en-NG). Maximum 20 characters.
Detailed hardware and browser metadata. Show deviceMetadata properties
Screen resolution of the device (e.g. 1920x1080).
Operating system or platform name (e.g. MacIntel).
The browser user agent string.
Color depth of the device screen (e.g. 24).
Number of logical processor cores available.
Amount of device RAM in GB. May be null if unavailable.
Whether the device supports touch input.
Whether cookies are enabled in the browser.
Whether the user has enabled the Do Not Track setting.
Response The server returns the tokens in response headers in addition to the body.
Header Description X-Access-TokenShort-lived JWT used to authenticate API requests X-Refresh-TokenLong-lived token used to obtain a new access token
Body true on a successful login.
Authenticated user information. The unique identifier of the user.
The user’s role (e.g. MERCHANT).
The user’s email address.
The user’s current account mode: SANDBOX or PRODUCTION.
ISO 8601 timestamp of when the user was created.
ISO 8601 timestamp of when the user was last updated.
The merchant account linked to the authenticated user. The unique identifier of the merchant.
The registered business name of the merchant.
The type of business (e.g. FINANCIAL-SERVICES).
The merchant’s registered email address.
The user’s role within this merchant account.
true if this user is the owner of the merchant account.
The merchant’s active mode: SANDBOX or PRODUCTION.
KYC review status: PENDING, IN-REVIEW, or ENABLED.
The production webhook callback URL.
The sandbox webhook callback URL.
Whether the merchant is allowed to debit customer wallets.
The ID of the parent merchant if this is a subsidiary. null for main merchants.
ISO 8601 timestamp of when the merchant was created.
ISO 8601 timestamp of when the merchant was last updated.
A list of all active merchant accounts this user has access to. The merchant’s unique identifier.
The merchant’s business name.
The user’s role within this merchant account.
Whether the user owns this merchant account.
The active mode for this merchant: SANDBOX or PRODUCTION.
true if the user has access to more than one active merchant account.
Code Example # Values are Base64-encoded: # [email protected] → bWVyY2hhbnRAZXhhbXBsZS5jb20= # password123 → cGFzc3dvcmQxMjM= curl -X POST https://api.tagpay.ng/v1/auth/login \ -H "Content-Type: application/json" \ -D - \ -d '{ "email": "bWVyY2hhbnRAZXhhbXBsZS5jb20=", "password": "cGFzc3dvcmQxMjM=", "metadata": { "deviceFingerprint": "abc123fingerprint", "timezone": "Africa/Lagos", "language": "en-NG" } }'
Example Response { "status" : true , "data" : { "id" : "usr_01hxyz1234" , "role" : "MERCHANT" , "email" : "[email protected] " , "firstName" : "Amara" , "lastName" : "Okonkwo" , "mode" : "SANDBOX" , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-03-01T08:00:00.000Z" }, "merchant" : { "id" : "mch_01hxyz5678" , "businessName" : "Okonkwo Payments Ltd" , "businessType" : "FINANCIAL-SERVICES" , "email" : "[email protected] " , "role" : "owner" , "owner" : true , "mode" : "SANDBOX" , "review" : "ENABLED" , "callbackURL" : "https://yourapp.com/webhooks/tagpay" , "sandboxCallbackURL" : "https://yourapp.com/webhooks/tagpay-sandbox" , "canDebitCustomer" : true , "parentMerchant" : null , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-03-01T08:00:00.000Z" }, "availableMerchants" : [ { "id" : "mch_01hxyz5678" , "businessName" : "Okonkwo Payments Ltd" , "role" : "owner" , "owner" : true , "mode" : "SANDBOX" } ], "hasMultipleMerchants" : false }
Unverified Account Response If the user’s account has not been verified, the API sends a verification code to their email and returns:
{ "requiresVerification" : true , "message" : "Account has not been verified. Kindly check your email for verification code" }
Error Responses Status Description 400ACCOUNT_LOCKED — The merchant’s login access has been locked by an administrator.401Invalid email address or password. 401Account is currently disabled. 422Validation error — email or password failed schema validation.
