Reverse a payment

Learn how to reverse a payment with the Dojo API.

Use a reversal if you need to cancel a payment, for example if a customer has requested a payment to be canceled. You can reverse the full payment amount only.

Reversal scenarios

You can reverse a payment in the following scenarios:

State	captureMode:Auto	captureMode:Manual
Created
Authorized	N/A
Captured

*   If reversed within 7 days of the original payment date.

* * If reversed on the same calendar day as the original payment date.

info

• Reversing a payment won't work in any other state.
• Once the reversal time limit expires, the payment can only be refunded.
• Payments that were captured in captureMode:Manual can only be refunded, and not reversed.

If you want to reverse a payment using the Dojo for Merchants App, see Reversing online checkout transactions.

Reverse using the Dojo API

To reverse a payment, use the endpoint below:

POST /payment-intents/{paymentIntentId}/reversal

In your request, include:

• paymentIntentId: This identifies the payment being reverse.

For the full API specification, see the reference.

Request example

The next example below shows how you would reverse the payment intent pi_pT08VyWG3EC_HQB4NBVliA.

cURL

# The sandbox API key passed in 'authorization' is public.
# Don't submit any personally identifiable information in any requests made with this key.
# Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
# for secure testing.

curl -v --request POST \
  --url https://api.dojo.tech/payment-intents/<paymentIntentId>/reversal \
  --header 'Authorization: Basic <your_api_key>' \
  --header 'Version: 2024-02-05'

PowerShell

# The sandbox API key passed in '$publicSandboxKey' is public.
# Don't submit any personally identifiable information in any requests made with this key.
# Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
# for secure testing.

$publicSandboxKey = "sk_sandbox_c8oLGaI__msxsXbpBDpdtwJEz_eIhfQoKHmedqgZPCdBx59zpKZLSk8OPLT0cZolbeuYJSBvzDVVsYvtpo5RkQ"

# Replace <payment_intent_id> with ID of payment intent you want to reverse.
Invoke-WebRequest `
    -Uri 'https://api.dojo.tech/payment-intents/<paymentIntentId>/reversal' `
    -Method POST `
    -Headers @{
        "Version" = "2024-02-05"
        "Authorization" = "Basic $publicSandboxKey"
    }
    -ContentType 'application/json'

Python

# The sandbox API key passed in 'authorization' is public.
# Don't submit any personally identifiable information in any requests made with this key.
# Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
# for secure testing.

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = {
    'Version': "2024-02-05",
    'Authorization': "Basic <your_api_key>"
    }

conn.request("POST", f"/payment-intents/{paymentIntentId}/reversal", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

conn.close()

C#

// The sandbox API key passed in 'ApiKeyClientAuthorization' is public.
// Don't submit any personally identifiable information in any requests made with this key.
// Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
// for secure testing.

var reversalClient = new ReversalClient(new HttpClient(), new ApiKeyClientAuthorization("<your_api_key>"));
var result = await reversalClient.CreateAsync("<paymentIntentId>");

PHP

<?php
// The sandbox API key used in this example is public.
// Don't submit any personally identifiable information in any requests made with this key.
// Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
// for secure testing.

namespace Test;
require_once "vendor/autoload.php";

use Dojo_PHP\ApiFactory;

$apiKey = "<your_api_key>";
$api = ApiFactory::createReversalApi($apiKey);

$pi = $api->reversalCreate(\Dojo_PHP\API_VERSION, "<paymentIntentId>");

Response example

If your request is successful, the response will return information about the reversal.

{
  "message": "reverse for the order 3443",
  "reversalId": "rvs_g8mCx87TykeQ6BOXqxZ9NQ"
}

Cancel a reverse

Once created, a reversal can't be canceled. You cannot reverse a reversal. You will have to create a new payment intent, instead.