Handling Timeouts Via API

When using our APIs, and you experience a timeout, quidpay has built a system for you to handle this gracefully. Please see below on how to do that.

NB: Timeouts happen when a request takes to long to provide respond or you get a 5xx error calling the endpoints, typically our window before we return a timeout response is 25 Seconds

Sample response when there is a timeout:

{
  "status": "error",
  "message": "No Message",
  "data": {
    "code": "FLW_ERR",
    "message": "No Message",
    "err_tx": {
      "id": 60335,
      "chargeResponseCode": "NR",
      "chargeResponseMessage": "No Message",
      "status": "failed",
      "merchantbearsfee": 1,
      "appfee": 96.25,
      "merchantfee": 0,
      "charged_amount": 4500.00
    }
  }
}

What do you need to do when you get this ?

You need to ensure you start passing a query string use_polling=1 in your charge and validate/validatecharge endpoint like this:

https://ravesandboxapi.flutterwave.com/flwv3-pug/getpaidx/api/charge?use_polling=1

What happens when you pass the query params ?

You get a response that looks like this:

{
  "status": "success",
  "message": "LONG-REQ",
  "data": {
    "ping_url": "http://localhost:9329/flwv3-pug/getpaidx/api/requests/RCORE_CHREQ_529B140C1A06B38AD413",
    "message": "The request is taking too long. Please poll the ping_url to get response",
    "REQUEST": "RCORE_CHREQ_529B140C1A06B38AD413",
    "wait": 7468
  }
}

Okay I just got that response what does it allow me do ?

The response expects that you POLL the ping_url returned at your own intervals to get a success or failure response.

NB: "wait": 7468, is the advised wait time before you should start polling. Could be used in setTimeout or interval or delay time for cron based systems.

I have started polling what response should I expect ?

Once we have a success or failure response we return a response that looks like this:

{
  "status": "success",
  "message": "REQSPONSE",
  "data": {
    "id": 61,
    "reqid": "RCORE_CHREQ_17F0B216FD488F229EA0",
    "status": "completed",
    "response": "{\"code\":\"FLW_ERR\",\"message\":\"Sorry that account number is invalid. Please check and try again\",\"err_tx\":{\"id\":83146,\"flwRef\":\"ACHG-1511212902957\",\"chargeResponseCode\":\"RR\",\"chargeResponseMessage\":\"Sorry that account number is invalid. Please check and try again\",\"status\":\"failed\",\"merchantbearsfee\":0,\"appfee\":\"10.0736\",\"merchantfee\":\"0\",\"charged_amount\":\"330.07\"},\"is_err\":1}",
    "createdAt": "2017-11-20T21:21:44.000Z",
    "updatedAt": "2017-11-20T21:21:57.000Z",
    "deletedAt": null,
    "response_parsed": {
      "code": "FLW_ERR",
      "message": "Sorry that account number is invalid. Please check and try again",
      "err_tx": {
        "id": 83146,
        "flwRef": "ACHG-1511212902957",
        "chargeResponseCode": "RR",
        "chargeResponseMessage": "Sorry that account number is invalid. Please check and try again",
        "status": "failed",
        "merchantbearsfee": 0,
        "appfee": "10.0736",
        "merchantfee": "0",
        "charged_amount": "330.07"
      },
      "is_err": 1
    }
  }
}

If we still don't have a success or failure response we return a response that looks like this:

{
  "status": "success",
  "message": "REQSPONSE",
  "data": {
    "id": 61,
    "reqid": "RCORE_CHREQ_17F0B216FD488F229EA0",
    "status": "pending",
    "response": null,
    "createdAt": "2017-11-20T21:21:44.000Z",
    "updatedAt": "2017-11-20T21:21:44.000Z",
    "deletedAt": null,
    "response_parsed": null
  }
}

Why should I do this

This helps you handle timeouts gracefully. Timeouts happen in payment systems because of the deep level of connections within systems and in some cases dependence on outer systems. Imagine a timeout happens when your customer is trying to pay, we send you the response above and you can do this:

Cut the session and inform them you would update the status while you poll at the back.

This would mean you have prevented your customers from experiencing cases where they are debited but value not given because your system did not plan for such cases.

And immediately you get the status you can notify your customer, building trust and handling timeouts gracefully.

Do I still need to requery when I get the final response from the ping url ?

Yes you do.