Skip to main content

Agent Send Money Flow

📋 Overview​

Complete workflow for processing agent send money transactions in the GafaPay system. This flow allows agents to send money on behalf of non-registered users, involving wallet transfers and cash transfer request tracking through a comprehensive API integration process.

🔄 Workflow Steps​

Step 1: Get Agent Wallet Balance​

  • Follow the Common Transaction Flow to get agent wallet balance
  • Call the Get User Wallet API to retrieve agent's available balance
  • Validate that agent has sufficient balance for the transaction
  • Display wallet balance to the agent for verification

Step 2: Enter Sender and Receiver Details​

  • Agent enters sender's (non-registered user) information:
    • Phone number with dial code
    • First name and last name
  • Agent enters receiver's (non-registered user) information:
    • Phone number with dial code
    • First name and last name

Step 3: Enter Amount​

  • Agent enters the transfer amount
  • System validates the amount format and range
  • Amount should be a positive numeric value
  • Verify agent has sufficient balance for transaction amount

Step 4: Check NRTA Product Availability​

  • System checks if the NRTA (Non-Register to Non-Register Transfer via Agent) product is allowed for the agent
  • Call the Get Agent Profile Products API and pass the agent's agent_profile_id
  • Search for product with product_code: "NRTA" in the returned products list
  • If no NRTA product found → Product is not allowed for this agent, show error message and stop the process
  • If NRTA product exists → Continue with the transaction flow

Step 5: Prepare and Execute Wallet Transfer API​

  • Prepare wallet transfer request with NRTA product code
  • In the debit_user_info, pass the logged-in agent's details
  • In the credit_user_info, pass the company admin user details
  • Call the Wallet Transfer API with the following payload structure:
{
    "charges_info": null,
    "note": null,
    "txn_amount": 100,
    "txn_code": "NRTA",
    "payment_mode": 3,
    "company_admin_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 1,
        "credit_account_type_id": "640b793d04e2428dbf19ab10399f4edb",
        "username": "Mouhamad Amine"
    },
    "txn_device_info": {
        "device_name": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
        "os_name": "MacIntel",
        "location": {},
        "host_name": "localhost",
        "url": "http://localhost:9000"
    },
    "debit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "debit_type": 1,
        "debit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "debit_account_type": 5,
        "debit_account_type_id": "dd4403366e944eb4b302a69f684bc52e",
        "username": "Md Siraj"
    },
    "credit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 1,
        "credit_account_type_id": "640b793d04e2428dbf19ab10399f4edb",
        "username": "Gafa Pay"
    }
}

Field Descriptions:

  • txn_code: "NRTA" (Non-Register to Non-Register Transfer via Agent)
  • payment_mode: 3 (Wallet payment)
  • debit_user_info: Contains logged-in agent's details
    • debit_account_type: 5 (Agent account type)
    • debit_account_type_id: Agent's user ID
  • credit_user_info: Contains company admin user details
    • credit_account_type: 1 (Admin account type)
    • credit_account_type_id: Admin user ID

Step 6: Save Cash Transfer Request​

  • On successful wallet transfer API response, extract the transaction details:
    • sender_txn_id: Transaction ID from the wallet transfer response
    • receiver_txn_id: Will be empty initially
  • Call the Save Cash Transfer Request API with the following payload:
{
    "to_user_type": null,
    "from_user_type": null,
    "to_user_detail": {
        "dial_code": "+221",
        "first_name": "travis",
        "last_name": "head",
        "phone_number": "678368383",
        "user_id": "",
        "user_type": 0
    },
    "currency_id": "1f1519903ed240578f071aa45cb479f2",
    "from_user_detail": {
        "dial_code": "+221",
        "first_name": "mitchel",
        "last_name": "marsh",
        "phone_number": "157127893",
        "user_id": "",
        "user_type": ""
    },
    "amount": 100,
    "from_agent_id": "dd4403366e944eb4b302a69f684bc52e",
    "sender_txn_id": "59f640c23f8749bba61c1b9b7c2283bb",
    "receiver_txn_id": "",
    "note": ""
}

Field Descriptions:

  • from_user_detail: Sender's (non-registered user) information entered by agent
    • user_type: 0 (Non-registered user)
    • user_id: Empty string (not registered)
  • to_user_detail: Receiver's (non-registered user) information entered by agent
    • user_type: 0 (Non-registered user)
    • user_id: Empty string (not registered)
  • from_agent_id: Logged-in agent's user ID
  • sender_txn_id: Transaction ID from wallet transfer response
  • receiver_txn_id: Empty initially (will be populated when receiver collects)
  • amount: Transfer amount (same as wallet transfer amount)

