Instant Cashin API Endpoint

Usage

  • This endpoint is used to disburse the E-Money for an anonymous recipients through a specific issuer.
Environment API location source HTTP Method Content Type
{ENV} ^disburse/ POST JSON

Headers

{
    "Content-Type": "application/json",
    "Authorization": "Bearer {ACCESS_TOKEN}"
}

Request

  1. Request Parameters

    Field M/O/C Type Notes
    issuer M String the channel to disburse the e-money through
    amount M Float
    msisdn C String vodafone/etisalat/orange/bank wallets
    bank_card_number C String bank accounts/cards only
    bank_transaction_type C String bank accounts/cards only
    bank_code C String bank accounts/cards only
    full_name C String bank accounts/cards only
    national_id M String The national for the recipient
    client_reference_id O String of uuid4 it's reference id generated by your side
    client_reference O String it's reference id generated by your side must be unique
    customer_bears_fees O Boolean Determines who pays the transaction fees
    • Usage:
      • {issuer} options list: [vodafone, etisalat, orange, bank_wallet, bank_card] -case insensitive-.
      • {amount} it's valid to use decimal point numbers up to 2 decimal points ex: 53.99
      • {msisdn}: the +2 added automatically, so it consists of 11 numbers, ex: 01020304050
      • {national_id}: the national id number for the recipient, ex: 29005270102927
      • {bank_card_number}: expected: [bank account number, IBAN, card number]
      • {bank_transaction_type} options list: [salary, credit_card, prepaid_card, cash_transfer] -case insensitive-.
      • {client_reference_id} generated UUID by the client to be saved as reference in case of timeouts.

      • {customer_bears_fees} optional boolean parameter (defaults to false if not provided):

        • true: Customer pays the transaction fees and VAT. The customer receives the amount minus fees and VAT.
          • Example: For a 100 EGP transaction with 10 EGP fees + 1.40 EGP VAT:
            • Merchant's budget is charged: 100 EGP
            • Customer receives: 88.60 EGP (100 - 10 - 1.40)
        • false (default): Merchant pays the transaction fees and VAT. The customer receives the full amount.
          • Example: For a 100 EGP transaction with 10 EGP fees + 1.40 EGP VAT:
            • Merchant's budget is charged: 111.40 EGP (100 + 10 + 1.40)
            • Customer receives: 100 EGP
        Description Type
        For concurrent or repeated payments salary
        For credit cards payments credit_card
        For prepaid cards and Meeza cards payments prepaid_card
        For bank accounts, debit cards etc. cash_transfer

        the reference number of his/her transaction. * {bank_code}: the banks list and their corresponding codes -case sensitive-.

        Bank Name Bank Code
        Ahli United Bank AUB
        MIDBANK MIDB
        Banque Du Caire BDC
        HSBC Bank Egypt S.A.E HSBC
        Credit Agricole Egypt S.A.E CAE
        Egyptian Gulf Bank EGB
        The United Bank UB
        Qatar National Bank Alahli QNB
        Arab Bank PLC ARAB
        Emirates National Bank of Dubai ENBD
        Al Ahli Bank of Kuwait – Egypt ABK
        National Bank of Kuwait – Egypt NBK
        Arab Banking Corporation - Egypt S.A.E ABC
        First Abu Dhabi Bank FAB
        Abu Dhabi Islamic Bank – Egypt ADIB
        Commercial International Bank - Egypt S.A.E CIB
        Housing And Development Bank HDB
        Banque Misr MISR
        Arab African International Bank AAIB
        Egyptian Arab Land Bank EALB
        Export Development Bank of Egypt EDBE
        Faisal Islamic Bank of Egypt FAIB
        Blom Bank BLOM
        Abu Dhabi Commercial Bank – Egypt ADCB
        Alex Bank Egypt BOA
        Societe Arabe Internationale De Banque SAIB
        National Bank of Egypt NBE
        Al Baraka Bank Egypt B.S.C. ABRK
        Egypt Post POST
        Nasser Social Bank NSB
        Industrial Development Bank IDB
        Suez Canal Bank SCB
        Mashreq Bank MASH
        Arab Investment Bank AIB
        General Authority For Supply Commodities GASC
        Arab International Bank ARIB
        Agricultural Bank of Egypt PDAC
        National Bank of Greece NBG
        Central Bank Of Egypt CBE
        ATTIJARIWAFA BANK Egypt BBE

Response

  1. Response Parameters

    Field Type Notes
    disbursement_status String
    status_description String
    status_code String
    transaction_id String

