Ask us anything. We're here to help.

2022-10-17 Idempotency Added to POST /transfers Endpoint

API Updates

General 

  • We've added a new field to the POST /transfersendpoint called client_transfer_id.
  • This is an optional field and when used Zero Hash will complete idempotency checks for previously created transfers to validate that the client_transfer_id has not already been used.
    • If providing a value, the client_transfer_id must be unique, we will return an error if the id has ever been used in the past.
  • Zero Hash will now return the client_transfer_id when a Platform uses the GET /transfers endpoint.
    • If a client_transfer_id was not provided for a transaction, we will return a null value.

Use Cases 

  • This feature is ideal for Platforms that expect to perform a significant volume of transfers and wants to ensure that transfer requests are not duplicated.

 

API Sequencing

  • Example Request
    • POST /transfer
      {
      "from_participant_code":"PLAT01",
      "from_account_group": "PLAT01",
      "to_participant_code":"CUST01",
      "to_account_group": "PLAT01",
      "client_transfer_id": "b8aa391c-6da9-4991-b123-f8d64976c92e",
      "asset":"USD",
      "amount":"1.00"
      }
       
  • Example Response:
    • {
      "message": {
      "id": 48598,
      "client_transfer_id": "b8aa391c-6da9-4991-b123-f8d64976c92e",
      "created_at": "2022-10-13T20:06:29.276Z",
      "updated_at": "2022-10-13T20:06:29.276Z",
      "status": "approved",
      "from_participant_code": "PLAT01",
      "from_account_group": "PLAT01",
      "from_account_label": null,
      "to_participant_code": "CUST01",
      "to_account_group": "PLAT01",
      "to_account_label": null,
      "amount": "1.00",
      "movement_id": null,
      "admin_transfer": false,
      "asset": "USD"
      }
      }
  • Example Error Response (duplicate client_transfer_id used):
    • {
      "error": true,
      "message": "Request does not contain an unique client_transfer_id"
      }

       

*New fields in bold