Step 7: Display Transaction Success​

  • Show success message to the agent
  • Display the cash transfer request reference number
  • Show transaction details including:
    • Sender information
    • Receiver information
    • Amount transferred
    • Transaction ID
    • Reference number for tracking

Step 8: Display in Transaction History​

  • To display the agent send money transaction in transaction history:
    • Filter transactions with transaction code "NRTA"
    • Call the Get All Cash Transfer Requests API
    • Pass the sender_txn_id as a filter parameter to retrieve the specific cash transfer request
    • Display the cash transfer request details including sender, receiver, and status

📡 API References​

Get Agent Wallet Balance​

  • API: Get User Wallet API
  • Purpose: Retrieve agent's current wallet balance to ensure sufficient funds

Check NRTA Product Availability​

  • API: Get Agent Profile Products API
  • Purpose: Verify that NRTA product is allowed for the agent's profile
  • Filter: agent_profile_id (agent's profile ID)
  • Search: Look for product_code: "NRTA"

Execute Wallet Transfer​

  • API: Wallet Transfer API
  • Purpose: Process the wallet transfer with NRTA product code
  • Debit: Agent's account (account type 5)
  • Credit: Admin account (account type 1)

Save Cash Transfer Request​

  • API: Save Cash Transfer Request API
  • Purpose: Create and store the cash transfer request with sender and receiver details
  • Note: Stores non-registered user information for both sender and receiver

Retrieve Cash Transfer Request​

  • API: Get All Cash Transfer Requests API
  • Purpose: Retrieve cash transfer request details using sender transaction ID for display in transaction history
  • Filter: sender_txn_id from wallet transfer response

Note: For complete API details, request/response formats, and error codes, please refer to the individual API documentation pages linked above.

🔄 Flow Logic​

1. Get agent wallet balance
   ↓
2. Enter sender details (non-registered user)
   ↓
3. Enter receiver details (non-registered user)
   ↓
4. Enter amount
   ↓
5. Check if NRTA product is allowed for agent
   ├─ Product not found → Show error, stop process
   └─ Product found → Continue
      ↓
6. Prepare wallet transfer request
   - Debit: Agent account
   - Credit: Admin account
   - Product code: NRTA
   ↓
7. Call Wallet Transfer API
   ├─ Failed → Show error, stop process
   └─ Success → Extract sender_txn_id
      ↓
8. Call Save Cash Transfer Request API
   - Pass sender details
   - Pass receiver details
   - Pass sender_txn_id
   - Pass agent_id
   ├─ Failed → Show error, transaction may be inconsistent
   └─ Success → Get reference number
      ↓
9. Display success message with reference number
   ↓
10. Transaction complete

🎯 Key Points​

Product Code​

  • Always use "NRTA" (Non-Register to Non-Register Transfer via Agent) for this flow
  • This product must be assigned to the agent's profile

User Types​

  • Sender and receiver are both non-registered users (user_type: 0)
  • Agent acts as an intermediary to facilitate the transfer
  • Agent's account is debited, admin account is credited

Account Types​

  • Debit Account Type: 5 (Agent)
  • Credit Account Type: 1 (Admin)
  • Agent wallet is debited with the transaction amount
  • Company admin wallet is credited (holds funds until receiver collection)

Transaction Flow​

  1. Agent pays from their wallet (debit)
  2. Admin wallet receives the funds (credit)
  3. Cash transfer request tracks sender and receiver details
  4. Receiver can later collect from another agent

Agent Role​

  • Agent facilitates the transaction for non-registered users
  • Agent's wallet must have sufficient balance
  • Agent must have NRTA product assigned to their profile
  • Agent ID is tracked in the cash transfer request

Reference Number​

  • Generated automatically by the Save Cash Transfer Request API
  • Used to track and identify the transfer
  • Receiver uses this reference to collect money from another agent

Important Validations​

  • ✅ Agent wallet balance must be sufficient
  • ✅ NRTA product must be assigned to agent's profile
  • ✅ Sender and receiver phone numbers must be valid
  • ✅ Amount must be positive and within allowed limits
  • ✅ All required fields must be provided

Error Handling​

  • If NRTA product check fails → Show "Product not allowed" message
  • If wallet transfer fails → Show wallet transfer error message
  • If cash transfer request save fails → Transaction is processed but tracking may be incomplete
  • Always verify API response status before proceeding to next step