{"openapi":"3.0.0","info":{"title":"Lendoverify API","description":"The official API documentation for Lendoverify - Nigeria's premier identity verification,\npayments, and financial services platform for businesses.\n\n![Integration Tools](https://api.lendoverify.com/customers/images/integration-tools.png)\n\n## Overview\nLendoverify provides APIs for:\n- **Identity Verification**: NIN, BVN, CAC, Driver's License, Voter's Card verification\n- **Face Matching**: Biometric verification against government databases\n- **Credit Bureau Checks**: CRC, First Central, Credit Registry lookups\n- **Fraud Screening**: Email, phone, and IP address fraud detection\n- **Payments**: Direct debit, transfers, and virtual accounts\n- **Communications**: SMS and email messaging services\n\n## Authentication\nThe API supports two authentication methods:\n- **Bearer Token**: For admin and customer session-based access. Include in header as `Authorization: Bearer <token>`\n- **API Key**: For programmatic API access. Include in header as `api-key: <your_api_key>`\n\n## Environments\n- **Production**: `https://api.lendoverify.com`\n- **Sandbox**: Use test API keys for sandbox testing\n\n## Rate Limits\n- Standard: 100 requests per minute\n- Enterprise: Contact support for custom limits\n\n## Support\nFor technical support, contact us at support@afihan.com\n","version":"1.0.0","termsOfService":"https://www.afihan.com/terms-of-use","contact":{"name":"Lendoverify Support","url":"https://www.afihan.com/support"},"license":{"name":"Privacy Policy","url":"https://www.afihan.com/privacy-policy"}},"servers":[{"url":"https://api.lendoverify.com","description":"Production environment"},{"url":"http://localhost:8004","description":"Development environment"}],"tags":[{"name":"Customer","description":"Merchant and customer-facing API endpoints for account management"},{"name":"Identity Verification","description":"NIN, BVN, CAC, Driver's License, Passport, and Voter's Card verification services"},{"name":"Face Matching","description":"Biometric face matching and liveness detection services"},{"name":"Credit Check","description":"Credit bureau checks including CRC, First Central, and Credit Registry"},{"name":"Fraud Screening","description":"Email, phone, and IP address fraud detection and risk assessment"},{"name":"Payments","description":"Payment processing, transfers, and virtual account management"},{"name":"Direct Debit","description":"Direct debit mandate initialization, charging, status checks, and deactivation"},{"name":"SMS & Email","description":"Communication services for SMS and email messaging"},{"name":"Address Verification","description":"Physical and digital address verification services"},{"name":"Checkout","description":"Afihan checkout for card and bank transfer payments"}],"paths":{"/api/customers/login":{"post":{"operationId":"customerLogin","tags":["Customer"],"summary":"Customer login","description":"Authenticate as a customer (merchant) to access the API.\nReturns a bearer token for subsequent authenticated requests.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email","example":"customer@example.com"},"password":{"type":"string","description":"Password","example":"password"}},"required":["email","password"]}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/customers/logout":{"delete":{"operationId":"customerLogout","tags":["Customer"],"summary":"Customer logout","description":"Invalidate the current session and revoke the bearer token.","responses":{"200":{"description":"Logout successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"bearerTokenAuth":[]}]}},"/api/customers/reset-password":{"post":{"operationId":"customerResetPassword","tags":["Customer"],"summary":"Reset password","description":"Change the password for the currently authenticated customer. Requires the current password for verification.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"old_password":{"type":"string","description":"Password","example":"password"},"password":{"type":"string","description":"Password","example":"password"},"password_confirmation":{"type":"string","description":"Password confirmation","example":"password"}},"required":["old_password","password","password_confirmation"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]}]}},"/api/customers/api-keys":{"get":{"operationId":"customerGetApiKeys","tags":["Customer"],"summary":"Get API keys","description":"Retrieve the API keys (public and secret) for programmatic API access.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]}]}},"/api/customers/generate-secret-key":{"patch":{"operationId":"customerRegenerateSecretKey","tags":["Customer"],"summary":"Regenerate secret key","description":"Generate a new secret API key. The old key will be invalidated immediately.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]}]}},"/api/customers/webhook":{"patch":{"operationId":"customerUpdateWebhook","tags":["Customer"],"summary":"Update webhook settings","description":"Configure the webhook URL and secret for receiving real-time event notifications.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"webhook_url":{"type":"string","description":"The webhook url","example":"https://example.com/webhook"},"test_webhook_url":{"type":"string","description":"The test webhook url (used in test mode)","example":"https://example.com/test-webhook"},"webhook_secret":{"type":"string","description":"The webhook secret","example":"secret"},"email_from":{"type":"string","description":"The sender email address","example":"notifications@example.com"},"email_webhook":{"type":"string","description":"The webhook url for email delivery notifications","example":"https://example.com/email-webhook"},"sms_webhook":{"type":"string","description":"The webhook url for SMS delivery notifications","example":"https://example.com/sms-webhook"}}}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]}]}},"/api/customers/fund-wallet":{"post":{"operationId":"customerFundWallet","tags":["Payments"],"summary":"Fund wallet","description":"Initiate a wallet top-up transaction. Returns a payment link for completing the transaction via Paystack.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"The amount to fund in kobo (i.e 100000 = 1000)","example":100000}},"required":["amount"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]}]}},"/api/customers/profile":{"get":{"operationId":"customerGetProfile","tags":["Customer"],"summary":"Get profile","description":"Retrieve the authenticated customer's profile details including business information and wallet balance.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]}]}},"/api/customers/balance":{"get":{"operationId":"customerGetBalance","tags":["Customer"],"summary":"Get wallet balance","description":"Retrieve the current wallet balance in Kobo.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/sms/send":{"post":{"operationId":"customerSendSms","tags":["SMS & Email"],"summary":"Send SMS","description":"Send an SMS message to one or more phone numbers.\nPhone numbers must be in international format (+234XXXXXXXXXX).\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"The phone number(s) to send to. The only acceptable format is +234XXXXXXXXXX"},"message":{"type":"string","description":"The message to send","example":"Hello world"},"sender_id":{"type":"string","description":"The ID of the sender if available","example":"lendocredit"}},"required":["to","message"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/sms/send/bulk":{"post":{"operationId":"customerSendBulkSms","tags":["SMS & Email"],"summary":"Send bulk SMS","description":"Send the same SMS message to multiple phone numbers in a single request.\nIdeal for marketing campaigns or bulk notifications.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"to[]":{"type":"array","description":"The phone number(s) to send to. The only acceptable format is +234XXXXXXXXXX"},"message":{"type":"string","description":"The message to send","example":"Hello world"}},"required":["to[]","message"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/email/send":{"post":{"operationId":"customerSendEmail","tags":["SMS & Email"],"summary":"Send email","description":"Send an email to one or more recipients with optional attachments.\nSupports CC, BCC, and file attachments.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"to[]":{"type":"array","description":"The email addresses to send email to"},"subject":{"type":"string","description":"The subject of the email","example":"Hello world"},"message":{"type":"string","description":"The message to send","example":"Hello world"},"from_name":{"type":"string","description":"Your from name","example":"lendoverify"},"cc[]":{"type":"array","description":"The email address(es) to cc. The only acceptable format is admin@example.com"},"bcc[]":{"type":"array","description":"The email address(es) to bcc. The only acceptable format is admin@example.com"},"attachments[]":{"type":"array","description":"The files to attach. The only acceptable format is file1.txt,file2.pdf","items":{"type":"string","format":"binary"}}},"required":["to[]","subject","message"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/pep-sanction-check":{"post":{"operationId":"verifyPepSanction","tags":["Fraud Screening"],"summary":"PEP and Sanction check","description":"Screen an individual or business against Politically Exposed Persons (PEP)\nand international sanctions databases for AML/KYC compliance.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"identity_number":{"type":"string","description":"Identity number of the the subject to query with","example":63184876213},"type":{"type":"string","description":"Type of identification","example":"individual","enum":["individual","business","all"]},"first_name":{"type":"string","description":"The first name of the customer","example":"Bunch"},"last_name":{"type":"string","description":"The last name of the customer","example":"Dillon"},"position":{"type":"string","description":"Position of customer"},"keyword":{"type":"string","description":"Keywords related to the customer"},"gender":{"type":"string","description":"Gender of the customer"},"country":{"type":"string","description":"Country of the customer"},"education":{"type":"string","description":"Education of the customer"}},"required":["identity_number","type"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/nin":{"post":{"operationId":"verifyNin","tags":["Identity Verification"],"summary":"Verify NIN (Basic)","description":"Verify a Nigerian National Identification Number (NIN).\nReturns basic identity information linked to the NIN.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"nin":{"type":"string","description":"The NIN to verify","example":63184876213},"firstname":{"type":"string","description":"The first name of the customer","example":"Bunch"},"lastname":{"type":"string","description":"The last name of the customer","example":"Dillon"},"dob":{"type":"string","description":"The date of birth of the customer (YYYY-MM-DD)"},"phone":{"type":"string","description":"The phone number of the customer"},"email":{"type":"string","description":"The email of the customer"},"gender":{"type":"string","description":"The gender of the customer (m or f)"}},"required":["nin"]}}}},"responses":{"200":{"description":"NIN verification successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientFunds"},"500":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/nin/premium":{"post":{"operationId":"verifyNinPremium","tags":["Identity Verification"],"summary":"Verify NIN (Premium)","description":"Verify a Nigerian National Identification Number (NIN) with enhanced data.\nReturns comprehensive identity information including photo.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"nin":{"type":"string","description":"The NIN to verify","example":63184876213},"firstname":{"type":"string","description":"The first name of the customer","example":"Bunch"},"lastname":{"type":"string","description":"The last name of the customer","example":"Dillon"},"dob":{"type":"string","description":"The date of birth of the customer (YYYY-MM-DD)"},"phone":{"type":"string","description":"The phone number of the customer"},"email":{"type":"string","description":"The email of the customer"},"gender":{"type":"string","description":"The gender of the customer (m or f)"}},"required":["nin"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/bvn/basic":{"post":{"operationId":"verifyBvnBasic","tags":["Identity Verification"],"summary":"Verify BVN (Basic)","description":"Verify a Bank Verification Number (BVN) with basic information.\nReturns name, phone, and date of birth linked to the BVN.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"bvn":{"type":"string","description":"The BVN to verify","example":95888168924},"firstname":{"type":"string","description":"The first name of the customer","example":"Bunch"},"lastname":{"type":"string","description":"The last name of the customer","example":"Dillon"},"dob":{"type":"string","description":"The date of birth of the customer (YYYY-MM-DD)"},"phone":{"type":"string","description":"The phone number of the customer"},"email":{"type":"string","description":"The email of the customer"},"gender":{"type":"string","description":"The gender of the customer (m or f)"}},"required":["bvn"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/bvn/premium":{"post":{"operationId":"verifyBvnPremium","tags":["Identity Verification"],"summary":"Verify BVN (Premium)","description":"Verify a Bank Verification Number (BVN) with comprehensive data.\nReturns full identity information including photo and address.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"bvn":{"type":"string","description":"The BVN to verify","example":95888168924},"firstname":{"type":"string","description":"The first name of the customer","example":"Bunch"},"lastname":{"type":"string","description":"The last name of the customer","example":"Dillon"},"dob":{"type":"string","description":"The date of birth of the customer (YYYY-MM-DD)"},"phone":{"type":"string","description":"The phone number of the customer"},"email":{"type":"string","description":"The email of the customer"},"gender":{"type":"string","description":"The gender of the customer (m or f)"}},"required":["bvn"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/nigerian-passport":{"post":{"operationId":"verifyNigerianPassport","tags":["Identity Verification"],"summary":"Verify Nigerian Passport","description":"Verify a Nigerian international passport number.\nReturns passport holder information and validity status.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"passport":{"type":"string","description":"The passport number to verify","example":"A10000001"},"firstname":{"type":"string","description":"The first name of the customer","example":"John"},"lastname":{"type":"string","description":"The last name of the customer","example":"Doe"},"dob":{"type":"string","description":"The date of birth of the customer (YYYY-MM-DD)"},"gender":{"type":"string","description":"The gender of the customer (m or f)"}},"required":["passport","firstname","lastname"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/drivers-license":{"post":{"operationId":"verifyDriversLicense","tags":["Identity Verification"],"summary":"Verify Driver's License","description":"Verify a Nigerian driver's license number.\nReturns license holder information and validity status.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"license_number":{"type":"string","description":"The driver's license number to verify","example":63184876213},"firstname":{"type":"string","description":"The first name of the customer","example":"John"},"lastname":{"type":"string","description":"The last name of the customer","example":"Doe"},"dob":{"type":"string","description":"The date of birth of the customer (YYYY-MM-DD)","example":"1990-01-15"},"phone":{"type":"string","description":"The phone number of the customer","example":8012345678},"email":{"type":"string","description":"The email address of the customer","example":"john.doe@example.com"},"gender":{"type":"string","description":"The gender of the customer","example":"Male"}},"required":["license_number","firstname","lastname"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/voters-card":{"post":{"operationId":"verifyVotersCard","tags":["Identity Verification"],"summary":"Verify Voter's Card","description":"Verify a Nigerian Voter Identification Number (VIN).\nReturns voter registration information.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"vin":{"type":"string","description":"The passport number to verify","example":"90F5DB8799296145513"},"firstname":{"type":"string","description":"The first name of the customer","example":"DOE"},"lastname":{"type":"string","description":"The last name of the customer","example":"JOHN"},"dob":{"type":"string","description":"The date of birth of the customer (YYYY-MM-DD)","example":"2022-04-22"}},"required":["vin","firstname","lastname","dob"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/face-match/bvn":{"post":{"operationId":"verifyBvnFaceMatch","tags":["Face Matching"],"summary":"BVN Face Match","description":"Compare a photo against the image on record for a BVN.\nReturns a match confidence score and verification result.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"bvn":{"type":"string","description":"The BVN number to verify","example":95888168924},"photoBase64":{"type":"string","description":"The base 64 format of the imag"},"photoUrl":{"type":"string","description":"The url of the image"},"photo":{"type":"string","description":"The file of the image","format":"binary"}},"required":["bvn"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/face-match/nin":{"post":{"operationId":"verifyNinFaceMatch","tags":["Face Matching"],"summary":"NIN Face Match","description":"Compare a photo against the image on record for a NIN.\nReturns a match confidence score and verification result.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"nin":{"type":"string","description":"The NIN number to verify","example":63184876213},"photoBase64":{"type":"string","description":"The base 64 format of the imag"},"photoUrl":{"type":"string","description":"The url of the image"},"photo":{"type":"string","description":"The file of the image","format":"binary"}},"required":["nin"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/face-match/drivers-license":{"post":{"operationId":"verifyDriversLicenseFaceMatch","tags":["Face Matching"],"summary":"Driver's License Face Match","description":"Compare a photo against the image on a driver's license.\nReturns a match confidence score and verification result.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"dlNumber":{"type":"integer","description":"The NIN number to verify","example":63184876213},"photoBase64":{"type":"string","description":"The base 64 format of the image"},"photoUrl":{"type":"string","description":"The url of the image"},"photo":{"type":"string","description":"The file of the image","format":"binary"}},"required":["dlNumber"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/face-match/passport":{"post":{"operationId":"verifyPassportFaceMatch","tags":["Face Matching"],"summary":"Passport Face Match","description":"Compare a photo against the image on a Nigerian passport.\nReturns a match confidence score and verification result.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"passportNumber":{"type":"string","description":"The NIN number to verify","example":"A10000001"},"photoBase64":{"type":"string","description":"The base 64 format of the image"},"photoUrl":{"type":"string","description":"The url of the image"},"photo":{"type":"string","description":"The file of the image","format":"binary"}},"required":["passportNumber"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/face-match/image":{"post":{"operationId":"compareFaceImages","tags":["Face Matching"],"summary":"Compare two face images","description":"Compare two images for face match using AWS Rekognition.\nAccepts images as base64 encoded strings or HTTP/HTTPS URLs.\nReturns similarity score and match status.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"source_image":{"type":"string","description":"The source image to compare. Can be a base64 encoded string (with or without data URI prefix) or a direct URL starting with http/https","example":"https://example.com/selfie.jpg"},"target_image":{"type":"string","description":"The target image to compare against. Can be a base64 encoded string (with or without data URI prefix) or a direct URL starting with http/https","example":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."},"minimum_similarity_threshold":{"type":"number","format":"float","description":"The minimum similarity percentage (0-100) required for a match. AWS Rekognition will only return faces with similarity above this threshold","example":80}},"required":["source_image","target_image","minimum_similarity_threshold"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/liveness/url":{"post":{"operationId":"initiateLivenessCheck","tags":["Face Matching"],"summary":"Initiate liveness check","description":"Generate a liveness check URL for biometric verification.\nThe user completes verification via the widget, and results are sent to your webhook.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"callback_url":{"type":"string","example":"your-callback.com","description":"The URL to which the user will be redirected after completing the liveness check"},"meta":{"type":"object","example":{}}}}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Liveness url initiated successfully"},"data":{"type":"object","properties":{"widget_url":{"type":"string","description":"The Dojah widget URL that the user should open to complete liveness verification","example":"https://identity.lendoverify.com/?widget_id=68f770cdd629b177f1b622c7"}}}}}}}},"400":{"description":"Bad request - Insufficient funds or widget ID not configured"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/screening/email":{"post":{"operationId":"screenEmail","tags":["Fraud Screening"],"summary":"Email screening","description":"Submit an email address for fraud screening and background intelligence.\n\n**Fee:* NGN charged per request\n\n**Use Cases:**\n- Verify email authenticity before onboarding users\n- Detect disposable/temporary email addresses\n- Check if email has been involved in data breaches\n- Identify malicious or spam-related emails\n- View social media profiles linked to the email\n\n**Response Details:**\n- `reputation`: Overall reputation score (high, medium, low)\n- `suspicious`: Whether the email appears suspicious\n- `blacklisted`: If email is on known blacklists\n- `credentials_leaked`: If email was found in credential leaks\n- `data_breach`: If email was involved in data breaches\n- `disposable`: If email is from a disposable email provider\n- `deliverable`: If email is deliverable\n- `profiles`: Social media platforms linked to this email\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The email address to screen","example":"johndoe@gmail.com"}},"required":["email"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Email screening completed successfully"},"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"email":{"type":"string","example":"johndoe@gmail.com"},"reputation":{"type":"string","example":"high"},"suspicious":{"type":"boolean","example":false},"references":{"type":"integer","example":178},"details":{"type":"object","properties":{"blacklisted":{"type":"boolean"},"malicious_activity":{"type":"boolean"},"credentials_leaked":{"type":"boolean"},"data_breach":{"type":"boolean"},"domain_exists":{"type":"boolean"},"free_provider":{"type":"boolean"},"disposable":{"type":"boolean"},"deliverable":{"type":"boolean"},"profiles":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"400":{"description":"Bad request - Insufficient funds or invalid email"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/screening/phone":{"post":{"operationId":"screenPhone","tags":["Fraud Screening"],"summary":"Phone screening","description":"Submit a phone number for fraud screening and background intelligence.\n\n**Fee:** NGN  charged per request\n\n**Use Cases:**\n- Verify phone number authenticity before onboarding users\n- Detect disposable/virtual phone numbers\n- Identify phone carrier and country\n- Check if phone is registered on social platforms\n- Fraud risk scoring for phone numbers\n\n**Response Details:**\n- `valid`: Whether the phone number is valid\n- `disposable`: If it's a disposable/virtual number\n- `type`: Phone type (mobile, landline, voip)\n- `country`: Country code (e.g., NG for Nigeria)\n- `carrier`: Network carrier (e.g., MTN, Airtel)\n- `score`: Fraud risk score (0 = low risk)\n- `account_details_registered`: Social platforms linked to this phone\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"phone":{"type":"string","description":"The phone number to screen","example":"2348068810228"}},"required":["phone"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Phone screening completed successfully"},"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"number":{"type":"string","example":"2348068810228"},"valid":{"type":"boolean","example":true},"disposable":{"type":"boolean","example":false},"type":{"type":"string","example":"mobile"},"country":{"type":"string","example":"NG"},"carrier":{"type":"string","example":"MTN"},"score":{"type":"integer","example":0},"account_details_registered":{"type":"array","items":{"type":"string"},"example":["facebook","google","twitter"]}}}}}}}}}},"400":{"description":"Bad request - Insufficient funds or invalid phone"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/screening/ip":{"post":{"operationId":"screenIpAddress","tags":["Fraud Screening"],"summary":"IP address screening","description":"Submit an IP address for fraud screening and risk assessment.\n\n**Fee:** NGN charged per request\n\n**Use Cases:**\n- Detect VPN, proxy, and Tor usage\n- Identify high-risk IP addresses\n- Check IP blacklist status\n- Geo-location verification\n- Fraud risk scoring for IP addresses\n\n**Response Details:**\n- `blacklists`: Detections across multiple security engines\n- `information`: Geo-location details (country, city, ISP, ASN)\n- `anonymity`: VPN, proxy, Tor, and hosting detection flags\n- `risk_score`: Overall risk score (0-100, higher = more risky)\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"ip_address":{"type":"string","description":"The IP address to screen","example":"2.58.56.101"}},"required":["ip_address"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"IP screening completed successfully"},"data":{"type":"object","properties":{"entity":{"type":"object","properties":{"report":{"type":"object","properties":{"ip":{"type":"string","example":"2.58.56.101"},"blacklists":{"type":"object","properties":{"detections":{"type":"integer","example":11},"engines_count":{"type":"integer","example":85},"detection_rate":{"type":"string","example":"13%"},"scantime":{"type":"string","example":"0.92"}}},"information":{"type":"object","properties":{"reverse_dns":{"type":"string","example":"powered.by.rdp.sh"},"continent_code":{"type":"string","example":"EU"},"continent_name":{"type":"string","example":"Europe"},"country_code":{"type":"string","example":"DE"},"country_name":{"type":"string","example":"Germany"},"country_currency":{"type":"string","example":"EUR"},"country_calling_code":{"type":"string","example":"49"},"region_name":{"type":"string","example":"Hamburg"},"city_name":{"type":"string","example":"Hamburg"},"latitude":{"type":"number","example":53.575321197509766},"longitude":{"type":"number","example":10.015339851379395},"isp":{"type":"string","example":"1337 Services GmbH"},"asn":{"type":"string","example":"AS210558"}}},"anonymity":{"type":"object","properties":{"is_proxy":{"type":"boolean","example":false},"is_webproxy":{"type":"boolean","example":false},"is_vpn":{"type":"boolean","example":false},"is_hosting":{"type":"boolean","example":false},"is_tor":{"type":"boolean","example":true}}},"risk_score":{"type":"object","properties":{"result":{"type":"integer","example":100}}}}},"success":{"type":"boolean","example":true}}}}}}}}}},"400":{"description":"Bad request - Insufficient funds or invalid IP address"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/aml-screening":{"post":{"operationId":"screenAml","tags":["Fraud Screening"],"summary":"AML Screening","description":"Screen individuals or organizations against PEP, OFAC, AML, Sanctions and Adverse Media across 200+ countries and 42,800+ databases.\n\n**Fee:** NGN per request (uses pep_sanction_check fee)\n\n**Use Cases:**\n- KYC/AML compliance for financial services\n- Politically Exposed Persons (PEP) screening\n- OFAC and international sanctions list checks\n- Adverse media monitoring for reputational risk\n- Customer due diligence (CDD) and enhanced due diligence (EDD)\n\n**Schema Types:**\n- `individual`: For screening persons (supports gender, date_of_birth, nationality, id_number)\n- `organization`: For screening companies (supports registration_number, country_of_incorporation)\n\n**Screening Options:**\n- `pep_check`: Check against Politically Exposed Persons databases\n- `sanction`: Check against OFAC, EU, UN and other sanctions lists\n- `adverse_media_check`: Check against negative news and media sources\n- `match_threshold`: Matching sensitivity (0.0 to 1.0, default 0.85)\n\n**Response Details:**\n- `risk_level`: Overall risk assessment (Low, Medium, High)\n- `match_status`: Confirmed Match, Potential Match, or No Match\n- `results`: Array of matched records with source_type (PEP, SANCTIONS, CRIMINAL, ADVERSE_MEDIA)\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"names":{"type":"string","description":"Full name of the individual or organization","example":"John Doe"},"schema":{"type":"string","enum":["individual","organization"],"description":"Screening type","example":"individual"},"gender":{"type":"string","enum":["male","female"],"description":"Gender of the individual (for individual schema)","example":"male"},"date_of_birth":{"type":"string","format":"date","description":"Date of birth in YYYY-MM-DD format (for individual schema)","example":"1990-01-01"},"nationality":{"type":"string","description":"Nationality of the individual (for individual schema)","example":"Nigerian"},"id_number":{"type":"string","description":"ID number of the individual (for individual schema)","example":"AD45UIOO123"},"registration_number":{"type":"string","description":"Registration number (for organization schema)","example":"RC12345678"},"country_of_incorporation":{"type":"string","description":"Country of incorporation (for organization schema)","example":"NG"},"unique_reference":{"type":"string","description":"Optional unique identifier for the screening request","example":"ref123456"},"pep_check":{"type":"boolean","description":"Perform Politically Exposed Person (PEP) check","example":true},"sanction":{"type":"boolean","description":"Perform sanction screening","example":true},"adverse_media_check":{"type":"boolean","description":"Perform adverse media check","example":true},"match_threshold":{"type":"number","description":"Match threshold score between 0 and 1","example":0.85}},"required":["names"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"AML screening completed successfully"},"data":{"type":"object","properties":{"entity_type":{"type":"string","example":"individual"},"entity_id":{"type":"string","example":"123450987qwergoi"},"date":{"type":"string","example":"2025-05-14T01:37:53.423Z"},"total_results":{"type":"integer","example":7},"search_query":{"type":"string","example":"John Doe"},"risk_level":{"type":"string","example":"Medium"},"match_status":{"type":"string","example":"Confirmed Match"},"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"source_type":{"type":"string","description":"PEP, CRIMINAL, SANCTIONS, or ADVERSE_MEDIA"},"country":{"type":"string"},"positions":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"400":{"description":"Bad request - Insufficient funds or invalid data"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/screening/user":{"post":{"operationId":"screenUser","tags":["Fraud Screening"],"summary":"Comprehensive user screening","description":"Comprehensive user screening that combines email, phone, IP address and AML screening in a single API call.\n\n**Fee:** NGN charged per request\n\n**Use Cases:**\n- Complete fraud risk assessment for new user onboarding\n- Combined email + phone + IP + AML check in one request\n- Single API call for comprehensive user due diligence\n- Risk scoring across multiple data points\n- Detect high-risk users before granting access\n\n**Required Fields:**\n- `first_name`: User's first name\n- `last_name`: User's last name\n- `date_of_birth`: Date of birth (YYYY-MM-DD format)\n\n**Optional Fields for Enhanced Screening:**\n- `middle_name`: User's middle name\n- `email`: Email address for email fraud check\n- `phone`: Phone number for phone fraud check\n- `ip_address`: IP address for geolocation and proxy/VPN detection\n\n**Response Details:**\n- `overall_risk_score`: Combined risk score (0-100, lower is safer)\n- `email_check_result`: Email fraud analysis with domain details, breach history, and social profiles\n- `phone_check_result`: Phone validation with carrier info, risk flags, and platform registrations\n- `ip_check_result`: IP analysis with geolocation, blacklist status, and anonymity detection (VPN/Proxy/Tor)\n- `aml_screening_result`: PEP, sanctions, and adverse media screening results\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"first_name":{"type":"string","description":"User's first name (required)","example":"John"},"last_name":{"type":"string","description":"User's last name (required)","example":"Doe"},"middle_name":{"type":"string","description":"User's middle name (optional)","example":"Smith"},"date_of_birth":{"type":"string","format":"date","description":"Date of birth in YYYY-MM-DD format (required)","example":"1990-05-15"},"email":{"type":"string","format":"email","description":"Email address for email screening (optional)","example":"john.doe@example.com"},"phone":{"type":"string","description":"Phone number for phone screening (optional)","example":"2348068810228"},"ip_address":{"type":"string","format":"ipv4","description":"IP address for geolocation and proxy detection (optional)","example":"102.89.23.45"}},"required":["first_name","last_name","date_of_birth"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"User screening completed successfully"},"data":{"type":"object","properties":{"overall_risk_score":{"type":"integer","description":"Combined risk score (0-100, lower is safer)","example":20},"email_check_result":{"type":"object","properties":{"email":{"type":"string","example":"john.doe@example.com"},"valid":{"type":"boolean","example":true},"deliverable":{"type":"boolean","example":true},"score":{"type":"integer","description":"Email risk score","example":4},"domain_details":{"type":"object","properties":{"registered":{"type":"boolean","example":true},"free":{"type":"boolean","example":true},"disposable":{"type":"boolean","example":false},"valid_mx":{"type":"boolean","example":true}}},"breach_details":{"type":"object","properties":{"haveibeenpwned_listed":{"type":"boolean","example":false},"number_of_breaches":{"type":"integer","example":0}}},"account_details_registered":{"type":"array","items":{"type":"string"},"example":["linkedin","twitter"]}}},"phone_check_result":{"type":"object","properties":{"number":{"type":"string","example":"2348068810228"},"valid":{"type":"boolean","example":true},"type":{"type":"string","example":"mobile"},"country":{"type":"string","example":"NG"},"carrier":{"type":"string","example":"MTN"},"disposable":{"type":"boolean","example":false},"score":{"type":"integer","description":"Phone risk score","example":4},"flags":{"type":"array","items":{"type":"string"}},"account_details_registered":{"type":"array","items":{"type":"string"},"example":["facebook","google"]}}},"ip_check_result":{"type":"object","properties":{"ip":{"type":"string","example":"102.89.23.45"},"ip_details":{"type":"object","properties":{"country_code":{"type":"string","example":"NG"},"country_name":{"type":"string","example":"Nigeria"},"city_name":{"type":"string","example":"Lagos"}}},"blacklists":{"type":"object","properties":{"detections":{"type":"integer","example":0},"engines_count":{"type":"integer","example":85},"detection_rate":{"type":"string","example":"0%"}}},"anonymity":{"type":"object","description":"Proxy/VPN/Tor detection","properties":{"is_proxy":{"type":"boolean","example":false},"is_vpn":{"type":"boolean","example":false},"is_tor":{"type":"boolean","example":false}}},"risk_score":{"type":"object","properties":{"result":{"type":"integer","example":10}}}}},"aml_screening_result":{"type":"array","description":"PEP, sanctions, and adverse media matches (empty if no matches)","items":{"type":"object"}}}}}}}}},"400":{"description":"Bad request - Insufficient funds or invalid data"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/cac-basic":{"post":{"operationId":"verifyCacBasic","tags":["Identity Verification"],"summary":"Verify CAC (Basic)","description":"Verify a Corporate Affairs Commission (CAC) registration number.\nReturns basic company registration information.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"The CAC to verify","example":"RC100001"}},"required":["number"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/cac-premium":{"post":{"operationId":"verifyCacPremium","tags":["Identity Verification"],"summary":"Verify CAC (Premium)","description":"Verify a Corporate Affairs Commission (CAC) registration number with enhanced data.\nReturns comprehensive company information including directors and shareholders.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"The CAC to verify","example":"RC100001"}},"required":["number"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/tin":{"post":{"operationId":"verifyTin","tags":["Identity Verification"],"summary":"Verify TIN","description":"Verify a Tax Identification Number (TIN) via CAC using RC Number and Company Type.\nReturns company tax information and registration details.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"rc_number":{"type":"string","description":"The company's CAC registration (RC) number.","example":"1261103"},"company_type":{"type":"string","description":"The entity type registered with the CAC.","example":"COMPANY","enum":["BUSINESS_NAME","COMPANY","INCORPORATED_TRUSTEES","LIMITED_PARTNERSHIP","LIMITED_LIABILITY_PARTNERSHIP"]}},"required":["rc_number","company_type"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/address/individual":{"post":{"operationId":"verifyIndividualAddress","tags":["Address Verification"],"summary":"Individual address verification","description":"Submit an address for physical verification of an individual in Nigeria.\n\n**Fee:** NGN 2000 charged per request\n\n**Use Cases:**\n- Verify residential address of an individual\n- Physical field verification with agent visit\n- KYC address verification for financial services\n\n**Response Details:**\n- `status`: Verification status (pending initially)\n- `reference_id`: Unique reference to track verification progress\n\n**Note:** This is an asynchronous verification. The initial response will have status \"pending\".\nUse the GET /api/customers/identities/address endpoint to check status, or receive a webhook when completed.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"first_name":{"type":"string","description":"First name of the individual","example":"John"},"last_name":{"type":"string","description":"Last name of the individual","example":"Doe"},"middle_name":{"type":"string","description":"Middle name of the individual","example":"Kabiru"},"dob":{"type":"string","description":"Date of birth (yyyy-mm-dd)","example":"1988-01-17"},"gender":{"type":"string","description":"Gender of the individual","example":"Male","enum":["Male","Female"]},"mobile":{"type":"string","description":"Active mobile number of the individual","example":"08012345678"},"street":{"type":"string","description":"House number and street name","example":"270 Murtala Muhammed Way, Alagomeji"},"landmark":{"type":"string","description":"Closest landmark to the street","example":"Yaba Bus Stop"},"lga":{"type":"string","description":"Local Government Area","example":"Lagos Mainland"},"state":{"type":"string","description":"State","example":"Lagos"}},"required":["first_name","last_name","middle_name","dob","gender","mobile","street","landmark","lga","state"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Individual address verification initiated successfully"},"data":{"type":"object","properties":{"status":{"type":"string","example":"pending"},"reference_id":{"type":"string","example":"69e10264-4b90-64fe-b4b7-c9dddafd0241"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/address/business":{"post":{"operationId":"verifyBusinessAddress","tags":["Address Verification"],"summary":"Business address verification","description":"Submit an address for physical verification of a business in Nigeria.\n\n**Fee:** NGN 2000 charged per request\n\n**Use Cases:**\n- Verify business premises location\n- Physical field verification with agent visit\n- KYC address verification for business onboarding\n\n**Response Details:**\n- `status`: Verification status (pending initially)\n- `reference_id`: Unique reference to track verification progress\n\n**Note:** This is an asynchronous verification. The initial response will have status \"pending\".\nUse the GET /api/customers/identities/address endpoint to check status, or receive a webhook when completed.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"business_name":{"type":"string","description":"Name of the business","example":"Acme Technologies Ltd"},"business_mobile":{"type":"string","description":"Office mobile number of the business","example":"08098765432"},"business_email":{"type":"string","description":"Business email address","example":"info@acmetech.com"},"first_name":{"type":"string","description":"First name of business owner","example":"John"},"last_name":{"type":"string","description":"Last name of business owner","example":"Doe"},"mobile":{"type":"string","description":"Mobile number of business owner","example":"08012345678"},"street":{"type":"string","description":"House number and street name of the business","example":"15 Broad Street"},"landmark":{"type":"string","description":"Closest landmark to the location","example":"Marina Bus Stop"},"lga":{"type":"string","description":"Local Government Area","example":"Lagos Island"},"city":{"type":"string","description":"City","example":"Lagos"},"state":{"type":"string","description":"State","example":"Lagos"}},"required":["business_name","business_mobile","first_name","last_name","mobile","street","landmark","lga","city","state"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Business address verification initiated successfully"},"data":{"type":"object","properties":{"status":{"type":"string","example":"pending"},"reference_id":{"type":"string","example":"69e10264-4b90-64fe-b4b7-c9dddafd0241"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/identities/address":{"get":{"operationId":"getAddressVerificationStatus","tags":["Address Verification"],"summary":"Get address verification status","description":"Retrieve the status and details of an address verification request.\n\n**Fee:** FREE - No charge for this endpoint\n\n**Use Cases:**\n- Check the status of a pending address verification\n- Retrieve completed verification details\n- Get failure reasons for failed verifications\n\n**Status Values:**\n- `pending`: Verification is still in progress\n- `completed`: Verification completed successfully\n- `failed`: Verification failed\n\n**Response Details (when completed):**\n- `applicant`: Details of the person/business verified\n- `location`: GPS coordinates of the verified address\n- `photos`: Photos taken during verification\n- `neighbor`: Information from neighbor interview\n- `street`, `lga`, `state`, `city`, `country`: Address details\n","parameters":[{"name":"reference_id","in":"query","required":true,"description":"The reference ID returned from the address verification initiation","schema":{"type":"string","example":"69e10264-4b90-64fe-b4b7-c9dddafd0241"}}],"responses":{"200":{"description":"Request successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Address verification status retrieved successfully"},"data":{"type":"object","properties":{"status":{"type":"string","example":"completed"},"reference_id":{"type":"string","example":"69e10264-4b90-64fe-b4b7-c9dddafd0241"},"data":{"type":"object","properties":{"applicant":{"type":"object","properties":{"first_name":{"type":"string","example":"John"},"last_name":{"type":"string","example":"Doe"},"mobile":{"type":"string","example":"08012345678"},"middle_name":{"type":"string","example":"Kabiru"},"gender":{"type":"string","example":"Male"},"dob":{"type":"string","example":"17/01/1988"}}},"lattitude":{"type":"string","example":"7.081273"},"longitude":{"type":"string","example":"8.232523"},"photos":{"type":"array","items":{"type":"string"},"example":["https://example.com/photo1.jpg"]},"neighbor":{"type":"object","properties":{"name":{"type":"string","example":"Musa Garba"},"comment":{"type":"string","example":"Very friendly"},"phone":{"type":"string","example":"080987654321"}}},"city":{"type":"string","example":"oshodi"},"street":{"type":"string","example":"270 Murtala Muhammed Way, Alagomeji. Yaba"},"lga":{"type":"string","example":"lagos mainland"},"state":{"type":"string","example":"Lagos"},"country":{"type":"string","example":"Nigeria"}}}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Address verification record not found"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bureaus/crc":{"post":{"operationId":"checkCrcBureau","tags":["Credit Check"],"summary":"CRC Credit Bureau check","description":"Query the CRC (Credit Bureau Nigeria) database for credit history.\nReturns credit score and loan repayment history.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"bvn":{"type":"string","description":"The BVN to verify","example":95888168924}},"required":["bvn"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"examples":{"hit":{"summary":"BVN found (hit)","value":{"message":"Request successful","data":{"ConsumerHitResponse":{"BODY":{"AddressHistory":null,"Amount_OD_BucketCURR1":null,"CONSUMER_RELATION":{"RELATED_TO":null},"CREDIT_MICRO_SUMMARY":null,"CREDIT_NANO_SUMMARY":{"SUMMARY":{"HAS_CREDITFACILITIES":"NO","LAST_REPORTED_DATE":null,"NO_OF_DELINQCREDITFACILITIES":"0"}},"CREDIT_SCORE_DETAILS":null,"ClassificationInsType":null,"ClassificationProdType":null,"ClosedAccounts":null,"ConsCommDetails":null,"ConsumerMergerDetails":null,"ContactHistory":null,"CreditDisputeDetails":null,"CreditFacilityHistory24":null,"CreditProfileOverview":null,"CreditProfileSummaryCURR1":null,"CreditProfileSummaryCURR2":null,"CreditProfileSummaryCURR3":null,"CreditProfileSummaryCURR4":null,"CreditProfileSummaryCURR5":null,"DMMDisputeSection":null,"DODishonoredChequeDetails":null,"DOJointHolderDetails":null,"DOLitigationDetails":null,"DisclaimerDetails":null,"EmploymentHistory":null,"GuaranteedLoanDetails":null,"InquiryHistoryDetails":null,"Inquiry_Product":null,"LegendDetails":null,"MFCREDIT_MICRO_SUMMARY":null,"MFCREDIT_NANO_SUMMARY":{"SUMMARY":{"HAS_CREDITFACILITIES":"YES","NO_OF_DELINQCREDITFACILITIES":"21"}},"MGCREDIT_MICRO_SUMMARY":null,"MGCREDIT_NANO_SUMMARY":{"SUMMARY":{"HAS_CREDITFACILITIES":"NO","NO_OF_DELINQCREDITFACILITIES":"0"}},"MIC_CONSUMER_PROFILE":null,"NANO_CONSUMER_PROFILE":{"CONSUMER_DETAILS":{"CITIZENSHIP":"NG","DATE_OF_BIRTH":"15-JUN-1990","FIRST_NAME":"JOHN","GENDER":"001","IDENTIFICATION":[{"EXP_DATE":null,"EXP_DATESpecified":false,"ID_DISPLAY_NAME":"Business Verification Number","ID_VALUE":"12345678901","RUID":"1112019001376303","SOURCE_ID":"BVN"}],"IDENTIFICATION_DETAILS":[{"EXPIRY_DATE":"Expiry Date","EXP_DATE":null,"ID_DISPLAY_NAME":"Passport Authority","ID_VALUE":"A12345678901234","RUID":"1112019001376303","SOURCE_ID":"PAS"}],"LAST_NAME":"DOE","NAME":"JOHN JAMES DOE","RUID":"1112019001376303"}},"RelatedToDetails":null,"ReportDetail":null,"ReportDetailAcc":null,"ReportDetailBVN":null,"ReportDetailMob":null,"ReportDetailsSIR":null,"SecurityDetails":null,"SummaryOfPerformance":null},"HEADER":{"REPORTHEADER":{"MAILTO":"support@crccreditbureau.com","PRODUCTNAME":"Nano Consumer Report","REASON":[],"REPORTDATE":"01/Jan/2026","REPORTORDERNUMBER":"W-0000000000/2026","USERID":"your_user_id"},"RESPONSETYPE":{"CODE":"1","DESCRIPTION":"Response DataPacket"},"SEARCHCRITERIA":{"BRANCHCODE":null,"BVN_NO":"12345678901","CFACCOUNTNUMBER":null,"DATEOFBIRTH":null,"GENDER":null,"NAME":null,"TELEPHONE_NO":null},"SEARCHRESULTLIST":{"SEARCHRESULTITEM":{"ADDRESSES":"","BUREAUID":"1112023003307783","CONFIDENCESCORE":"100","IDENTIFIERS":"","NAME":"JOHN DOE","SURROGATES":""}}},"REQUESTID":"1"}}}},"no_hit":{"summary":"BVN not found (no hit)","value":{"message":"Request successful","data":{"ConsumerNoHitResponse":{"HEADER":{"REPORTHEADER":{"MAILTO":"support@crccreditbureau.com","PRODUCTNAME":"Nano Consumer Report","REASON":[],"REPORTDATE":"01/Jan/2026","REPORTORDERNUMBER":"W-0000000000/2026","USERID":"your_user_id"},"RESPONSETYPE":{"CODE":"0","DESCRIPTION":"No Hit"},"SEARCHCRITERIA":{"BRANCHCODE":null,"BVN_NO":"12345678901","CFACCOUNTNUMBER":null,"DATEOFBIRTH":null,"GENDER":null,"NAME":null,"TELEPHONE_NO":null}},"REQUESTID":"1"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bureaus/first-central":{"post":{"operationId":"checkFirstCentralBureau","tags":["Credit Check"],"summary":"First Central Credit Bureau check","description":"Query the First Central Credit Bureau database for credit history.\nReturns credit score and loan repayment history.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"bvn":{"type":"string","description":"The BVN to verify","example":95888168924}},"required":["bvn"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"examples":{"hit":{"summary":"BVN found (hit)","value":{"message":"Request successful","data":[{"SubjectList":[{"ConsumerID":10000001,"SearchOutput":"Adeyemi, James, , 12 Adeola Crescent, Lekki, Lagos","Reference":10000001}]},{"PersonalDetailsSummary":[{"Header":"PERSONAL DETAILS SUMMARY: Adeyemi James","ConsumerID":10000001,"ReferenceNo":null,"Nationality":"Nigeria","NationalIDNo":"12345678901","PassportNo":null,"DriversLicenseNo":null,"BankVerificationNo":"12345678901","PencomIDNo":"","otheridNo":"","BirthDate":"10/05/1988","Dependants":0,"Gender":"Male","MaritalStatus":null,"ResidentialAddress1":"12 Adeola Crescent, Lekki, Lagos","ResidentialAddress2":"","ResidentialAddress3":"Eti-Osa","ResidentialAddress4":"Lagos","PostalAddress1":"12 Adeola Crescent, Lekki, Lagos","PostalAddress2":"12 Adeola Crescent, Lekki, Lagos","PostalAddress3":"Eti-Osa","PostalAddress4":"Lagos Nigeria","HomeTelephoneNo":null,"WorkTelephoneNo":null,"CellularNo":"08000000000","EmailAddress":"","EmployerDetail":null,"PropertyOwnedType":"","Surname":"Adeyemi","FirstName":"James","OtherNames":""}]},{"CreditSummary":[{"TotalNumberOfAccountsReported":"12","NumberOfAccountsInGoodStanding":"10","NumberOfAccountsInBadStanding":"2"}]},{"PerformanceClassification":[{"NoOfLoansPerforming":"10","NoOfLoansSubstandard":"1","NoOfLoansDoubtful":"1","NoOfLoansLost":"0"}]},{"EnquiryDetails":[{"SubscriberEnquiryResultID":null,"ProductID":null,"MatchingRate":null,"SubscriberEnquiryEngineID":null}]}]}},"no_hit":{"summary":"BVN not found (no hit)","value":{"message":"Request successful","data":{"message":"Consumer does not exist."}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bureaus/credit-registry":{"post":{"operationId":"checkCreditRegistry","tags":["Credit Check"],"summary":"Credit Registry check","description":"Query the Credit Registry database for credit history.\nReturns credit score and loan repayment history.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"bvn":{"type":"string","description":"The BVN to verify","example":95888168924}},"required":["bvn"]}}}},"responses":{"200":{"description":"Request successful","content":{"application/json":{"examples":{"hit":{"summary":"BVN found (hit)","value":{"message":"Request successful","data":{"SearchResult":[{"RegistryID":"736318553238690082","Name":"John James Doe","IsPerforming":false},{"RegistryID":"737346491626147206","Name":"John James Doe","IsPerforming":false},{"RegistryID":"737377662138766037","Name":"John James Doe","IsPerforming":false},{"RegistryID":"737401406287722193","Name":"John James","IsPerforming":true},{"RegistryID":"737738509703731399","Name":"John James Doe","IsPerforming":false}],"Success":true,"Errors":[],"InfoMessage":"","TransactionID":"27495481"}}},"no_hit":{"summary":"BVN not found (no hit)","value":{"message":"Request successful","data":{"SearchResult":[],"Success":true,"Errors":[],"InfoMessage":"","TransactionID":"27510838"}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transfer":{"post":{"operationId":"initiateTransfer","tags":["Payments"],"summary":"Initiate a transfer","description":"Transfer funds from your wallet to a Nigerian bank account.\nSupports all major Nigerian banks.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"The amount to transfer (in KOBO form i.e 100000 = 1000)","example":100000},"name":{"type":"string","description":"The name of the recipient","example":"John Doe"},"account_number":{"type":"string","description":"The account number of the recipient","example":1234567890},"bank_code":{"type":"string","description":"The bank code of the recipient","example":1},"reason":{"type":"string","description":"The reason for the transfer","example":"Payment"},"reference":{"type":"string","description":"A reference for the transfer","example":"LENDOV-123452FDSDW"},"metadata[]":{"type":"object","description":"Metadata for the transfer","example":{"key":"value"}}},"required":["amount","name","account_number","bank_code"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transfer/verify-otp":{"post":{"operationId":"verifyTransferOtp","tags":["Payments"],"summary":"Verify transfer OTP","description":"Verify the OTP and complete a pending transfer.\nThe transfer is executed upon successful OTP verification.\n","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"transfer_id":{"type":"integer","description":"ID of the pending transfer transaction.","example":123},"otp":{"type":"string","description":"One-time password sent to the user.","example":"482910"}},"required":["transfer_id","otp"]}}}},"responses":{"200":{"description":"Transfer verified and initiated successfully."},"400":{"description":"Validation error"},"401":{"description":"Unauthenticated or Unauthorized"},"default":{"description":"Fallback for undocumented status code","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/customers/transfer/resend-otp":{"post":{"operationId":"resendTransferOtp","tags":["Payments"],"summary":"Resend transfer OTP","description":"Resend a new OTP for a pending transfer.\nThe previous OTP will be invalidated.\n","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"transfer_id":{"type":"integer","description":"ID of the transfer transaction.","example":123}},"required":["transfer_id"]}}}},"responses":{"200":{"description":"A new OTP was successfully sent to the user's registered number and email."},"400":{"description":"Validation error"},"401":{"description":"Unauthenticated or Unauthorized"},"default":{"description":"Fallback for undocumented status code","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/customers/fees":{"get":{"operationId":"getFees","tags":["Payments"],"summary":"Get default fees","description":"Retrieve the default fee schedule for all services on the platform.\nThis is an open endpoint and does not require authentication.\n","responses":{"200":{"description":"Fees fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Fees fetched successfully"},"data":{"type":"object","properties":{"fees":{"type":"object","description":"Fee amounts (in Naira) for each service","properties":{"nin_with_nin":{"type":"number","example":80},"bvn_basic":{"type":"number","example":55},"bvn_premium":{"type":"number","example":70},"bvn_face_match":{"type":"number","example":130},"nin_face_match":{"type":"number","example":130},"drivers_license":{"type":"number","example":90},"drivers_license_face_match":{"type":"number","example":100},"nigerian_passport":{"type":"number","example":90},"passport_face_match":{"type":"number","example":130},"voters_card":{"type":"number","example":90},"cac_basic":{"type":"number","example":115},"cac_premium":{"type":"number","example":160},"tin":{"type":"number","example":80},"crc":{"type":"number","example":107},"first_central":{"type":"number","example":107},"credit_registry":{"type":"number","example":107},"pep_sanction_check":{"type":"number","example":400},"liveness_check":{"type":"number","example":35},"image_face_match":{"type":"number","example":25},"physical_address":{"type":"number","example":1500},"business_address_verification":{"type":"number","example":1500},"digital_address_4d":{"type":"number","example":115},"email_screening":{"type":"number","example":50},"phone_screening":{"type":"number","example":50},"ip_screening":{"type":"number","example":50},"user_screening":{"type":"number","example":500},"sms":{"type":"number","example":6},"email":{"type":"number","example":2},"direct_debit":{"type":"number","example":1.5},"direct_debit_capped":{"type":"number","example":200000},"dedicated_virtual_accounts":{"type":"number","example":1.5},"transfers_5000_and_below":{"type":"number","example":20},"transfers_5001_and_50000":{"type":"number","example":35},"transfers_above_50000":{"type":"number","example":60}}}}}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/api/customers/transaction/initialize":{"post":{"operationId":"initializeTransaction","tags":["Payments"],"summary":"Initialize payment transaction","description":"Initialize a payment collection transaction.\nReturns a payment link for your customer to complete payment.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"customerEmail":{"type":"string","description":"The email of the customer","example":"ravi@demo.com"},"customerName":{"type":"string","description":"The name of the customer","example":"John Doe"},"amount":{"type":"number","format":"float","description":"The amount to transfer (in KOBO form i.e 100000 = 1000)","example":500000},"paymentReference":{"type":"string","description":"The unique reference for the transaction"},"paymentDescription":{"type":"string","description":"The description of the transaction"},"paymentMethods[]":{"type":"array","description":"Accepted payment methods for this transaction. If not provided, all methods (CARD and ACCOUNT_TRANSFER) are enabled by default.","items":{"type":"string","enum":["CARD","ACCOUNT_TRANSFER","USSD","PHONE_NUMBER"]},"example":["CARD"]},"redirectUrl":{"type":"string","description":"Fully qualified url, e.g. https://example.com/ ."},"metadata[]":{"type":"object","description":"Stringified JSON object of custom data."}},"required":["customerEmail","amount"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transaction/verify":{"post":{"operationId":"verifyTransaction","tags":["Payments"],"summary":"Verify transaction status","description":"Confirm the status of a previously initialized payment transaction.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"reference":{"type":"string"}},"description":"The paymentReference of the transaction","required":["reference"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transaction/charge-authorization":{"post":{"operationId":"chargeCardToken","tags":["Payments"],"summary":"Charge saved card token","description":"Charge a previously saved card token to receive payments from the customer","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"card_token":{"type":"string","description":"The card token to charge","example":"MNFY_CARD_TOKEN_123456"},"amount":{"type":"number","description":"The amount to charge (in kobo, minimum 100 i.e ₦1)","example":100000},"reference":{"type":"string","description":"Optional unique reference for the transaction. Auto-generated if not provided.","example":"TXN_REF_123456"},"payment_description":{"type":"string","description":"Optional description for the payment","example":"Payment for order","maxLength":255}},"required":["card_token","amount"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transaction/charge-card":{"post":{"operationId":"chargeCard","tags":["Payments"],"summary":"Charge card and save token","description":"Charge a user's card and save the card token for future transactions.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"cardNumber":{"type":"string","description":"The card number","example":"4242424242424242"},"expiryMonth":{"type":"string","description":"The expiry month","example":"12"},"expiryYear":{"type":"string","description":"The expiry year","example":"2026"},"pin":{"type":"string","description":"The pin","example":"1234"},"cvv":{"type":"string","description":"The cvv","example":"123"},"reference":{"type":"string","description":"The TransactionReference generated from the Initialize Transaction endpoint","example":"MNFY|49|123456"}},"required":["cardNumber","expiryMonth","expiryYear","pin","cvv","reference"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transaction/charge-card-otp":{"post":{"operationId":"chargeCardOtp","tags":["Payments"],"summary":"Verify card charge OTP","description":"Submit the OTP to complete a card charge transaction.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The reference of the charge","example":"MNFY|49|123456"},"token_id":{"type":"string","description":"The token ID from the OTP data","example":"123456"},"token":{"type":"string","description":"The otp from the customer","example":"666777"}},"required":["reference","token_id","token"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transaction/check-out":{"post":{"operationId":"checkoutPayment","tags":["Checkout"],"summary":"Afihan checkout","description":"Afihan checkout with card and bank transfer payment. Initializes a payment transaction and returns a checkout link. The customer is redirected to the checkout page to complete payment.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"The amount to charge (in kobo/minor units, minimum 100)","example":10000},"customerEmail":{"type":"string","format":"email","description":"The customer's email address","example":"customer@example.com"},"customerName":{"type":"string","description":"The customer's name (optional)","example":"John Doe"},"paymentDescription":{"type":"string","description":"Description of the payment (optional)","example":"Wallet top-up"},"redirectUrl":{"type":"string","description":"Fully qualified url, e.g. https://example.com/ ."},"paymentReference":{"type":"string","description":"Custom payment reference (optional, auto-generated if not provided)","example":"LNV-123456"},"paymentMethods[]":{"type":"array","description":"Accepted payment methods for this transaction. If not provided, all methods (CARD and ACCOUNT_TRANSFER) are enabled by default.","items":{"type":"string","enum":["CARD","ACCOUNT_TRANSFER"]},"example":["CARD"]},"metadata[]":{"type":"object","description":"Stringified JSON object of custom data."}},"required":["amount","customerEmail"]}}}},"responses":{"200":{"description":"Checkout initialized successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payment link generated"},"data":{"type":"object","properties":{"payment_link":{"type":"string","example":"https://www.afihan.com/checkout?ref=MNFY%257C11%257C2026040333259%257C025148"},"transaction_ref":{"type":"string","description":"The Monnify transaction reference","example":"MNFY|20210101120000|000001"},"merchant_ref":{"type":"string","example":"LNV-123456"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transaction/bank-transfer":{"post":{"operationId":"initiateBankTransfer","tags":["Payments"],"summary":"Initiate bank transfer payment","description":"Initiates a bank transfer payment using the transaction reference from a previously initialized transaction. This generates bank account details for the customer to make a transfer.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The transaction reference from a previously initialized transaction","example":"MNFY|20210101120000|000001"},"bankCode":{"type":"string","description":"Optional bank code to specify preferred bank for transfer","example":"035"}},"required":["reference"]}}}},"responses":{"200":{"description":"Bank transfer initiated successfully. Returns bank account details for the transfer."},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/transaction/payment-details":{"get":{"operationId":"checkoutPaymentDetails","tags":["Checkout"],"summary":"Get payment details","description":"Retrieves payment details for a transaction using the payment reference. The amount is returned in kobo.","parameters":[{"name":"reference","in":"query","required":true,"schema":{"type":"string","example":"LNV-UrTZq2021201"},"description":"The payment reference"}],"responses":{"200":{"description":"Payment details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"The payment amount in kobo","example":10000},"description":{"type":"string","description":"The payment description","example":"Wallet top-up"},"status":{"type":"string","description":"The live payment status from Monnify","example":"PAID"},"reference":{"type":"string","description":"The merchant payment reference","example":"LNV-123456"},"date":{"type":"string","description":"The transaction date","example":"2026-01-01 12:00:00"},"mode":{"type":"string","description":"The mode the transaction was made in","example":"live"},"payment_method":{"type":"string","nullable":true,"description":"The payment method used for the transaction","example":"CARD"},"customer":{"nullable":true,"type":"object","properties":{"name":{"type":"string","description":"The customer's name","example":"John Doe"},"email":{"type":"string","description":"The customer's email","example":"customer@example.com"}}}}}}}},"404":{"description":"Payment data not found or expired"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/direct-debit/nip-transfer":{"post":{"operationId":"directDebitNipTransfer","tags":["Payments"],"summary":"Direct debit NIP transfer","description":"Charge an account with direct debit mandate and transfer funds to recipient.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The email of the customer to charge for direct debit","example":"ravi@demo.com"},"amount":{"type":"string","description":"The amount to transfer (in KOBO form i.e 100000 = 1000)","example":100000},"name":{"type":"string","description":"The name of the recipient","example":"John Doe"},"account_number":{"type":"string","description":"The account number of the recipient","example":1234567890},"bank_code":{"type":"string","description":"The bank code of the recipient","example":1},"reason":{"type":"string","description":"The reason for the transfer","example":"Payment"},"reference":{"type":"string","description":"The reference for the transfer"}},"required":["amount","name","account_number","bank_code","email"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/commercial-banks":{"get":{"operationId":"getCommercialBanks","tags":["Direct Debit"],"summary":"Get supported commercial banks","description":"Returns the list of commercial banks supported for direct debit mandate setup.\nUse the `bankCode` from this list when initializing a direct debit mandate.\n","responses":{"200":{"description":"Request successful","content":{"application/json":{"example":{"message":"Request successful","data":[{"bankCode":"044","bankName":"Access Bank"},{"bankCode":"050","bankName":"Ecobank Nigeria"},{"bankCode":"011","bankName":"First Bank of Nigeria"},{"bankCode":"058","bankName":"Guaranty Trust Bank"},{"bankCode":"076","bankName":"Polaris Bank"},{"bankCode":"221","bankName":"Stanbic IBTC Bank"},{"bankCode":"232","bankName":"Sterling Bank"},{"bankCode":"033","bankName":"United Bank For Africa"},{"bankCode":"035","bankName":"Wema Bank"},{"bankCode":"057","bankName":"Zenith Bank"}]}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/direct-debit/initialize":{"post":{"operationId":"initializeDirectDebit","tags":["Direct Debit"],"summary":"Initialize direct debit mandate","description":"Create a direct debit mandate for recurring payments (commercial banks only). **Note:** The duration between `start_date` and `end_date` must be a minimum of 30 days.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"customer_name":{"type":"string","description":"The name of the customer","example":"John Doe"},"phone_number":{"type":"string","description":"The phone number of the customer","example":8012345678},"email":{"type":"string","description":"The email of the customer","example":"ravi@demo.com"},"account_number":{"type":"string","description":"The account number of the customer","example":1234567890},"bank_code":{"type":"string","description":"The bank code of the customer","example":58},"address":{"type":"string","description":"The address of the customer","example":"456 New Street, Lagos"},"callback_url":{"type":"string","description":"The name callback url for customer","example":"https://yourcallback.com"},"start_date":{"type":"string","format":"date-time","description":"The start date for the mandate (YYYY-MM-DDTHH:MM:SS). The duration between start_date and end_date must be a minimum of 30 days.","example":"2023-12-25T10:00:00"},"end_date":{"type":"string","format":"date-time","description":"The end date for the mandate (YYYY-MM-DDTHH:MM:SS). The duration between start_date and end_date must be a minimum of 30 days.","example":"2024-12-25T10:00:00"},"mandateDescription":{"type":"string","description":"The description of the payment the mandate is associated to","example":"Product payment"},"mandateReference":{"type":"string","description":"The reference of the mandate","example":"1_abc123xyz456"},"mandateAmount":{"type":"integer","nullable":true,"description":"Total lifetime amount debitable on the mandate, in kobo.","example":5000000}},"required":["customer_name","phone_number","email","account_number","bank_code","address","start_date","end_date","mandateDescription"]}}}},"responses":{"200":{"description":"Mandate initialized successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Request successful."},"data":{"type":"object","properties":{"redirect_url":{"type":"string","description":"URL to redirect the customer to authorize the mandate","example":"https://paylink.com/mandate-auth/MNDD%ZFNBSF0PC9TTM7GVCPYDK?accountNumber=9880218357&bankName=Paystack-Titan+Bank"},"mandate_reference":{"type":"string","description":"The unique reference for the mandate","example":"LNV-MAND-Zr0GW202603WW11"}}}}}}}},"400":{"description":"Bad request - Validation error or mandate creation failed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Mandate initialization failed. Please try again."}}}}}},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":false},"message":{"type":"string","example":"API Key is missing"}}}}}},"422":{"description":"Unprocessable Entity - Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The given data was invalid."},"errors":{"type":"object"}}}}}},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/direct-debit/charge":{"post":{"operationId":"chargeDirectDebit","tags":["Direct Debit"],"summary":"Charge direct debit mandate","description":"Execute a charge against an active direct debit mandate.\n\n**Checking debit status:** To check the status of a debit transaction, pass the `paymentReference` returned from this endpoint to [POST /api/customers/transaction/verify](#tag/payments/POST/api/customers/transaction/verify).\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"The amount to debit the customer (i.e 100000 = 1000)","example":100000},"reference":{"type":"string","description":"The unique reference for the transaction"},"narration":{"type":"string","description":"The narration for the transaction"},"mandateCode":{"type":"string","description":"The mandate code for the transaction"}},"required":["amount","mandateCode"]}}}},"responses":{"200":{"description":"Debit mandate accepted for processing","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Request successful."},"data":{"type":"object","properties":{"paymentReference":{"type":"string","example":"LNV-EHeRJ20260325"},"transactionReference":{"type":"string","example":"MNFY|95|20260325094342|023392"},"debitAmount":{"type":"number","example":100},"narration":{"type":"string","example":"Direct Debit charge from Toluwani Ibironke"},"mandateCode":{"type":"string","example":"MNDD|01KMJ24AAKR2FCZJYXYTCEZR13"},"responseMessage":{"type":"string","example":"Debit mandate request accepted for processing"},"transactionStatus":{"type":"string","example":"PENDING"},"incomeSplitConfig":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"description":"Bad request - Validation error or mandate not active","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Bad request."}}}}}},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":false},"message":{"type":"string","example":"API Key is missing"}}}}}},"422":{"description":"Unprocessable Entity - Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The given data was invalid."},"errors":{"type":"object"}}}}}},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/direct-debit/mandate-status":{"post":{"operationId":"getDirectDebitMandateStatus","tags":["Direct Debit"],"summary":"Get mandate status","description":"Retrieve the current status of a direct debit mandate.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"mandateReference":{"type":"string","description":"The mandate reference of the mandate to check","example":"1_abc123xyz456"}},"required":["mandateReference"]}}}},"responses":{"200":{"description":"Mandate status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Request successful."},"data":{"type":"object","properties":{"mandateCode":{"type":"string","example":"MNDD|01KMJ42RZE1VVZVAE72B68XVG2"},"mandateReference":{"type":"string","example":"LNV-MAND-65PVO20260325"},"startDate":{"type":"string","example":"2026-03-25T09:09:17.000+00:00"},"endDate":{"type":"string","example":"2027-03-25T09:09:17.000+00:00"},"mandateStatus":{"type":"string","example":"PENDING_AUTHORIZATION"},"mandateAmount":{"type":"number","example":100000},"autoRenew":{"type":"boolean","example":true},"customerPhoneNumber":{"type":"string","example":"08148509447"},"customerEmailAddress":{"type":"string","example":"joyelere@gmail.com"},"customerAddress":{"type":"string","example":"456 New Street, Lagos"},"customerName":{"type":"string","example":"Jeremiah Oyelere"},"customerAccountName":{"type":"string","example":"JEREMIAH AYOMIDE OYELERE"},"customerAccountNumber":{"type":"string","example":"2254930579"},"customerAccountBankCode":{"type":"string","example":"057"},"mandateDescription":{"type":"string","example":"Product payment"},"debitAmount":{"type":"number","nullable":true,"example":null},"authorizationMessage":{"type":"string","example":"Request Jeremiah Oyelere to kindly proceed with a token payment of N50.00 into account number 9880218357 with Paystack-Titan Bank."},"authorizationLink":{"type":"string","example":"https://paylink.monnify.com/mandate-auth/MNDD%7C01KMJ42RZE1VVZVAE72B68XVG2?accountNumber=9880218357&bankName=Paystack-Titan+Bank"},"responseMessage":{"type":"string","example":"Mandate is awaiting customer authorization"},"redirectUrl":{"type":"string","example":"https://yourcallback.com"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":false},"message":{"type":"string","example":"API Key is missing"}}}}}},"404":{"description":"Mandate not found"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/direct-debit/deactivate":{"post":{"operationId":"deactivateDirectDebit","tags":["Direct Debit"],"summary":"Deactivate direct debit mandate","description":"Cancel and deactivate an existing direct debit mandate.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"mandateCode":{"type":"string","description":"The mandate code of the mandate to deactivate","example":"md_123456"}},"required":["mandateCode"]}}}},"responses":{"200":{"description":"Mandate deactivated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Request successful."},"data":{"type":"object","properties":{"responseMessage":{"type":"string","example":"Mandate has been requested to be cancelled."},"mandateReference":{"type":"string","example":"LNV-MAND-n5JAu20260325"},"mandateCode":{"type":"string","example":"MNDD|01KMJ24AAKR2FCZJYXYTCEZR13"},"mandateStatus":{"type":"string","example":"ACTIVE"}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized - API key is missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":false},"message":{"type":"string","example":"API Key is missing"}}}}}},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/dva/create":{"post":{"operationId":"createReserveAccount","tags":["Payments"],"summary":"Create reserve account","description":"Create a dedicated virtual account (DVA) for receiving payments.","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"account_reference":{"type":"string","description":"The account reference of the customer","example":"RND123456789"},"account_name":{"type":"string","description":"The acoount name of the customer","example":"LennoxD"},"customer_name":{"type":"string","description":"The customer name of the customer","example":"Lennox Doe"},"customer_email":{"type":"string","description":"The customer email of the customer","example":"ravi@demo.com"},"bvn":{"type":"string","description":"The BVN of the customer","example":1234567890}},"required":["account_name","bvn","customer_email","customer_name"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/dva/reserved-account/details":{"post":{"operationId":"getReserveAccountDetails","tags":["Payments"],"summary":"Get reserve account details","description":"Retrieve details of a dedicated virtual account (DVA).","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"account_reference":{"type":"string","description":"The unique reference used when creating the reserved account","example":"RND123456789"}},"required":["account_reference"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Reserved account not found"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/dva/reserved-account/transactions":{"post":{"operationId":"getReserveAccountTransactions","tags":["Payments"],"summary":"Get reserve account transactions","description":"List all transactions on a dedicated virtual account (DVA).","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"account_reference":{"type":"string","description":"The unique reference used when creating the reserved account","example":"RND123456789"},"page":{"type":"integer","description":"The page of data you want returned (starts from 0)","example":0},"size":{"type":"integer","description":"The number of records you want returned in a page","example":10}},"required":["account_reference"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Reserved account not found"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/dva/reserved-account/delete":{"post":{"operationId":"deleteReserveAccount","tags":["Payments"],"summary":"Delete reserve account","description":"Deallocate and delete a dedicated virtual account (DVA).","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"account_reference":{"type":"string","description":"The unique reference used when creating the reserved account","example":"RND123456789"}},"required":["account_reference"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Reserved account not found"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/gsi/banks":{"get":{"operationId":"getGsiBanks","tags":["Payments"],"summary":"Get GSI supported banks","description":"Retrieve list of banks supported for GSI (Global Standard Initiative) operations.","responses":{"200":{"description":"Banks retrieved successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/gsi/customers":{"post":{"operationId":"createGsiCustomer","tags":["Payments"],"summary":"Create GSI customer","description":"Create a new customer for GSI (Global Standard Initiative) operations.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"bvn":{"type":"string","description":"Bank Verification Number (11 digits)","example":12345678901},"email":{"type":"string","description":"Customer email address","example":"customer@example.com"},"first_name":{"type":"string","description":"Customer first name","example":"John"},"last_name":{"type":"string","description":"Customer last name","example":"Doe"},"address":{"type":"string","description":"Customer address","example":"123 Main Street, Lagos"},"phone_number":{"type":"string","description":"Customer phone number","example":8012345678}},"required":["bvn","email","first_name","last_name","address","phone_number"]}}}},"responses":{"201":{"description":"Mono customer created successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]},"patch":{"operationId":"updateGsiCustomer","tags":["Payments"],"summary":"Update GSI customer","description":"Update an existing GSI customer's details.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"mono_customer_id":{"type":"string","description":"Mono customer ID","example":"cust_123456"},"bvn":{"type":"string","description":"Bank Verification Number (11 digits)","example":12345678901},"address":{"type":"string","description":"Customer address","example":"456 New Street, Lagos"},"phone_number":{"type":"string","description":"Customer phone number","example":8087654321}},"required":["mono_customer_id","bvn","address","phone_number"]}}}},"responses":{"200":{"description":"Mono customer updated successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/gsi/customers/{customerId}":{"get":{"operationId":"getGsiCustomer","tags":["Payments"],"summary":"Get GSI customer","description":"Retrieve a specific GSI customer's details by ID.","parameters":[{"in":"path","name":"customerId","required":true,"schema":{"type":"string"},"description":"Mono customer ID","example":"cust_123456"}],"responses":{"200":{"description":"Mono customer retrieved successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Customer not found"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/gsi/initiate":{"post":{"operationId":"initiateGsiMandate","tags":["Payments"],"summary":"Initiate GSI mandate","description":"Create a new GSI mandate for recurring payments.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"The total maximum amount (in Naira) that can be debited over the life of the mandate. Minimum is 200. For variable mandates, this is a spending cap; for fixed mandates, this is the recurring amount.\n","example":200},"description":{"type":"string","description":"Mandate description","example":"Monthly subscription payment"},"customerId":{"type":"string","description":"Mono customer ID","example":"cust_123456"},"redirectUrl":{"type":"string","description":"Redirect URL after mandate setup","example":"https://yourdomain.com/callback"},"reference":{"type":"string","description":"Reference must contain only letters and numbers (optional)","example":"LINK123456"},"meta":{"type":"object","description":"Additional metadata"}},"required":["amount","description","customerId"]}}}},"responses":{"200":{"description":"GSI Mandate initiated successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/v2/direct-debit/initiate":{"post":{"operationId":"initiateDirectDebitV2","tags":["Payments"],"summary":"Initiate direct debit mandate (V2)","description":"Create a new direct debit mandate using Mono integration.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Mandate amount (in Naira)","example":10000},"description":{"type":"string","description":"Mandate description","example":"Monthly subscription payment"},"customerId":{"type":"string","description":"Mono customer ID","example":"cust_123456"},"redirectUrl":{"type":"string","description":"Redirect URL after mandate setup","example":"https://yourdomain.com/callback"},"meta":{"type":"object","description":"Additional metadata"}},"required":["amount","mandate_type","description","userId","customerId"]}}}},"responses":{"200":{"description":"Mandate initiated successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/gsi/mandates/{mandateId}/debit":{"post":{"operationId":"debitGsiMandate","tags":["Payments"],"summary":"Debit GSI mandate","description":"Charge a customer's account using an active GSI mandate.","parameters":[{"in":"path","name":"mandateId","required":true,"schema":{"type":"string"},"description":"Mandate ID","example":"mandate_123456"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount to debit (in kobo) (i.e 100000 = 1000). Must be in integer","example":100000},"narration":{"type":"string","description":"Transaction narration","example":"Loan repayment"},"reference":{"type":"string","description":"Transaction reference","example":"RefID2025MANDATE"}},"required":["amount"]}}}},"responses":{"200":{"description":"Account debited successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/gsi/mandates/{accountId}/income":{"get":{"operationId":"getGsiMandateIncome","tags":["Payments"],"summary":"Get mandate income data","description":"Retrieve customer income information from mandate history.","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"},"description":"accountId ID","example":"accountId_123456"},{"in":"query","name":"period","schema":{"type":"integer","default":6},"description":"Period in months","example":6}],"responses":{"200":{"description":"Income data retrieved successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/gsi/account-linking":{"post":{"operationId":"initiateGsiAccountLinking","tags":["Payments"],"summary":"Initiate GSI account linking","description":"Link a user's bank account for GSI operations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"User email","example":"user@example.com"},"first_name":{"type":"string","description":"User first name","example":"John"},"last_name":{"type":"string","description":"User last name","example":"Doe"},"ref":{"type":"string","description":"Optional reference for linking request","example":"LINK_123456"},"redirect_url":{"type":"string","description":"Custom redirect URL","example":"https://yourdomain.com/success"},"meta":{"type":"object","description":"Additional metadata to include in the request","additionalProperties":true,"example":{"custom_field":"value","another_field":"another_value"}}},"required":["email","first_name","last_name"]}}}},"responses":{"200":{"description":"Account linking initiated successfully"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/banks":{"get":{"operationId":"getBanks","tags":["Payments"],"summary":"Get list of banks","description":"Retrieve the list of Nigerian banks for transfers and payments.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/name-resolution":{"get":{"operationId":"resolveAccountName","tags":["Payments"],"summary":"Resolve account name","description":"Verify and resolve a bank account number to get the account holder's name.","parameters":[{"in":"query","name":"account_number","required":true,"schema":{"type":"string"}},{"in":"query","name":"bank_code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/account-resolution":{"get":{"operationId":"resolveAccountDetails","tags":["Payments"],"summary":"Resolve account details with BVN","description":"Resolve a bank account number to get full account details including BVN, name, date of birth, phone, and residential address.","parameters":[{"in":"query","name":"account_number","required":true,"schema":{"type":"string"}},{"in":"query","name":"bank_code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/nigerian-states":{"get":{"operationId":"getNigerianStates","tags":["Customer"],"summary":"Get Nigerian states","description":"Retrieve the list of Nigerian states (requires live API key).","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/nigerian-lgas":{"get":{"operationId":"getNigerianLgas","tags":["Customer"],"summary":"Get Nigerian LGAs","description":"Retrieve the list of Local Government Areas for a state (requires live API key).","parameters":[{"in":"query","name":"state_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills":{"get":{"operationId":"getBillers","tags":["Payments"],"summary":"Get billers","description":"Retrieve all available billers for bill payments.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/categories":{"get":{"operationId":"getBillerCategories","tags":["Payments"],"summary":"Get biller categories","description":"Retrieve biller categories (airtime, data, etc.).","parameters":[{"name":"category","in":"query","description":"Category type (default is airtime)","schema":{"type":"string","example":"airtime"}},{"name":"isBouquet","in":"query","description":"Is bouquet (default is No)","schema":{"type":"string","example":"No"}}],"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/internet-categories":{"get":{"operationId":"getInternetBillerCategories","tags":["Payments"],"summary":"Get internet biller categories","description":"Retrieve available internet data providers and plans.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/tv-categories":{"get":{"operationId":"getTvBillerCategories","tags":["Payments"],"summary":"Get TV biller categories","description":"Retrieve available TV subscription providers and plans.","responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/bouquets":{"get":{"operationId":"getBillerBouquets","tags":["Payments"],"summary":"Get bouquets for biller","description":"Retrieve available bouquets/plans for a specific biller.","parameters":[{"name":"category","in":"query","description":"Category type","schema":{"type":"string","example":"data"}},{"name":"biller_id","in":"query","description":"Biller ID","schema":{"type":"string","example":123}}],"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/validate/phone":{"post":{"operationId":"validateBillPhone","tags":["Payments"],"summary":"Validate phone for bills","description":"Validate a phone number before purchasing airtime or data.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"Phone number to validate","example":8012345678}},"required":["phone_number"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/validate/bet":{"post":{"operationId":"validateBetId","tags":["Payments"],"summary":"Validate bet ID","description":"Validate a betting account ID before funding.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"BET9JA"},"customer_id":{"type":"string","description":"Customer ID","example":123456789}},"required":["biller_id","customer_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/validate/disco":{"post":{"operationId":"validateDiscoCustomer","tags":["Payments"],"summary":"Validate electricity meter","description":"Validate an electricity meter number before purchasing tokens.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"IKEDC"},"customer_id":{"type":"string","description":"Customer ID/Meter number","example":123456789}},"required":["biller_id","customer_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/validate/tv":{"post":{"operationId":"validateTvSubscription","tags":["Payments"],"summary":"Validate TV smartcard","description":"Validate a TV smartcard number before subscription payment.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"DSTV"},"customer_id":{"type":"string","description":"Customer ID/Smart card number","example":123456789}},"required":["biller_id","customer_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/validate/internet":{"post":{"operationId":"validateInternetSubscription","tags":["Payments"],"summary":"Validate internet customer","description":"Validate an internet customer ID before subscription payment.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"SMILE"},"customer_id":{"type":"string","description":"Customer ID","example":123456789}},"required":["biller_id","customer_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/airtime":{"post":{"operationId":"purchaseAirtime","tags":["Payments"],"summary":"Purchase airtime","description":"Purchase airtime for a mobile phone number.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"Phone number","example":8012345678},"biller_code":{"type":"string","description":"Biller code","example":"MTN"},"amount":{"type":"number","description":"Amount in naira","example":100},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"}},"required":["phone_number","biller_code","amount","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/data":{"post":{"operationId":"purchaseData","tags":["Payments"],"summary":"Purchase data bundle","description":"Purchase a mobile data bundle.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"Phone number","example":8012345678},"biller_code":{"type":"string","description":"Biller code","example":"MTN"},"amount":{"type":"number","description":"Amount in naira","example":500},"bouquet_code":{"type":"string","description":"Data plan code","example":"1GB_30DAYS"},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"}},"required":["phone_number","biller_code","amount","bouquet_code","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/bet":{"post":{"operationId":"fundBettingAccount","tags":["Payments"],"summary":"Fund betting account","description":"Fund a betting wallet/account.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"BET9JA"},"customer_id":{"type":"string","description":"Customer ID","example":123456789},"amount":{"type":"number","description":"Amount in naira","example":1000},"customer_name":{"type":"string","description":"Customer name","example":"John Doe"},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"}},"required":["biller_id","customer_id","amount","customer_name","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/disco":{"post":{"operationId":"purchaseElectricity","tags":["Payments"],"summary":"Purchase electricity","description":"Purchase electricity tokens for a prepaid meter.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"IKEDC"},"customer_id":{"type":"string","description":"Customer ID/Meter number","example":123456789},"amount":{"type":"number","description":"Amount in naira","example":5000},"customer_name":{"type":"string","description":"Customer name","example":"John Doe"},"customer_address":{"type":"string","description":"Customer address","example":"123 Main Street"},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"}},"required":["biller_id","customer_id","amount","customer_name","customer_address","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/tv":{"post":{"operationId":"purchaseTvSubscription","tags":["Payments"],"summary":"Purchase TV subscription","description":"Pay for a TV subscription (DSTV, GOtv, etc.).","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"DSTV"},"customer_id":{"type":"string","description":"Customer ID/Smart card number","example":123456789},"amount":{"type":"number","description":"Amount in naira","example":4000},"customer_name":{"type":"string","description":"Customer name","example":"John Doe"},"bouquet_code":{"type":"string","description":"Bouquet code","example":"COMPACT"},"customer_number":{"type":"string","description":"Customer phone number","example":8012345678},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"},"addon_code":{"type":"string","description":"Addon code (optional)","example":""}},"required":["biller_id","customer_id","amount","customer_name","bouquet_code","customer_number","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/tv-renewal":{"post":{"operationId":"renewTvSubscription","tags":["Payments"],"summary":"Renew TV subscription","description":"Renew an existing TV subscription.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"DSTV"},"customer_id":{"type":"string","description":"Customer ID/Smart card number","example":123456789},"amount":{"type":"number","description":"Amount in naira","example":4000},"customer_name":{"type":"string","description":"Customer name","example":"John Doe"},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"}},"required":["biller_id","customer_id","amount","customer_name","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/showmax":{"post":{"operationId":"purchaseShowmax","tags":["Payments"],"summary":"Purchase Showmax subscription","description":"Purchase a Showmax streaming subscription.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID (default is SHOWMAX)","example":"SHOWMAX"},"customer_id":{"type":"string","description":"Customer ID","example":123456789},"amount":{"type":"number","description":"Amount in naira","example":2900},"bouquet_code":{"type":"string","description":"Showmax package code","example":"SHOWMAX_MOBILE"},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"}},"required":["customer_id","amount","bouquet_code","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/internet":{"post":{"operationId":"purchaseInternet","tags":["Payments"],"summary":"Purchase internet subscription","description":"Purchase an internet data subscription.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"SMILE"},"customer_id":{"type":"string","description":"Customer ID","example":123456789},"amount":{"type":"number","description":"Amount in naira","example":2000},"customer_name":{"type":"string","description":"Customer name","example":"John Doe"},"customer_address":{"type":"string","description":"Customer address","example":"123 Main Street"},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"},"bouquet_code":{"type":"string","description":"Internet package code (optional)","example":"1GB_MONTHLY"}},"required":["biller_id","customer_id","amount","customer_name","customer_address","request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/purchase/education":{"post":{"operationId":"purchaseEducation","tags":["Payments"],"summary":"Purchase education pin","description":"Purchase education-related products (WAEC, NECO, JAMB pins, etc.).","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"biller_id":{"type":"string","description":"Biller ID","example":"WAEC"},"amount":{"type":"number","description":"Amount in naira","example":2500},"request_id":{"type":"string","description":"Unique request ID","example":"req_123456789"},"bouquet_code":{"type":"string","description":"Education package code","example":"WAEC_PIN"}},"required":["biller_id","amount","request_id","bouquet_code"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/requery":{"post":{"operationId":"requeryBillTransaction","tags":["Payments"],"summary":"Requery bill transaction","description":"Check the status of a previously initiated bill payment.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"request_id":{"type":"string","description":"Request ID to requery","example":"req_123456789"}},"required":["request_id"]}}}},"responses":{"200":{"description":"Request successful"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"apiKeyAuth":[]}]}},"/api/customers/bills/v2/categories":{"get":{"operationId":"getBillerCategoriesV2","tags":["Payments"],"summary":"Get biller categories (V2)","description":"Retrieves all available biller categories from Monnify, such as airtime, cable TV, data services, etc.","responses":{"200":{"description":"A list of biller categories","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Biller categories retrieved successfully"},"data":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"AIRTIME"},"name":{"type":"string","example":"AIRTIME"}}}},"totalElements":{"type":"integer","example":8},"size":{"type":"integer","example":8},"number":{"type":"integer","example":0},"empty":{"type":"boolean","example":false},"nextPage":{"type":"integer","nullable":true,"example":null}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]},{"apiKeyAuth":[]}]}},"/api/customers/bills/v2/billers":{"get":{"operationId":"getBillersV2","tags":["Payments"],"summary":"Get all billers (V2)","description":"Retrieves all billers with optional category filter.","parameters":[{"name":"category_code","in":"query","description":"Optional category code to filter billers (e.g., CABLE_TV, AIRTIME, DATA)","schema":{"type":"string","example":"CABLE_TV"}}],"responses":{"200":{"description":"A list of billers","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Billers retrieved successfully"},"data":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"biller-dstv"},"name":{"type":"string","example":"DSTV"},"categories":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"CABLE_TV"},"name":{"type":"string","example":"CABLE_TV"}}}}}}},"totalElements":{"type":"integer","example":4},"size":{"type":"integer","example":20},"number":{"type":"integer","example":0},"empty":{"type":"boolean","example":false},"nextPage":{"type":"integer","nullable":true,"example":null}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]},{"apiKeyAuth":[]}]}},"/api/customers/bills/v2/products":{"get":{"tags":["Payments"],"summary":"Get biller products","description":"Retrieves all products available for a specific biller.","parameters":[{"name":"biller_code","in":"query","required":true,"description":"The code of the biller to retrieve products for","schema":{"type":"string","example":"MTN"}}],"responses":{"200":{"description":"A list of biller products","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Biller products retrieved successfully"},"data":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"11"},"name":{"type":"string","example":"MTN Mobile Top up"},"price":{"type":"number","nullable":true,"example":null},"priceType":{"type":"string","example":"OPEN"},"minAmount":{"type":"number","nullable":true,"example":50},"maxAmount":{"type":"number","nullable":true,"example":50000}}}},"totalElements":{"type":"integer","example":4},"size":{"type":"integer","example":20},"number":{"type":"integer","example":0},"empty":{"type":"boolean","example":false},"nextPage":{"type":"integer","nullable":true,"example":null}}}}}}}},"400":{"description":"Bad request - biller_code is required"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]},{"apiKeyAuth":[]}]}},"/api/customers/bills/v2/validate-customer":{"post":{"tags":["Payments"],"summary":"Validate customer","description":"Validates a customer's details (like a meter number or phone number) for a specific product before initiating a transaction.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"product_code":{"type":"string","description":"The unique code for the product","example":"11"},"customer_id":{"type":"string","description":"The customer's identifier to validate (e.g., phone number, meter number)","example":"08012345678"}},"required":["product_code","customer_id"]}}}},"responses":{"200":{"description":"Successful customer validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Customer validated successfully"},"data":{"type":"object","properties":{"priceType":{"type":"string","example":"OPEN"},"customerName":{"type":"string","example":"Test Customer 5678"},"vendInstruction":{"type":"object","properties":{"requireValidationRef":{"type":"boolean","example":false}}}}}}}}}},"400":{"description":"Bad request - invalid customer ID or missing parameters"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]},{"apiKeyAuth":[]}]}},"/api/customers/bills/v2/requery":{"get":{"tags":["Payments"],"summary":"Requery transaction","description":"Checks and retrieves the final status of a previously initiated transaction using its unique reference.","parameters":[{"name":"reference","in":"query","required":true,"description":"The unique reference of the transaction to requery","schema":{"type":"string","example":"REF-ABC12345"}}],"responses":{"200":{"description":"Successful requery with transaction details","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Transaction requeried successfully"},"data":{"type":"object","properties":{"vendReference":{"type":"string","example":"REF-ABC12345"},"transactionReference":{"type":"string","example":"MFBP1234567890test"},"vendStatus":{"type":"string","example":"SUCCESS"},"description":{"type":"string","example":"Okay, purchase was successfully created."},"vendAmount":{"type":"number","example":1000},"payableAmount":{"type":"number","example":1010},"commission":{"type":"number","example":10},"customerId":{"type":"string","example":"08012345678"},"productCode":{"type":"string","example":"11"},"productName":{"type":"string","example":"Test Product"},"billerCode":{"type":"string","example":"TEST"},"billerName":{"type":"string","example":"Test Biller"}}}}}}}},"400":{"description":"Bad request - reference is required"},"401":{"description":"Unauthorized"},"404":{"description":"Transaction not found for the given reference"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]},{"apiKeyAuth":[]}]}},"/api/customers/bills/v2/vend":{"post":{"tags":["Payments"],"summary":"Vend/Purchase","description":"Initiates a payment or vending transaction for a specific product, such as airtime top-up or a utility bill payment.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"product_code":{"type":"string","description":"The unique code for the product being purchased","example":"11"},"customer_id":{"type":"string","description":"The customer's identifier (e.g., phone number, meter number)","example":"08012345678"},"amount":{"type":"number","description":"The amount for the transaction","example":1000},"reference":{"type":"string","description":"A unique reference for this transaction","example":"REF-UNIQUE-12345"},"validation_reference":{"type":"string","description":"A reference obtained from the customer validation endpoint, if required","example":"VAL-REF-12345"},"email":{"type":"string","format":"email","description":"The customer's email address for notifications","example":"customer@example.com"},"phone_number":{"type":"string","description":"The customer's phone number","example":"08012345678"}},"required":["product_code","customer_id","amount","reference"]}}}},"responses":{"200":{"description":"Successful vending transaction","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Vend transaction successful"},"data":{"type":"object","properties":{"vendReference":{"type":"string","example":"REF-ABC12345"},"transactionReference":{"type":"string","example":"MFBP1234567890test"},"vendStatus":{"type":"string","example":"SUCCESS"},"description":{"type":"string","example":"Okay, purchase was successfully created."},"vendAmount":{"type":"number","example":1000},"payableAmount":{"type":"number","example":1010},"commission":{"type":"number","example":10},"customerId":{"type":"string","example":"08012345678"},"productCode":{"type":"string","example":"11"},"productName":{"type":"string","example":"Test Product"},"billerCode":{"type":"string","example":"TEST"},"billerName":{"type":"string","example":"Test Biller"}}}}}}}},"400":{"description":"Bad request - required field missing"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"},"default":{"description":"Unexpected error"}},"security":[{"bearerTokenAuth":[]},{"apiKeyAuth":[]}]}}},"components":{"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Request successful"},"data":{"type":"object"}},"required":["success","message"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"An error occurred"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["success","message"]},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"per_page":{"type":"integer","example":20},"total":{"type":"integer","example":100},"last_page":{"type":"integer","example":5},"from":{"type":"integer","example":1},"to":{"type":"integer","example":20}}},"PaginatedResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"Customer":{"type":"object","properties":{"id":{"type":"integer","example":1},"first_name":{"type":"string","example":"John"},"last_name":{"type":"string","example":"Doe"},"email":{"type":"string","format":"email","example":"john.doe@example.com"},"phone_number":{"type":"string","example":"08012345678"},"email_verified_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"LoginRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"User's email address","example":"user@example.com"},"password":{"type":"string","format":"password","description":"User's password","example":"password123"}},"required":["email","password"]},"LoginResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Login successful"},"data":{"type":"object","properties":{"token":{"type":"string","description":"Bearer token for authentication","example":"1|abc123xyz..."},"user":{"$ref":"#/components/schemas/Customer"}}}}},"VerificationResult":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"entity":{"type":"object","description":"Verification result data"}}}}},"Transaction":{"type":"object","properties":{"id":{"type":"integer"},"reference":{"type":"string","example":"TXN_abc123"},"type":{"type":"string","example":"nin_verification"},"amount":{"type":"number","format":"float","example":100},"status":{"type":"string","enum":["pending","successful","failed"]},"created_at":{"type":"string","format":"date-time"}}}},"parameters":{"PageParam":{"name":"page","in":"query","description":"Current page number","schema":{"type":"integer","default":1,"minimum":1},"example":1},"PerPageParam":{"name":"per_page","in":"query","description":"Number of items per page","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"example":20},"FromDateParam":{"name":"from_date","in":"query","description":"Start date for filtering (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"example":"2024-01-01"},"ToDateParam":{"name":"to_date","in":"query","description":"End date for filtering (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"example":"2024-12-31"},"SearchQueryParam":{"name":"q","in":"query","description":"Search query string","schema":{"type":"string"},"example":"John"},"CustomerIdParam":{"name":"customer","in":"path","description":"The unique identifier of the customer","required":true,"schema":{"type":"integer"},"example":1}},"responses":{"BadRequest":{"description":"Bad request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Validation failed","errors":{"email":["The email field is required."]}}}}},"Unauthorized":{"description":"Unauthorized - Authentication required or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Unauthenticated"}}}},"Forbidden":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"You do not have permission to perform this action"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Resource not found"}}}},"InsufficientFunds":{"description":"Insufficient wallet balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Insufficient funds. Please top up your wallet."}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"An unexpected error occurred. Please try again later."}}}}},"securitySchemes":{"bearerTokenAuth":{"type":"http","description":"Bearer token authentication for session-based access.\nObtain a token via the login endpoint and include it in the Authorization header.\n","scheme":"bearer","bearerFormat":"JWT"},"apiKeyAuth":{"type":"apiKey","description":"API key authentication for programmatic access.\nGenerate an API key from your dashboard and include it in the api-key header.\n","in":"header","name":"api-key"}}},"x-webhooks":{"mandatePendingAuthorization":{"post":{"tags":["Webhook Events"],"summary":"Mandate Pending Authorization","description":"Sent when a direct debit mandate is initialized and awaiting customer authorization.\nThe customer must complete the authorization (including the ₦50 bank fee) before the mandate becomes active.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventType":{"type":"string","example":"MANDATE_UPDATE"},"eventData":{"type":"object","properties":{"externalMandateReference":{"type":"string","example":"LNV-MAND-yokAO260324"},"mandateCode":{"type":"string","example":"MNDD|01KMGVWXA5KDDV154AKJ0BR"},"mandateStatus":{"type":"string","example":"PENDING_AUTHORIZATION"},"mandateAmount":{"type":"number","example":100000},"mandateDescription":{"type":"string","example":"Product payment"},"autoRenew":{"type":"boolean","example":true},"customerName":{"type":"string","example":"Jeremiah Oyelere"},"customerEmailAddress":{"type":"string","example":"test@gmail.com"},"customerPhoneNumber":{"type":"string","example":"08148501147"},"customerAccountName":{"type":"string","example":"JEREMIAH OYELERE"},"customerAccountNumber":{"type":"string","example":"2202541196"},"customerAccountBankCode":{"type":"string","example":"033"},"customerAddress":{"type":"string","example":"2 mojisola street"},"contractCode":{"type":"string","example":"892560411253"},"startDate":{"type":"string","example":"2026-03-24 22:27:01.0"},"endDate":{"type":"string","example":"2027-03-24 22:27:01.0"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"mandateActive":{"post":{"tags":["Webhook Events"],"summary":"Mandate Activated","description":"Sent after the customer completes authorization and pays the ₦50 bank activation fee.\nThe mandate is now active and ready to be charged.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventType":{"type":"string","example":"MANDATE_UPDATE"},"eventData":{"type":"object","properties":{"externalMandateReference":{"type":"string","example":"LNV-MAND-n5J20260325"},"mandateCode":{"type":"string","example":"MNDD|01KMJ24AAKRZJYXYTCEZR13"},"mandateStatus":{"type":"string","example":"ACTIVE"},"mandateAmount":{"type":"number","example":100000},"mandateDescription":{"type":"string","example":"Product payment"},"autoRenew":{"type":"boolean","example":true},"customerName":{"type":"string","example":"Toluwani Ibironke"},"customerEmailAddress":{"type":"string","example":"test@gmail.com"},"customerPhoneNumber":{"type":"string","example":"08113862827"},"customerAccountName":{"type":"string","example":"IBIRONKE TOLUWANIMI"},"customerAccountNumber":{"type":"string","example":"0251062433"},"customerAccountBankCode":{"type":"string","example":"058"},"customerAddress":{"type":"string","example":"456 New Street, Lagos"},"contractCode":{"type":"string","example":"892560411253"},"startDate":{"type":"string","example":"2026-03-25 09:35:09.0"},"endDate":{"type":"string","example":"2027-03-25 09:35:09.0"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"mandateCancelled":{"post":{"tags":["Webhook Events"],"summary":"Mandate Cancelled","description":"Sent when a direct debit mandate is cancelled, either by the customer or by the merchant via the deactivate endpoint.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventType":{"type":"string","example":"MANDATE_UPDATE"},"eventData":{"type":"object","properties":{"externalMandateReference":{"type":"string","example":"LNV-MAND-E2pr0660209"},"mandateCode":{"type":"string","example":"MNDD|01KH0VNVKVNXSR7S00HZRFZ4"},"mandateStatus":{"type":"string","example":"CANCELLED"},"mandateAmount":{"type":"number","example":100000},"mandateDescription":{"type":"string","example":"Loan repayment"},"autoRenew":{"type":"boolean","example":true},"customerName":{"type":"string","example":"Jeremiah Customer"},"customerEmailAddress":{"type":"string","example":"test@gmail.com"},"customerPhoneNumber":{"type":"string","example":"08148519447"},"customerAccountName":{"type":"string","example":"JEREMIAH OYELERE"},"customerAccountNumber":{"type":"string","example":"2202541296"},"customerAccountBankCode":{"type":"string","example":"033"},"customerAddress":{"type":"string","example":"2 Mojisola street"},"contractCode":{"type":"string","example":"892560412253"},"startDate":{"type":"string","example":"2026-02-09 10:28:15.0"},"endDate":{"type":"string","example":"2027-02-09 10:28:15.0"}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"directDebitCharged":{"post":{"tags":["Webhook Events"],"summary":"Direct Debit Charge Successful","description":"Sent when a direct debit charge is successfully processed against an active mandate.\nThe `paymentMethod` will be `DIRECT_DEBIT` and `paymentStatus` will be `PAID`.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventType":{"type":"string","example":"SUCCESSFUL_TRANSACTION"},"eventData":{"type":"object","properties":{"transactionReference":{"type":"string","example":"MNFY|68|202602095952|059409"},"paymentReference":{"type":"string","example":"LNV-22yHY2260209"},"paidOn":{"type":"string","example":"2026-02-09 10:59:56.594"},"paymentDescription":{"type":"string","example":"Direct Debit charge from Jeremiah Customer"},"amountPaid":{"type":"number","example":50},"totalPayable":{"type":"number","example":50},"settlementAmount":{"type":"string","example":"49.57"},"paymentMethod":{"type":"string","example":"DIRECT_DEBIT"},"paymentStatus":{"type":"string","example":"PAID"},"currency":{"type":"string","example":"NGN"},"paymentScope":{"type":"string","example":"LOCAL"},"customer":{"type":"object","properties":{"name":{"type":"string","example":"JEREMIAH OYELERE"},"email":{"type":"string","example":"test@gmail.com"}}},"product":{"type":"object","properties":{"reference":{"type":"string","example":"LNV-22yHY20260209"},"type":{"type":"string","example":"API_NOTIFICATION"}}}}}}}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}}}