Reject Transfer Beneficiary

post

https://api.blockpeer.finance/api/blockpeer-trade/transfer/rejectTransferBeneficiary

This endpoint initiates the rejection of a beneficiary transfer request for a document governed by a Title Escrow smart contract. When a beneficiary transfer is initiated by another party, the current beneficiary has the authority to approve or reject the transfer. This endpoint allows the current beneficiary to explicitly decline the pending transfer.

When the document file is provided, its embedded metadata is extracted to identify the corresponding token managed by the Title Escrow contract. Using this token reference and the registry address supplied in the request, the system locates the exact Title Escrow instance on-chain.

Authentication is performed through the user's wallet, verified using the authorization token provided in the request header. The authenticated wallet must match the current beneficiary on the Title Escrow contract. If the caller is not the recognized beneficiary, the rejection request is denied.

Any remarks provided in the request are converted into a structured data format and are stored as part of the rejection transaction. These remarks serve as contextual information for why the transfer was rejected.

The system encodes the contract call required to reject the transfer and prepares an unsigned blockchain transaction. After estimating gas usage and constructing this transaction, a transaction hash is generated. This hash becomes the basis for a signing challenge.

All details related to the rejection—including the document metadata, unsigned transaction, challenge data, and session parameters—are securely stored for the signing process.

The endpoint responds with a redirect URL to the signing interface. The caller must visit this URL to complete authentication and authorize the on-chain rejection of the pending transfer request.

File Upload Format (Base64 Data URI)

For endpoints that accept file inputs, files must be submitted as a Base64-encoded Data URI string in the document field.

Format
data:<mimeType>;name=<filename>;base64,<base64EncodedContent>

Example
json
{ "document": "data:application/octet-stream;name=BL-0xd7.tt;base64,ewogICJAY29udGV4dCI6IFsKICAgICJodHRwcz..." }

Notes

Requires End User approval
Reverts the pending transfer request
No control change occurs

This API returns a URL with sessionId.
Use GET /auth/session-response?sessionId=<sessionId> to retrieve the session result.

Responses

File Upload Format (Base64 Data URI)

Notes

200The rejection of the beneficiary transfer has been initiated successfully. The response includes a redirect URL for completing the authentication and signing process.

400The request contained missing or invalid fields, or the authorization token was not provided.

401The caller is not authorized to reject the transfer. This occurs if the caller is not the current beneficiary according to the Title Escrow contract.

409The rejection request is invalid due to the contract state—for example, when no beneficiary transfer is pending.

500A server error occurred while preparing the rejection request. This may involve blockchain read failures, transaction preparation issues, or unexpected runtime errors.