Refund a payment

Find out how to refund a payment using the Dojo API.

tip

This endpoint allows you to refund a Payment Intent without the user present. If you are looking for face-to-face refunds, please navigate to Terminal Sessions.

Refunds return money to customers. A customer that returns a purchase needs a refund. You can refund the full amount, part of the amount, or make several partial refunds, as long as their total doesn't exceed the full original payment amount.

You can only refund a payment after it has already been captured.

If you want to use the Dojo for Business app for a refund, see Refunding online checkout transactions.

Refund using the Dojo API

To return a payment to your customer, use the endpoint below:

POST /payment-intents/{paymentIntentId}/refunds

In your request, include:

• paymentIntentId: identifies the payment being refunded.

• amount: the refund amount.

• idempotencyKey: header parameter to recognize subsequent retries of the same request. Must be unique for each new refund for the payment intent.

For the full API specification, see the API reference.

Request example

The next example below shows how you would refund 10.00 GBP.

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>/refunds \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <your_api_key>' \
  --header 'Version: 2024-02-05' \
  --header 'IdempotencyKey: 656565gfyd65' \
  --data '{
    "amount": 1000,
    "refundReason": "Demo refund",
    "notes": "Duplicate transaction"
}'

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 refund.
Invoke-WebRequest `
    -Uri 'https://api.dojo.tech/payment-intents/<paymentIntentId>/refunds' `
    -Method POST `
    -Headers @{
        "Version" = "2024-02-05"
        "Authorization" = "Basic $publicSandboxKey"
        "IdempotencyKey" = "656565gfyd65"
    } `
    -ContentType 'application/json' `
    -Body '{
        "amount": 1000,
        "refundReason": "Demo refund",
        "notes": "Duplicate transaction"
    }'

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")

payload = "{\"amount\":1000,\"refundReason\":\"Demo refund\",\"notes\":\"Duplicate transaction\"}"

headers = {
    'Content-Type': "application/json",
    'IdempotencyKey': "656565gfyd65",
    'Version': "2024-02-05",
    'Authorization': "Basic <your_api_key>"
    }

conn.request("POST", f"/payment-intents/{paymentIntentId}/refunds", payload, 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 refundsClient = new RefundsClient(new HttpClient(), new ApiKeyClientAuthorization("<your_api_key>"));
refundsClient.CreateAsync("<paymentIntentId>", "656565gfyd65", new CreateRefundRequest() { Amount = 50, Notes = "Demo refund", RefundReason = "Duplicate transaction" });

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;
use Dojo_PHP\Model\CreateRefundRequest;

$apiKey = "<your_api_key>";
$refundApi = ApiFactory::createRefundsApi($apiKey);

$refundRequest = new CreateRefundRequest(["amount" => 50, "notes" => "Demo refund", "refund_reason" => "Duplicate transaction"]);
$refundApi->refundsCreate(\Dojo_PHP\API_VERSION, "<paymentIntentId>", "656565gfyd65", $refundRequest);

Response example

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

{
  "message": "refund for the order 3443",
  "refundId": "rfnd_g8mCx87TykeQ6BOXqxZ9NQ"
}

Cancel a refund

Once created, the refund can't be canceled. As an option, you can create a new payment intent instead of the one that was refunded.