GuideReference

Initiate Transactions on Behalf of a Customer

Businesses can perform any transaction on behalf of a customer that the customer could perform themselves. To do this, the customer's profile ID must be included in the request body. This ensures the transaction is correctly attributed to the customer rather than the business's account.

For transaction requests involving a customer, the X-BU-PROFILE-ID field should be included in the request header, and its value should be set to the customer ID for whom the request is performed on their behalf.

This guide will walk you through the process of programmatically accepting fiat currency deposits (e.g., NGN, KES) into your customer’s 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 customer to make the deposit.

  5. Monitor the status of fiat deposits.

Prerequisites

Before you begin, ensure you have:

Step 1: Get a Quote for the Fiat Deposit

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 customer intends to deposit, and a pay_in object with type: “temporary_bank_account”.

  4. Replace {customer_id} with the customer ID.

  5. 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 'X-BU-PROFILE-ID: {customer_id}' \
  -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)

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 customer 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 {customer_id} with the customer ID.

  4. Replace YOUR_BASE_URL and YOUR_SECRET_KEY with your actual details.

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/transfers \
  -H 'X-BU-PROFILE-ID: {customer_id}' \
  -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": "CUS_BqpKZiPXPo3Vz",
    "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 Status

Once you have the temporary bank account details, your application should display these to the customer, along with clear instructions to make the bank transfer. After the customer 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 Issues

  • “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?

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