14. Add external recharge to balance

Add external recharge to balance

This endpoint allows you to attach payment receipts for recharges made through external methods (e.g., bank deposits). The specified amount will be added to the agency's preloaded balance.

Endpoint

POST https://[base_url]/v2/preloaded-balance/agencies/{agency_id}/external

Query Parameters

Parameter	Type	Required	Description
agency_id	Integer	Yes	The unique ID of the agency

Request Body

This endpoint expects a multipart/form-data request containing the recharge details and the payment receipt file.

Example Request (multipart/form-data)

Content-Type: multipart/form-data

Parameter	Type	Required	Description
amount	Float	Yes	The amount to be added to the prepaid balance
currency	String	Yes	The currency for the recharge (must be COP)
payment_method	String	Yes	The payment method used for the recharge
payment_reference	String	Yes	The reference number of the payment
payment_receipt	File	Yes	The payment receipt file (PDF, JPG, PNG, etc.)

Example Request (cURL)

curl -X POST https://[base_url]/v2/preloaded-balance/agencies/{agency_id}/external \
  -H "Content-Type: multipart/form-data" \
  -F "amount=300000" \
  -F "currency=COP" \
  -F "payment_method=Bank Transfer" \
  -F "payment_reference=ABC123456" \
  -F "payment_receipt=@/path/to/receipt.pdf"

Response

{
    "msg": "Saldo añadido correctamente",
    "balance": 200000.0,
    "file_key": "preloaded-balance/95fee795-a6c8-49fd-b174-b8296e74c74b.pdf"
}

Downloading the Uploaded File

Once the payment receipt is uploaded, it can be downloaded using the following endpoint:

Endpoint

GET https://[base_url]/v2/media/{file_key}

Replace {file_key} with the actual file key returned from the upload process.