Ask us anything. We're here to help.

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

API Updates


  • 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_account_group": "PLAT01",
      "to_account_group": "PLAT01",
      "client_transfer_id": "b8aa391c-6da9-4991-b123-f8d64976c92e",
  • 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