Samples

  1. Instant cashin request through Vodafone as an issuer

    • request

      {
    "amount": "90.56",
    "issuer": "vodafone",
    "msisdn": "01092737975"
}

    • response

      {
    "transaction_id": "92134d2b-d1a5-4dde-859c-a1175e94582c",
    "msisdn": "01092737975",
    "issuer": "vodafone",
    "amount": "90.56",
    "full_name": "",
    "disbursement_status": "success",
    "status_code": "200",
    "status_description": "تم إيداع 90.56 جنيه إلى رقم 01010101010 بنجاح",
    "aman_cashing_details": null,
    "created_at": "2020-10-12 06:54:31.849561",
    "updated_at": "2020-10-12 06:54:33.146926"
}

    1.1 Vodafone request with customer bears fees (customer pays fees)

    • request

      {
    "amount": "100.00",
    "issuer": "vodafone",
    "msisdn": "01092737975",
    "customer_bears_fees": true
}

    • response

      {
    "transaction_id": "92134d2b-d1a5-4dde-859c-a1175e94582c",
    "msisdn": "01092737975",
    "issuer": "vodafone",
    "amount": "100.00",
    "full_name": "",
    "disbursement_status": "success",
    "status_code": "200",
    "status_description": "تم إيداع 88.60 جنيه إلى رقم 01092737975 بنجاح",
    "aman_cashing_details": null,
    "created_at": "2020-10-12 06:54:31.849561",
    "updated_at": "2020-10-12 06:54:33.146926"
}

    • Note: In this case, the merchant's budget is charged 100 EGP only, and the customer receives 88.60 EGP (100 - 10 - 1.40, assuming 10 EGP fees and 1.40 EGP VAT)

  2. Instant cashin request through Etisalat as an issuer

    • request

      {
    "issuer": "etisalat",
    "amount": 100.0,
    "msisdn": "01112131415"
}

    • response

      {
    "transaction_id": "4d8d2215-6b15-4cf0-8a5a-e62e3eb5fdb3",
    "msisdn": "01112131415",
    "issuer": "etisalat",
    "amount": 100.0,
    "full_name": "",
    "disbursement_status": "failed",
    "status_code": "90040",
    "status_description": "عزيزي العميل أنت غير مشترك في خدمة اتصالات كاش، للاشتراك برجاء زيارة أقرب فرع من فروع اتصالات بالخط والرقم القومي للمزيد من المعلومات اتصل ب-778",
    "aman_cashing_details": null,
    "created_at": "2020-10-12 07:00:23.453577",
    "updated_at": "2020-10-12 07:00:24.615864"
}

  3. Instant cashin request through Orange as an issuer

    • request

      {
    "issuer": "orange",
    "amount": 100.0,
    "msisdn": "01092737975"
}

    • response

      {
    "transaction_id": "7ce037de-a8d8-411c-be19-65ceb4e0dbd3",
    "issuer": "orange",
    "msisdn": "01092737975",
    "amount": 100.0,
    "full_name": "",
    "disbursement_status": "success",
    "status_code": "200",
    "status_description": "amount is deposited successfully",
    "aman_cashing_details": null,
    "created_at": "2020-10-12 07:19:46.121389",
    "updated_at": "2020-10-12 07:19:47.550900"
}

  4. Instant cashin request through Bank Wallets as an issuer

    • request

      {
    "issuer": "bank_wallet",
    "amount": 100.0,
    "msisdn": "01092737975"
}

    • response

      {
    "transaction_id": "d9707a55-16af-4d35-9c69-2bce5ecc6cfb",
    "issuer": "bank_wallet",
    "msisdn": "01092737975",
    "amount": 100.0,
    "full_name": "",
    "disbursement_status": "success",
    "status_code": "200",
    "status_description": "amount is deposited successfully",
    "aman_cashing_details": null,
    "created_at": "2020-10-12 07:23:17.540219",
    "updated_at": "2020-10-12 07:23:18.113919"
}

  5. Instant cashin request through Bank Cards / Accounts as an issuer

    • request

      {
    "issuer": "bank_card",
    "amount": 100.0,
    "full_name": "Tom Bernard Ceisar",
    "bank_card_number": "1111-2222-3333-4444",
    "bank_code": "CIB",
    "bank_transaction_type": "cash_transfer"
}

    • response

      {
    "transaction_id": "01ea2cd1-f01f-4857-b5ae-1e6359d1c779",
    "issuer": "bank_card",
    "amount": "100.00",
    "bank_card_number": "1111 2222 3333 4444",
    "full_name": "Tom Bernard Ceisar",
    "bank_code": "MISR",
    "bank_transaction_type": "salary",
    "disbursement_status": "pending",
    "status_code": "8000",
    "status_description": "Transaction received and validated successfully. Dispatched for being processed by the bank",
    "created_at": "2020-10-12 07:25:51.631701",
    "updated_at": "2020-10-12 07:25:52.263173"
}

    6.1 Bank Card request with customer bears fees (customer pays fees)

    • request

      {
    "issuer": "bank_card",
    "amount": 100.0,
    "full_name": "Tom Bernard Ceisar",
    "bank_card_number": "1111-2222-3333-4444",
    "bank_code": "CIB",
    "bank_transaction_type": "cash_transfer",
    "customer_bears_fees": true
}

    • response

      {
    "transaction_id": "01ea2cd1-f01f-4857-b5ae-1e6359d1c779",
    "issuer": "bank_card",
    "amount": "100.00",
    "bank_card_number": "1111 2222 3333 4444",
    "full_name": "Tom Bernard Ceisar",
    "bank_code": "MISR",
    "bank_transaction_type": "salary",
    "disbursement_status": "pending",
    "status_code": "8000",
    "status_description": "Transaction received and validated successfully. Dispatched for being processed by the bank",
    "created_at": "2020-10-12 07:25:51.631701",
    "updated_at": "2020-10-12 07:25:52.263173"
}

    • Note: In this case, the merchant's budget is charged 100 EGP, but the customer receives 100 - fees - VAT (e.g., 88.60 EGP if fees are 10 EGP and VAT is 1.40 EGP)

  6. Instant cashin request through Egypt Post as an issuer

    • request

      {
    "issuer": "post",
    "amount": 100.0,
    "full_name": "محمد محمود صابر",
    "national_id": "29005270102927"
}

    • response

      {
    "transaction_id": "929a04d5-ed26-4132-9456-407a588f94da",
    "anon_recipient": "29005270102927",
    "issuer": "post",
    "amount": 100.0,
    "full_name": "محمد محمود صابر",
    "disbursement_status": "pending",
    "status_code": "200",
    "fees": 10.0,
    "vat": 1.4,
    "reference_id": "",
    "status_description": "Request submitted",
    "aman_cashing_details": null,
    "client_transaction_reference": null,
    "created_at": "2024-07-03 12:18:25.211709",
    "updated_at": "2024-07-03 12:18:25.236080",
    "reference": null,
    "accept_balance_transfer_id": null
}

  7. Examples of failure cases

    7.1 Parameters didn't pass validations

            {
            "disbursement_status": "failed",
            "status_description": {
                "amount": [
                    "This field is required."
                ],
                "issuer": [
                    "This field is required."
                ]
            },
            "status_code": "400"
        }

    7.2 Token used is expired

        {
        "disbursement_status": "failed",
        "status_description": "Authentication credentials were not provided.",
        "status_code": "401"
    }

    7.2 The amount to be disbursed exceeds the current balance of the entity

        {
        "disbursement_status": "failed",
        "status_description": "Sorry, the amount to be disbursed exceeds you budget limit, please contact your support team",
        "status_code": "400"
    }

  8. Test e-wallet numbers

    IMPORTANT Note:

    these numbers will get success response on staging environment only

    1. Test number for vodafone issuer

       01023456789

    2. Test number for etisalat issuer

      01123456789

    3. Test number for orange issuer

       01223456789

    4. Test number for bank_wallet issuer

      01123416789

    5. Test number for bank_card issuer

      1111222233334444

    6. Test IBAN number for bank_card issuer

      EG829299835722904511873050307

NOTE: Transactions on wallet take notime to get final status (on the spot)

NOTE: Transactions on bank take 2 Working Days to get final status

NOTE: customer_bears_fees parameter behavior: - When customer_bears_fees is true: Customer pays fees. Merchant's budget is charged only the transaction amount. Customer receives amount minus fees and VAT. - When customer_bears_fees is false (default): Merchant pays fees. Merchant's budget is charged amount plus fees and VAT. Customer receives the full amount. - For returned/rejected transactions (due to incorrect details): If customer_bears_fees is true, the merchant is refunded the amount minus fees and VAT (fees are penalty). If false, the merchant is refunded the full amount only. - For failed transactions (system/bank errors): The merchant is always refunded based on what was originally charged from their budget.