Mobile Number Verification

Mobile Number Verification

Mobile number verification allows you to validate mobile money account details before initiating payout transactions. This helps reduce failed payouts, improves the disbursement experience, and provides recipient account holder information when available.

Introduction

When processing mobile money payouts, it’s crucial to verify that the recipient’s mobile number is valid and registered with the mobile money provider. The mobile number verification API enables you to check if a mobile number is registered for mobile money services and retrieve the account holder’s name when available.

This verification step can be integrated into your payout disbursement flow to:

• Reduce payout failures due to invalid or unregistered numbers
• Display the recipient’s account holder name for confirmation before disbursement
• Improve the overall user experience by catching errors early
• Minimize transaction fees wasted on failed payout attempts

Pre-requisites

Before using mobile number verification through PayOS, ensure you meet the following requirements:

• PayOS Integration:
  You have integrated with PayOS and have access to the API.

• Authentication:
  You have valid API credentials and can authenticate your requests using Bearer tokens.

• Payment Processor Configuration:
  Your merchant account has mobile money payment processors configured that support verification. Currently available for M-Pesa in Kenya. Contact PayOS support for availability in other markets.

• Merchant ID:
  You have your merchant ID available for API requests.

API Endpoint

The verification endpoint accepts a mobile number and country code, and returns whether the number is verified along with optional account information:

Endpoint: POST /api/v1/verification/mobile

Authentication: Bearer Token (required)

Request Format

To verify a mobile number, make a POST request with the following parameters:

1
{
2
  "phoneNumber": "254712345678",
3
  "country": "KEN",
4
  "merchantId": "12345678-1234-5678-1234-567812345678"
5
}

Request Parameters

Response Format

The API returns a response indicating whether the number was verified and may include additional account information:

1
{
2
  "verified": true,
3
  "accountName": "John Doe",
4
  "status": "ACTIVE"
5
}

Response Fields

Example Usage

Here’s a complete example of verifying a mobile number:

$
curl -X POST https://api.payos.money/api/v1/verification/mobile \
>
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "phoneNumber": "254712345678",
>
    "country": "KEN",
>
    "merchantId": "12345678-1234-5678-1234-567812345678"
>
  }'

Success Response (200 OK):

1
{
2
  "verified": true,
3
  "accountName": "Jane Smith",
4
  "status": "ACTIVE"
5
}

Unverified Number Response (200 OK):

1
{
2
  "verified": false
3
}

Error Response (422 Unprocessable Entity):

1
{
2
  "message": "Invalid request format: phoneNumber is required",
3
  "error": "Unprocessable Entity",
4
  "statusCode": "422"
5
}

Error Response (500 Internal Server Error):

1
{
2
  "message": "Internal server error",
3
  "error": "Internal Server Error",
4
  "statusCode": "500"
5
}

Integration Workflow

Here’s a recommended workflow for integrating mobile number verification into your payout disbursement process:

1. Collect Recipient Information:
   Obtain the recipient’s mobile number and country code from your payout request.

2. Verify Before Payout:
   Call the verification API before initiating the payout to ensure the number is valid and registered.

3. Display Confirmation:
   If verified, show the account holder’s name for confirmation before processing the disbursement.
   Example: “Send payout to Jane Smith at 254712345678?”

4. Store Verification Results:
   Cache the verification result and account name for future reference and audit trails.

5. Handle Verification Results:

   • If verified: Proceed with payout initiation
   • If not verified: Notify the requester and request updated recipient information

6. Initiate Payout:
   Process the payout transaction to the verified mobile money account.

Best Practices

To optimize your integration and minimize issues:

• Verify Before Processing:
  Verify mobile numbers before initiating payout transactions to catch errors early in the disbursement process.

• Cache Results:
  Consider caching verification results for a short period to avoid redundant API calls for the same recipient number.

• Handle Errors Gracefully:
  Account for cases where the verification service may be temporarily unavailable. Have a fallback process to handle unverified payouts with appropriate warnings.

• Display Account Names:
  When available, always show the account holder’s name for confirmation before processing the payout. This helps prevent incorrect disbursements and builds trust.

• Format Phone Numbers:
  Accept phone numbers in various formats but normalize them before sending to the API. Include country codes and remove spaces or special characters.

• Audit Trail:
  Log verification results along with payout transactions for reconciliation and compliance purposes.

Supported Markets

Mobile number verification is currently available for:

• Kenya (KEN): M-Pesa

Support for additional markets and mobile money providers is available upon request. Contact PayOS support to discuss verification capabilities for your specific requirements and payment processor configuration.

Error Handling

The verification API may return various error responses. Here’s how to handle common scenarios:

Validation Errors (422)

These occur when the request format is invalid:

• Missing required fields
• Invalid country code format
• Malformed phone number

Action: Validate input on the client side before making API calls.

Authentication Errors (401)

These occur when:

• The Bearer token is missing or invalid
• The token has expired

Action: Refresh your authentication token and retry the request.

Internal Server Errors (500)

These may occur when:

• The verification service is temporarily unavailable
• There’s an issue communicating with the payment processor

Action: Implement retry logic with exponential backoff. If the issue persists, allow users to proceed with appropriate warnings or contact support.

Rate Limiting

The verification API is subject to PayOS’s standard rate limiting policies. Excessive requests may result in HTTP 429 (Too Many Requests) responses.

• Recommendation: Cache verification results and avoid verifying the same number multiple times in quick succession.
• Rate Limit: Refer to the Rate Limiting guide for current limits and best practices.

Testing

When testing mobile number verification in the sandbox environment:

• Use your test merchant configuration with sandbox payment processors
• Test with various phone number formats to ensure proper handling
• Verify error handling for invalid inputs and authentication failures

Contact PayOS support for test credentials and sample numbers for your specific market and payment processor configuration.

Security Considerations

When implementing mobile number verification:

• Protect API Credentials:
  Never expose your Bearer tokens or API keys in client-side code.

• Validate Input:
  Always validate and sanitize phone numbers on both client and server side.

• Secure Storage:
  If caching verification results, ensure they’re stored securely and comply with data protection regulations.

• PII Handling:
  Account names are personally identifiable information (PII). Handle them according to GDPR, POPIA, and other applicable data protection laws.

Additional Resources

For more information about PayOS APIs and mobile money payouts:

• Authentication
  Learn how to obtain and manage Bearer tokens for API authentication.

• M-Pesa Integration
  Comprehensive guide for integrating M-Pesa mobile money.

• Error Handling
  Best practices for handling API errors and edge cases.

• Rate Limiting
  Understanding and working with API rate limits.

By integrating mobile number verification, you can significantly improve the success rate of your mobile money payouts and reduce failed disbursements.