Skip to main content

Common Transaction Flow

This document describes the common transaction flow for the transaction service.

Global Requirements (Headers & Configuration)​

For every API call, you must pass:

  • companyId – Identifier of the company
  • requestId – A unique value (UUID) for each API request

Configuration​

You have to configure the following values in your environment:

  • companyId: 59388167894b4d10a04fe5da3b8a2104
  • company admin id: 640b793d04e2428dbf19ab10399f4edb

Common Modules (Reusable Across All Transactions)

1. Load Currency and Wallet Details​

Used in all transaction types to load active currency and relevant wallet IDs.

Get Currency Details​

Purpose: Get the currency details and save currencyId for further API use.
Endpoint: GET /gafapay/v3/base/currency

Response Example​

{
  "success": 1,
  "error": [],
  "data": {
    "currency": [
      {
        "id": "1f1519903ed240578f071aa45cb479f2",
        "is_active": true,
        "updated_by": null,
        "updated_date": 1733997986,
        "currency_name": "FCFA",
        "currency_code": "XAF",
        "currency_symbol": "FCFA",
        "is_primary_currency": true,
        "country_id": "1a5518d166cb4a3c8231f74d917cdac3"
      }
    ]
  }
}

Get Company Main Wallet​

Purpose: Get the company main wallet details and save walletId for further API use.
Endpoint: GET /gafapay/v3/transaction/wallet?wallet_type=1&currency_id={currency_id}

Response Example​

{
    "success": 1,
    "error": [],
    "data": {
        "wallet": [
            {
                "is_active": true,
                "created_by": "b87d383d91fe48e58024f8344ba3273c",
                "created_date": 1676540322,
                "updated_by": "640b793d04e2428dbf19ab10399f4edb",
                "updated_date": 1699425669,
                "id": "4010122e9d604e798b9a6e961df3e5b4",
                "wallet_name": "Gafa Wallet",
                "currency_id": "1f1519903ed240578f071aa45cb479f2",
                "wallet_type": 1,
                "pool_amount": 2.35415948E8,
                "sub_wallet_category_id": null,
                "user_id": null,
                "status": 1
            }
        ]
    }
}

Get Logged-In User Wallet​

Purpose: Get the current user wallet details including wallet balance.
Endpoint: GET /gafapay/v3/transaction/user_wallet?user_id={logged_in_user_id}&currency_id={currency_id}&wallet_id={wallet_id}

Response Example​

{
    "success": 1,
    "error": [],
    "data": {
        "wallet": {
            "id": "d5e2f320ed71432ca9508e972e0f7a9f",
            "wallet_id": "4010122e9d604e798b9a6e961df3e5b4",
            "currency_id": "1f1519903ed240578f071aa45cb479f2",
            "user_id": "fb8f09210e0f46b7b4262d77f5b6c273",
            "is_default": true,
            "is_active": true,
            "wallet_balance": 500.0
        }
    }
}

2. Get Charges Details​

Used to determine applicable charges and fees for a given product type.

Get User Profile (Based on Wallet + Currency) APIs​

Purpose: Get the current user profile and charges from that, save profile id you need to pass that in further API.
Endpoint: GET /gafapay/v3/profile_threshold/user_profile

Response Example​

{
    "success": 1,
    "error": [],
    "data": {
        "user_profile": {
            "id": "b485d774b6c946e4884c924dc87647b8",
            "user_type": 2,
            "user_id": "fb8f09210e0f46b7b4262d77f5b6c273",
            "profile_id": "8be733e3facc45b5b268ae5c699aa772",
            "currency_id": "1f1519903ed240578f071aa45cb479f2",
            "parent_user_id": null,
            "parent_user_type": null,
            "is_active": true,
            "created_by": "fb8f09210e0f46b7b4262d77f5b6c273",
            "updated_date": 1754156707
        }
    }
}

Get Profile Product​

Purpose: Get the profile product details and check if charges are configured for the product or not.
Endpoint: GET /gafapay/v3/profile_threshold/profile_products?profile_id={profile_id}&product_code={PRODUCT_CODE}

Response Example​

{
    "success": 1,
    "error": [],
    "data": {
        "profile_product": {
            "id": "710466f2a46742e3a97e537588463edb",
            "is_active": true,
            "created_by": null,
            "updated_date": 1701682048,
            "profile_id": "8be733e3facc45b5b268ae5c699aa772",
            "product_id": "619395711eac4be9bc856ca0d9a6af1f",
            "product_name": "P2P (Domestic Money Transfer)",
            "product_code": "P2P",
            "product_type": 1,
            "charges": [
                {
                    "charge_id": "c869e0436e9e411093bfa6dc15c06659"
                }
            ],
            "commission_id": "",
            "updated_by": "640b793d04e2428dbf19ab10399f4edb"
        }
    }
}

