Skip to content

Submit Refund Information

Unreleased: This endpoint is available only in the test environment for early integration. Production is not yet available.

Request

POST https://api.mycactus.dev/custody/v1/api/projects/{b_id}/refund-information/upload

Call this endpoint only after receiving FROZEN_PENDING_DOCUMENT. A new submission is rejected while an existing record is under review.

Parameters

Path Parameters

FieldTypeDescription
b_id
Required
StringBusiness line ID

Request Body

FieldTypeDescription
wallet_detail_id
Required
LongDeposit transaction detail ID
source_of_funds
Required
StringSource of funds
purpose_of_transfer
Required
StringPurpose of transfer
refund_address
Required
StringRequested refund destination address
transaction_hash
Required
StringOriginal deposit transaction hash
amount
Required
DecimalAmount
coin_name
Required
StringAsset name
third_party_details
Optional
StringThird-party information
proof_file_count
Optional
IntegerNumber of proof files, maximum 10; omit or use 0 when no files are required

Request Example

{
  "wallet_detail_id": 1000123456,
  "source_of_funds": "Own funds",
  "purpose_of_transfer": "Internal treasury transfer",
  "refund_address": "0xabc...",
  "transaction_hash": "0xdef...",
  "amount": 1000.5,
  "coin_name": "USDT",
  "third_party_details": "",
  "proof_file_count": 1
}

When proof files are requested, upload each file by sending its content with PUT to the returned upload_url. Always use the URL from the latest query.

Response

Response Body

FieldTypeDescription
codeIntegerResponse code; 0 indicates success
messageStringResponse message
successfulBooleanWhether the request was successful
dataObjectRefund information

data (object)

FieldTypeDescription
wallet_detail_idLongDeposit transaction detail ID
source_of_fundsStringSource of funds
purpose_of_transferStringPurpose of transfer
refund_addressStringRefund address
transaction_hashStringOriginal deposit transaction hash
amountDecimalAmount
coin_nameStringAsset name
third_party_detailsStringThird-party information
proof_filesArray<ProofFile>Proof files and presigned URLs
emailStringSubmitter email
statusStringUNDER_REVIEW, WAITING_FILE_UPLOADED, APPROVED, or REJECTED_AWAITING_RESUBMISSION
rejected_reasonStringReason for rejection
create_timeStringSubmission time

ProofFile (object)

FieldTypeDescription
file_idStringUnique file ID
statusStringPENDING_UPLOAD, PENDING_SCAN, APPROVED, REJECTED, or INVALID
upload_urlStringPresigned upload URL
upload_url_expires_atLongUpload URL expiration time in epoch milliseconds
download_urlStringPresigned download URL, or null when unavailable
download_url_expires_atLongDownload URL expiration time in epoch milliseconds, or null

Response Example

{
  "code": 0,
  "message": "Success",
  "successful": true,
  "data": {
    "wallet_detail_id": 1000123456,
    "source_of_funds": "Own funds",
    "purpose_of_transfer": "Internal treasury transfer",
    "refund_address": "0xabc...",
    "transaction_hash": "0xdef...",
    "amount": 1000.5,
    "coin_name": "USDT",
    "third_party_details": "",
    "proof_files": [
      {
        "file_id": "f1",
        "status": "PENDING_UPLOAD",
        "upload_url": "https://...",
        "upload_url_expires_at": 1785657600000,
        "download_url": null,
        "download_url_expires_at": null
      }
    ],
    "email": "ops@yourcompany.com",
    "status": "WAITING_FILE_UPLOADED",
    "rejected_reason": null,
    "create_time": "2026-07-31 16:00:00"
  }
}