Update Escrow

This endpoint allows you to change the properties of an escrow as long as a series of requirements are met, which will be mentioned in this section.

Requirements to use:

1. Only the entity with the platform role has permissions to execute this endpoint

2. If an escrow has funds, the only thing the platform can do is add more milestones. The other properties cannot be modified under any circumstances.

Headers

Name	Value
Content-Type	application/json
x-api-key	<token>

Roles:

Name	Type	Description
approver	string	Address of the entity requiring the service.
serviceProvider	string	Address of the entity providing the service.
platformAddress	string	Address of the entity that owns the escrow
releaseSigner	string	Address of the user in charge of releasing the escrow funds to the service provider.
disputeResolver	string	Address in charge of resolving disputes within the escrow.
receiver	string	Address where escrow proceeds will be sent to

Milestone:

Name	Type	Description
description	string	Text describing the function of the milestone.
status	string	Milestone status. Ex: Approved, In dispute, etc...
approved	boolean	Flag indicating whether a milestone has been approved by the approver.

Flags

Name	Type	Description
disputed	boolean	Flag indicating that an escrow is in dispute.
released	boolean	Flag indicating that escrow funds have already been released.
resolved	boolean	Flag indicating that a disputed escrow has already been resolved.

Trustline

Name	Type	Description
address	string	Public address establishing permission to accept and use a specific token.

Open API

put

Authorizations

x-api-key

Body

application/json

signerstringRequired

Entity that signs the transaction that deploys and initializes the escrow

Example: GSIGN...XYZ

contractIdstringRequired

ID (address) that identifies the escrow contract

Example: CAZ6UQX7...

Responses

200

This endpoint returns an unsigned transaction in XDR format. This XDR is then used to sign the transaction using the “/helper/send-transaction” endpoint.

application/json

400

Bad request

401

Unauthorized access

429

Too Many Requests

500

Possible errors:

• Escrow not found
• The platform fee cannot exceed 99%
• Amount cannot be equal to or less than zero
• Escrow initialized without milestone
• Cannot define more than 50 milestones in an escrow
• Only the platform address should be able to execute this function
• The platform address of the escrow cannot be changed
• Escrow has been opened for dispute resolution
• All flags (approved, disputed, released) must be false in order to execute this function
• The provided escrow properties do not match the stored escrow
• You can't change the escrow properties after the milestone is approved
• An unexpected error occurred

application/json

put

/escrow/single-release/update-escrow

HTTPcURLJavaScriptPython

PUT /escrow/single-release/update-escrow HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 846

{
  "signer": "GAPPROVER1234567890...",
  "contractId": "CAZ6UQX7...",
  "isActive": true,
  "escrow": {
    "signer": "GAPPROVER1234567890...",
    "engagementId": "ENG12345",
    "title": "Project Title",
    "description": "This is a detailed description of the project.",
    "roles": {
      "approver": "GAPPROVER1234567890...",
      "serviceProvider": "GAPPROVER1234567890...",
      "platformAddress": "GAPPROVER1234567890...",
      "releaseSigner": "GAPPROVER1234567890...",
      "disputeResolver": "GAPPROVER1234567890...",
      "receiver": "GAPPROVER1234567890..."
    },
    "amount": 1000,
    "platformFee": 50,
    "milestones": [
      {
        "description": "test1",
        "status": "pending",
        "evidence": "Any evidence that the milestone is completed"
      },
      {
        "description": "test2",
        "status": "pending",
        "evidence": "Any evidence that the milestone is completed"
      }
    ],
    "flags": {
      "disputed": false,
      "released": false,
      "resolved": false
    },
    "trustline": {
      "address": "GAPPROVER1234567890..."
    }
  }
}

{
  "status": "SUCCESS",
  "unsignedTransaction": "AAAAAgAAAAAtWsgedQ...."
}

What this Endpoint returns?

This endpoint returns the transaction unsigned so that the transaction can be signed by means of a customer wallet.

Use Example:

import axios from "axios";

const http = axios.create({
  baseURL: "https://dev.api.trustlesswork.com",
  timeout: 10000,
  headers: {
    "Content-Type": "application/json",
    "x-api-key": your_api_key,
  },
});

export const useExample = async () => {
    // Get the signer address
    const { address } = await kit.getAddress();

    const response = await http.put(
      "/escrow/single-release/update-escrow",
      {
        // body requested for the endpoint
      },
    ); 
    
    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/helper/send-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;

    return data;
}