Buyer Cancels Order API

---

This API is used to automatically mark the order as cancelled in AtaraPay when the buyer cancels the order from the eCommerce/ delivery app which initiates a refund to the buyer and sometimes payout to the seller, if a cancellation fee is set. Below are the fields that are to be sent via API using the POST method to the URL:

For Staging: http://test-api.atarapay.com/api/callback/order
for live: https://api.atarapay.com/api/api/callback/order

Field name	Required	Description
authtoken	Yes	This is calculated using the steps mentioned here Calculation of Auth Token
order	Yes	This is Order Number from AtaraPay
status	Yes	This is the status to be marked. Pass the value buyer_cancel
Comment	Yes	This requires the reason for the cancellation. It accepts string values

Successfull Response

{
    "status": "success",
    "message": "transaction_canceled",
    "data": {
        "id": 3021,
        "type": 1,
        "customer_id": 278,
        "beneficiary_merchant_id": 117,
        "seller_email": null,
        "seller_phone": null,
        "buyer_email": null,
        "buyer_phone": null,
        "buyer_alt_phone": null,
        "buyer_account_number": null,
        "buyer_bank_code": null,
        "shipping_fee_bearer": null,
        "escrow_fee_bearer": null,
        "tx_fee_bearer": null,
        "is_marketplace": 0,
        "shipping_cost": 0,
        "category": null,
        "product_id": "1447",
        "product_name": "Samsung Galaxy 7s",
        "product_desc": "Samsung Galaxy 7s",
        "product_cost": 400000,
        "started_by": null,
        "amount_payed": 450000,
        "amount_net": 383250,
        "payment_number": 2532,
        "payment_ref": null,
        "gateway_name": "Paystack",
        "callback_url": null,
        "comment": "Testing api  cancelling",
        "delivery_man": 0,
        "delivery_location": "Gombe, NG, 140301",
        "delivery_city": "",
        "delivery_state": "",
        "delivery_country": "",
        "product_delivery_status": 0,
        "transaction_date": "2020-06-27 07:30:54",
        "delivery_date": "0000-00-00",
        "status": {
            "id": 9,
            "title": "Canceled",
            "description": "Order or Person to Person Transaction was Canceled",
            "deleted_at": null,
            "created_at": null,
            "updated_at": null
        },
        "state": 0,
        "shipping_method": null,
        "quantity": null,
        "max_delivery_days": 7,
        "extra": null,
        "is_additional_services": null,
        "additional_service_amount": null,
        "sla": 1,
        "cancellation_fee": 20000,
        "currency": "NGN",
        "conversion_ratio": 1,
        "deleted_at": null,
        "created_at": "2020-06-27 07:30:54",
        "updated_at": "2020-06-27 08:20:14",
        "attempts": null,
        "seller_attempts": "",
        "cron_status": null,
        "sp_order_ref": 0,
        "payment": {
            "id": 2532,
            "payment_ref": "LNG-17a2cc64b84811eab96200163e619ad2",
            "amount": 450000,
            "method": "card",
            "status": "1",
            "payment_date": "2020-06-27 07:30:54",
            "gateway_response": "Successful",
            "narrative": null,
            "deleted_at": null,
            "created_at": "2020-06-27 07:30:54",
            "updated_at": "2020-06-27 07:30:54"
        },
        "additional_services": [],
        "customers": {
            "id": 278,
            "firstname": "Emeka",
            "lastname": "Adeniyi",
            "phone_number": "+2348082094382",
            "phone_number_alt": null,
            "email": "emeka.adeniyi@atarapay.com",
            "otp_date": "2019-11-14 06:32:30",
            "status": 1,
            "deleted_at": null,
            "created_at": "2019-08-28 12:17:37",
            "updated_at": "2020-01-22 21:23:05"
        },
        "delivery_men": null
    }
}

Failure Response

{
    "status": "error",
    "message": "Invalid request to Process, Order has been already Processed"
}

Sample codes

C#

var client = new RestClient("http://test-api.atarapay.com/api/callback/order");
var request = new RestRequest(Method.POST);
request.AddHeader("postman-token", "7eb16eb4-c395-7477-de57-1723ea02f1c6");
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "authtoken=__AUTH_TOKEN_CALCULATED__&order=__Order_NO__&status=rejected&comment=__reason_for_cancelation__", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://test-api.atarapay.com/api/callback/order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "authtoken=__AUTH_TOKEN_CALCULATED__&order=__Order_NO__&status=rejected&comment=__reason_for_cancelation__",
  CURLOPT_HTTPHEADER => array(
    "cache-control: no-cache",
    "content-type: application/x-www-form-urlencoded",
    "postman-token: 147f6e58-9642-81aa-fc66-e301fd7713a9"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node Js

var unirest = require("unirest");

var req = unirest("POST", "http://test-api.atarapay.com/api/callback/order");

req.headers({
  "postman-token": "43b9ee82-e77d-f0ee-645d-e658b86ad0ef",
  "cache-control": "no-cache",
  "content-type": "application/x-www-form-urlencoded"
});

req.form({
  "authtoken": "__AUTH_TOKEN_CALCULATED__",
  "order": "__Order_NO__",
  "status": "rejected",
  "comment":"_reason_for_cancelation__"
});

req.end(function (res) {
  if (res.error) throw new Error(res.error);

  console.log(res.body);
});

Possible Error Message

Error Message	Field name	Possible Reason
Invalid authtoken. Does not match any record.	authtoken	The authtoken is not calculated correctly. Please refer here for the steps Calculation of Auth Token.
No such order exists for the seller.	order	The order number sent does not belong to the seller associated with the calculated authtoken
Invalid status sent.	status	This field accept only following the values delivered,cancelled,buyer_cancel,order. Any other value passed would generate the error.
Invalid action. This request has already been processed	order	The order Id passed has been processed earlier.
Invalid action. This cancel request by the buyer isn't allowed because it's past time eligible for a refund. The seller shall however provide full product replacement. Please contact seller for same.	order	The order ID passed is in dispute and user is trying to cancel it from another app, instead of doing so from the buyer's or seller's dashboard on Atarapay.