QRIOS API callbacks

Qrios API callback notification

User should expect notification, about every started Qrios API operation. When operation reaches final state, Qrios API sends callback to developer. During the onboarding, a developer is required to provide a callback URL which will be invoked to notify his application about an asynchronous result of an action he invoked.

Example:

Let's assume a developer has configured URL https://developer.example.com/callback as a main callback. When operation result is delivered, there should also following callback be invoked:

for success case:

POST https://developer.example.com/callback
{
  "clientId": "x97uJ23b",
  "operationId": "535bdec5-ea1c-4737-b9e2-04a9743d4227",
  "status": {
    "result": "success" 
  },
  "operation": "<<OPERATION>>",
  "<<OPERATION>>": {
    (additional data, depending on the operation type)
  }
}

HTTP 200 (OK)

That means operation has been completed successfully.

for failure case:

POST https://developer.example.com/callback
{
  "clientId": "x97uJ23b",
  "operationId": "535bdec5-ea1c-4737-b9e2-04a9743d4227",
  "status": {
    "result": "failure",
    "cause": "insufficient_balance"
  },
  "operation": "<<OPERATION_TYPE>>",
  "<<OPERATION_TYPE>>": {
    (additional data, depending on the operation type)
  }
}

HTTP 200 (OK)

We have failed completing your operation.

for unknown case:

POST https://developer.example.com/callback
{
  "clientId": "x97uJ23b",
  "operationId": "535bdec5-ea1c-4737-b9e2-04a9743d4227",
  "status": {
    "result": "unknown"
  },
  "operation": "<<OPERATION_TYPE>>",
  "<<OPERATION_TYPE>>": {
    (additional data, depending on the operation type)
  }
}

HTTP 200 (OK)

Operation final status can't be determined.

Callback schema

The callback examples above are only templates that depend on the operation type. Please refer to the specific operation documentation to check the complete schema of the callback request body.

Every operation should reach one of final states: success or failure. Failure state means, that Qrios API is sure, that commissioned operation can't be completed. For some reason processing operation may temporally fail, but Qrios API will retry attempt, or is waiting for external event. Such situation may result in unknown status, so operation hasn't been finally completed. It pretends reach success or failure shortly status, but at this moment unknown callback is sent to developer. Operation that has stuck in unknown or attempted status should be reported to Qrios team for future investigation.