Lookup Customer Banks

Retrieve a list of banks associated with a customer's phone number.

Endpoint

GET /api/v1/payment-providers/banks/lookup/:phone_number

Authentication

Requires a valid Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Path Parameters

Parameter	Type	Required	Description
phone_number	string	Yes	Customer's phone number in E.164 format (e.g., +233241234567)

Request

Phone Number Format

Phone numbers must be in E.164 international format:

• Include country code with + prefix
• No spaces, hyphens, or parentheses
• Example: +233241234567 (Ghana)

Example Request

curl --request GET \
  --url https://api.fluid-network.com/api/v1/payment-providers/banks/lookup/%2B233241234567 \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json'

Response

Success Response

Status Code: 200 OK

{
  "success": true,
  "phone_number": "+233241234567",
  "customer": "John Doe",
  "data": [
    {
      "name": "Example Bank Ghana",
      "identifier": "EXB",
      "country_code": "GH"
    },
    {
      "name": "Demo Bank Ghana",
      "identifier": "DEM",
      "country_code": "GH"
    }
  ]
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
phone_number	string	The queried phone number in E.164 format
customer	string	Customer name associated with the phone number
data	array	Array of bank objects linked to this customer
data[].name	string	Full name of the bank
data[].identifier	string	FLUID Network bank identifier
data[].country_code	string	ISO 3166-1 alpha-2 country code

Error Responses

Account Not Found

Status Code: 404 Not Found

{
  "success": false,
  "error": {
    "code": 1404,
    "message": "Account not found",
    "category": "accounts"
  }
}

Common Causes:

• Phone number not registered with any bank
• Invalid phone number format
• Customer has no active bank accounts

Bad Request

Status Code: 400 Bad Request

{
  "success": false,
  "error": {
    "code": 1400,
    "message": "Bad request",
    "category": "request"
  }
}

Common Causes:

• Invalid phone number format (missing +, wrong length)
• Malformed request

Unauthorized

Status Code: 401 Unauthorized

{
  "success": false,
  "error": {
    "code": 1401,
    "message": "Unauthorized",
    "category": "authentication"
  }
}

Usage Notes

Phone Number Encoding

URL Encoding Required: Always URL-encode phone numbers when including them in the URL path. The + symbol must be encoded as %2B.

Customer Privacy

• Customer names are returned for verification purposes
• Ensure compliance with data protection regulations in your jurisdiction
• Store customer data securely according to PCI-DSS and local privacy laws

Bank Selection

When a customer has multiple banks:

• Present all available options to the customer
• Let the customer choose their preferred bank
• Consider implementing bank preference caching for returning customers

Use Cases

1. Pre-payment Validation: Verify customer has an active bank account before initiating payment
2. Bank Selection UI: Display available banks for customer to choose from
3. Account Verification: Confirm phone number is linked to expected customer name

Rate Limits

• Production: 200 requests per minute
• Sandbox: 60 requests per minute

Testing in Sandbox: Use test phone number +233241234567 in sandbox environment. This returns mock data with multiple banks for testing.

Integration Example

When integrating customer bank lookup into your payment flow:

1. Lookup customer banks using their phone number
2. Display available bank options to the customer
3. Let customer select their preferred bank
4. Proceed with charge using the selected bank identifier

Implementation Steps

1. Call the lookup endpoint with customer's phone number (URL-encoded)
2. Handle the response and extract the list of available banks
3. Present bank options to customer in your UI
4. Store selected bank identifier for the charge request
5. Proceed with charge creation using the selected bank

Next Steps

• Create a debit request using the bank identifier
• List all available banks
• Handle webhook notifications for transaction status updates