Note: If you get the charges [] null then charges are not applied on that product so you don't need to call the calculate charges API and if exists then you have to show the total charges on charges and based on included and excluded you have show the details.

Calculate Charges (only if charges exist)​

Purpose: Get the final charges details based on the profile and product code.
Endpoint: POST /gafapay/v3/transaction/calculate_charges

Request Body​

{
    "wallet_id": "4010122e9d604e798b9a6e961df3e5b4",
    "currency_id": "1f1519903ed240578f071aa45cb479f2",
    "product_code": "P2P",
    "txn_amount": 100,
    "profile_id": "8be733e3facc45b5b268ae5c699aa772"
}

Response Example​

{
    "success": 1,
    "error": [],
    "data": {
        "charges_info": {
            "is_included": false,
            "total_charges": 5.0,
            "charges": [
                {
                    "charge_name": " Charges :",
                    "charge_type": 1,
                    "charge_value_type": 1,
                    "charge_id": "c869e0436e9e411093bfa6dc15c06659",
                    "charge_value": 1.0,
                    "final_charge": 5.0
                }
            ]
        }
    }
}

Note: Use the charges info to pass in wallet transfer API.

3. Wallet Transfer​

Purpose: Used to complete any wallet-based transaction (P2P, P2M, etc.).
Endpoint: POST /gafapay/v3/transaction/wallet_transfer

Request Body​

{
  "charges_info": null, // Pass the charges info from the Calculate Charges API if applicable
  "credit_user_info": {
    "currency_id": "currency_id_from_currency_API",
    "credit_type": 3, // Wallet (fixed)
    "credit_type_id": "wallet_id_from_main_wallet_API",
    "credit_account_type": 2, // user type of credit user
    "credit_account_type_id": "user_id_of_credit_user",
    "username": "Credit User Name"
  },
  "debit_user_info": {
    "currency_id": "currency_id_from_currency_API",
    "debit_type": 3, // Wallet (fixed)
    "debit_type_id": "wallet_id_from_main_wallet_API",
    "debit_account_type": 2, // user type of debit user
    "debit_account_type_id": "user_id_of_debit_user",
    "username": "Debit User Name"
  },
  "company_admin_user_info": {
    "currency_id": "currency_id_from_currency_API",
    "credit_type": 1, // Company Admin (fixed)
    "credit_type_id": "wallet_id_from_main_wallet_API",
    "credit_account_type": 1,
    "credit_account_type_id": "admin_user_id",
    "username": "Company Admin Name"
  },
  "payment_response": null,
  "card_info": null,
  "txn_amount": 100, // Transaction amount
  "txn_code": "P2P", // Product code
  "payment_mode": 3,
  "meta_data": {
    "company_name": "Gafa Pay"
  },
  "note": "Optional transaction note"
}

Parameters​

ParameterDescription
currency_idYou will get this from the Currency Details API
wallet_idYou will get this from the Main Wallet API
user_idLogged-in user's user ID
user_typeLogged-in user's user type
credit_typeFixed value: 3 (Wallet)
credit_type_idWallet ID of the credit user, from Main Wallet API
credit_account_typeUser type of the credit user
credit_account_type_idUser ID of the credit user
debit_typeFixed value: 3 (Wallet)
debit_type_idWallet ID of the debit user (logged-in user), from Main Wallet API
debit_account_typeUser type of the debit user
debit_account_type_idUser ID of the debit user
company_admin_user_info.credit_typeFixed value: 1 (Admin)
company_admin_user_info.credit_type_idWallet ID of the company admin
company_admin_user_info.credit_account_typeFixed value: 1
company_admin_user_info.credit_account_type_idUser ID of the company admin
txn_amountAmount to be transferred in the transaction
txn_codeProduct code (e.g., P2P, P2M, etc.)
noteTransaction note (optional)
charges_infoIf applicable, pass the object from the Calculate Charges API

Response Example​

{
    "success": 1,
    "error": [],
    "data": {
        "message": "TRANSACTION_WALLET_TRANSFER_SUCCESS",
        "transaction": {
            "txn_number": "97910374",
            "txn_id": "5b9468ba3b426b89f82af1639d0a77",
            "txn_status": 3
        }
    }
}

4. Refund Flow​

Used to process refund transactions for various transaction types.

Overview​

The refund flow provides a standardized approach for processing refund transactions across different transaction types including P2P, P2M, and other wallet-based transactions.

Flow Steps​

[To be filled with refund flow steps]

Prerequisites​

[To be filled with prerequisites]

API Endpoints​

[To be filled with API endpoints]

Flow Diagram​

[To be filled with flow diagram]

Error Handling​

[To be filled with error handling scenarios]