Menu
Language

Reversals

Step 1: Obtain an application access token

Your application will need to exchange its client_id, client_secret, and grant_type=client_credentials for an application access token. With this token, you can then make API requests to the Kopo Kopo API.

Step 2. Initiate a reversal request

Initiate reversals for incoming transactions made within the last 30 days. The request payload will need to include transaction_reference, reason, callback_url and metadata which is optional.

POST https://sandbox.kopokopo.com/api/api/v2/reversals
Content-Type: application/json
Accept: application/json
Authorization: Bearer <AccessToken>
User-Agent: "<product>/<product-version> <comment>"

{
  "transaction_reference": "TQ2L262026",
  "reason": "Erroneous payment",
  "metadata": {
    "reversalTicket": "#1283833"
  },
  "_links": {
    "callback_url": "https://callback_to_your_app.your_application.com"
  }
}

HTTP/1.1 201 Created
Location: https://sandbox.kopokopo.com/api/v2/reversals/247b1bd8-f5a0-4b71-a898-f62f67b8ae1c

#   Using K2Connect - https://github.com/kopokopo/k2-connect-ruby (Recommended)
reversal_params = {
  transaction_reference: "Y7T2990R11",
  reason: "Erroneous payment",
  metadata: {
    order_no: "ORD192832",
  },
  callback_url: "https://example.com/callback",
}
k2_reversal = K2ConnectRuby::K2Entity::Reversal.new("your_access_token")
k2_reversal.initiate_reversal(reversal_params)

k2_reversal.reversal_location_url # https://sandbox.kopokopo.com/api/v2/reversals/f6d21ac6-0403-4979-9657-6cfd534f74d9

const ReversalService = K2.ReversalService

const reversalOpts = {
  transactionReference: "transaction_reference",
  reason: "reason",
  callbackUrl: "https://8650bfeddc80.ngrok.io/reversals/result",
  metadata: {
    notes: "Sample Reversal transaction",
    customId: "custom123"
  },
  accessToken: "access_token",
};

ReversalService
  .initiateReversal(reversalOpts)
  .then(response => {
    console.log(response) // => 'https://sandbox.kopokopo.com/api/v2/reversals/cc438b3e-ecf0-4600-b9cc-edba32ae7019'
  })
  .catch(error => {
    console.log(error)
  })

#  Using Kopo Kopo Connect - https://github.com/kopokopo/k2-connect-python (Recommended)
import k2connect

reversal_service = k2connect.Reversals(access_token=access_token)

request_payload = {
  "transaction_reference": "TQ2L262026",
  "reason": "Erroneous payment",
  "metadata": {
    "reversalTicket": "#1283833"
  },
  "callback_url": "https://callback_to_your_app.your_application.com",
}
reversal_resource_location_url = reversal_service.initiate_reversal(request_payload)

//  Using Kopo Kopo Connect - https://github.com/kopokopo/k2-connect-php (Recommended)
$reversalService = $K2->ReversalService();

$reversalOptions = [
  "transactionReference" => "TQ2L262026",
  "reason" => "Erroneous payment",
  "metadata" => [
    "reversalTicket" => "#1283833",
  ],
  "callbackUrl" => "https://dummy_callback_url/reversal_result",
  "accessToken" => "myRand0mAcc3ssT0k3n",
];

$response = $reversalService->initiateReversal($reversalOptions);
print_r($response); // Array([status] => success, [location] => https://sandbox.kopokopo.com/api/v2/reversals/3de7b55a-61b9-4426-9c84-6fdcb34c191e)

// Not Supported
// This feature is not currently available in the Flutter SDK.
// Please use one of the other SDKs (PHP, Ruby, Python, NodeJs) or the REST API.

When the Reversal Request is successfully received, you will receive the Reversal Request URL in the location header. Kopo Kopo will then process the Reversal Request and the result will be sent asynchronously to the callback URL specified.

Step 3: Receive and process the Reversal Request Result

Upon a successful request an HTTP Status 201 will be returned and the location HTTP Header will contain the URL of the newly created Reversal API Request. The results and status of the request will be posted back to the Callback URL that you specified in Step 2. Your endpoint needs to be a secure endpoint protected with TLS (HTTPS).

Example Reversal Request Result payload when reversal request fails.

{
  "data":{
    "id":"c5486bd6-54c5-4d38-9e8a-e5a3597cd704",
    "type":"reversal",
    "attributes":{
      "status":"Processed",
      "created_at":"2025-11-24T13:11:13.255+03:00",
      "transaction_reference":"8b275328-3b33-4144-9163-b2badbfb5de3",
      "reason":"Testing Reversals",
      "reversal_bulk_payment":{
        "amount":"1300.0",
        "status":"Cancelled",
        "origination_time":"2025-11-24T13:01:18.000+03:00",
        "transaction_reference":null
      },
      "errors":null,
      "metadata":{
        "name":"Test"
      },
      "_links":{
        "callback_url":"https://your_callback_url.com/",
        "self":"https://sandbox.kopokopo.com/api/v2/reversals/c5486bd6-54c5-4d38-9e8a-e5a3597cd704"
      }
    }
  }
}

Example Reversal Request Result payload when reversal request is successful.

After a reversal has been processed, a reversal result will be posted asynchronously to the callback URL specified in the reversal API request.

{
  "data": {
  "id":"67b1bb87-b89b-4366-93c9-a2bb6944ec99",
  "type":"reversal",
  "attributes":{
    "status":"Processed",
    "created_at":"2025-10-31T16:32:54.952+03:00",
    "transaction_reference":"059278a2-8ffe-4f31-b3b4-d6c76770c72f",
    "reason":"Testing Reversals",
    "reversal_bulk_payment":{
      "amount":"400.0",
      "status":"Transferred",
      "origination_time":"2025-10-31T12:55:18.000+03:00",
      "transaction_reference":"ce430292-899b-4543-beb8-4195875dc063"
    },
    "errors":null,
    "metadata":{
      "name":"Test"
    },
    "_links":{
      "callback_url":"https://your_callback_url.com/",
      "self":"https://sandbox.kopokopo.com/api/v2/reversals/67b1bb87-b89b-4366-93c9-a2bb6944ec99"
    }
  }
}
}

Please note if you have also subscribed for the buygoods_transaction_reversed or b2b_transaction_reversed events webhooks, you will also receive a notification of this reversal to the url specified in the webhook subscriptions.

© 2026 Kopo Kopo, Inc.