GuideReference

Process Fiat Deposits

This guide will walk you through the process of programmatically accepting fiat currency deposits (e.g., NGN, KES) into your Busha Business fiat balances. Fiat deposits are typically facilitated through the generation of temporary bank accounts.

What You’ll Achieve:

  1. Understand the specific quote requirements for fiat deposits.

  2. Generate a deposit quote that provisions a temporary bank account.

  3. Finalize the deposit transfer to obtain the temporary bank account details.

  4. Learn how to instruct your users to make the deposit.

  5. Monitor the status of fiat deposits.

PrerequisitesCopied!

Before you begin, ensure you have:

Step 1: Get a Quote for the Fiat DepositCopied!

Fiat deposits are initiated by creating a Quote, where the source_currency and target_currency are the same fiat currency (e.g., NGN to NGN). The key here is the pay_in object, which specifies that you intend to use a temporary_bank_account for the deposit. This informs Busha to prepare for generating such an account upon transfer finalization.

To get a fiat deposit quote:

  1. Open your terminal or command prompt.

  2. Construct a POST request to the /v1/quotes endpoint.

  3. Specify the source_currency and target_currency (both being the fiat currency you expect to receive), the source_amount the user intends to deposit, and a pay_in object with type: “temporary_bank_account”.

  4. Replace YOUR_BASE_URL with your chosen environment’s URL and YOUR_SECRET_TOKEN with your actual key.

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/quotes \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_currency": "NGN",
    "target_currency": "NGN",
    "source_amount": "10000",
    "pay_in": {
      "type": "temporary_bank_account"
    }
  }'

A successful response will return a standard Quote object, similar to what you’ve seen before. Note the id of the returned Quote (e.g., QUO_vxcF2svmjMbxDp4T5dcD8 ), as you will need this ID for the next step. The pay_in object in the quote response will mirror what you sent in the request.

Step 2: Finalize the Deposit Transfer (Generate Temporary Bank Account)Copied!

After obtaining a valid Quote for a fiat deposit, you finalize the transfer. This crucial step is where Busha generates the temporary bank account details that your user will transfer funds into. The transfer object is initiated using the POST /v1/transfers endpoint.

To finalize the deposit transfer:

  1. Use the POST request below to the /v1/transfers endpoint.

  2. Include the quote_id obtained from Step 1.

  3. Replace YOUR_BASE_URL and YOUR_SECRET_KEY with your actual details.

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/transfers \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "QUO_vxcF2svmjMbxDp4T5dcD8"
  }'

Sample Response with Generated Temporary Account Number:

A successful response will return a Transfer object. The generated temporary bank account number and other recipient details will be located within the data.pay_in.recipient_details object of this response.

{
  "status": "success",
  "message": "Created transfer successfully",
  "data": {
    "id": "TRF_LJB2GQb55Cs98LbpqgRMx",
    "profile_id": "BUS_tg6yujbZ1nMu5BLQkPGGO",
    "quote_id": "QUO_vxcF2svmjMbxDp4T5dcD8",
    "source_currency": "NGN",
    "target_currency": "NGN",
    "source_amount": "10000",
    "target_amount": "9900",
    "rate": {
      "rate": "1",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "NGN",
      "target_currency": "NGN"
    },
    "fees": [
      {
        "amount": {
          "amount": "100",
          "currency": "NGN"
        },
        "name": "payment gateway fee",
        "type": "FIXED"
      }
    ],
    "pay_in": {
      "expires_at": "2025-02-21T10:46:56.232278869Z",
      "recipient_details": {
        "account_name": "Payaza(Business 1 Business)",
        "account_number": "7000384620",
        "bank_name": "78 FINANCE COMPANY LIMITED",
        "email": "dickson@busha.co"
      },
      "type": "temporary_bank_account"
    },
    "status": "pending",
    "created_at": "2025-02-21T10:16:54.40130914Z",
    "updated_at": "2025-02-21T10:16:54.401309215Z"
  }
}

Step 3: Instruct Your User and Monitor Deposit StatusCopied!

Once you have the temporary bank account details, your application should display these to the end user, along with clear instructions to make the bank transfer. After the user initiates the transfer, you’ll need to monitor its status to confirm when the funds have been successfully deposited into your Busha balance.

To monitor deposit status:

  • Webhooks (Recommended): Set up a webhook endpoint to receive real-time notifications from Busha when the transfer status changes. This is the most efficient method for real-time updates.

  • Polling (Less Recommended): Periodically GET the transfer status using the transfer id (TRF_LJB2GQb55Cs98LbpqgRMx in the example). While possible, this is less efficient and can lead to rate limiting if done too frequently.

Expected Transfer Statutes:

  • pending : Transfer initiated, awaiting user bank transfer.

  • completed: Funds have been successfully received and credited to your Busha balance.

  • failed: The deposit failed (e.g., transfer not received within timeframe, invalid details)

  • reversed: The deposit was processed but later reversed.

Troubleshooting Common Fiat Deposit IssuesCopied!

  • “Quote expired” during transfer finalization: Always create a fresh quote immediately before attempting to finalize the transfer.

  • Deposit not reflecting: Check the transfer status via API/webhooks. If still pending after an extended period, contact Busha support with the TRF_ ID.

  • Temporary account expires: Ensure the user makes the transfer before the pay_in.expires_at time shown in the transfer response. If expired, you may need to initiate a new deposit flow.

What’s Next?Copied!

Now that you know how to process fiat deposits, consider: