Orders Refund

The Order Refunds API enables order or order items refund operations.

Note: All requests require an X-API-Key header with your API key.

---

1. Full Order Refund

Service Call: OrderService.RefundOrder

Refund entire order amount.

Examples

Java

import com.kodypay.grpc.ordering.v1.OrderServiceGrpc;
import com.kodypay.grpc.ordering.v1.RefundOrderRequest;
import io.grpc.ManagedChannelBuilder;
import io.grpc.Metadata;
import io.grpc.stub.MetadataUtils;
import java.util.UUID;

public class FullRefundExample {
    public static void main(String[] args) {
        Metadata metadata = new Metadata();
        metadata.put(Metadata.Key.of("X-API-Key", Metadata.ASCII_STRING_MARSHALLER), API_KEY);

        var channel = ManagedChannelBuilder.forAddress("grpc-staging.kodypay.com", 443)
                .useTransportSecurity().build();
        var client = OrderServiceGrpc.newBlockingStub(channel)
                .withInterceptors(MetadataUtils.newAttachHeadersInterceptor(metadata));

        RefundOrderRequest request = RefundOrderRequest.newBuilder()
                .setStoreId("STORE_123")
                .setOrderId("ORDER_456")
                .setReason("Wrong item shipped")
                .setIdempotencyUuid(UUID.randomUUID().toString())
                .build();

        var response = client.refundOrder(request);
        System.out.println("Refund status: " + (response.getSuccess() ? "Success" : "Failed"));
        System.out.println("Amount refunded: " + response.getAmount());
    }
}

Python

import uuid
import grpc
import kody_clientsdk_python.ordering.v1.order_pb2 as kody_model
import kody_clientsdk_python.ordering.v1.order_pb2_grpc as kody_client


def full_refund():
    # TODO: Replace this with the testing or live environment
    address = "grpc-staging.kodypay.com"
    # TODO: Replace this with your Store ID
    store_id = "c95397d7-67a6-493d-9eb0-bc9fb2db0f6f"
    # TODO: Replace this with your API key
    api_key = "API_KEY"
    # TODO: Replace this with your order ID
    order_id = "ORDER_ID"

    with grpc.secure_channel(target=address, credentials=grpc.ssl_channel_credentials()) as channel:
        client = kody_client.OrderServiceStub(channel)

        request = kody_model.RefundOrderRequest(
            store_id=store_id,
            order_id=order_id,
            reason="Wrong item shipped",
            idempotency_uuid=str(uuid.uuid4())
        )

        response = client.RefundOrder(request, metadata=[("x-api-key", api_key)])
        print(f"Refunded {response.amount}. Success: {response.success}")

if __name__ == "__main__":
    full_refund()

.NET

var channel = GrpcChannel.ForAddress("https://grpc-staging.kodypay.com");
var client = new OrderService.OrderServiceClient(channel);

var request = new RefundOrderRequest {
    StoreId = "STORE_123",
    OrderId = "ORDER_456",
    Reason = "Wrong item shipped",
    IdempotencyUuid = Guid.NewGuid().ToString()
};

var response = await client.RefundOrderAsync(request, new Metadata {
    { "X-API-Key", "API_KEY" }
});

Console.WriteLine($"Refund status: {(response.Success ? "Success" : "Failed")}");
Console.WriteLine($"Amount: {response.Amount}");

PHP

use Com\Kodypay\Grpc\Ordering\V1\OrderServiceClient;
use Com\Kodypay\Grpc\Ordering\V1\RefundOrderRequest;
use Grpc\ChannelCredentials;
use Ramsey\Uuid\Uuid;

$api_key = ''; // Put your API key

$client = new OrderServiceClient('grpc-staging.kodypay.com:443', ['credentials' => ChannelCredentials::createSsl()]);
$metadata = ['X-API-Key' => [$api_key]];

$request = (new RefundOrderRequest())
    ->setStoreId('STORE_123')
    ->setOrderId('ORDER_456')
    ->setReason('Wrong item shipped')
    ->setIdempotencyUuid(Uuid::uuid4()->toString());

list($response, $status) = $client->RefundOrder($request, $metadata)->wait();

echo "Refund status: " . ($response->getSuccess() ? "Success" : "Failed") . PHP_EOL;
echo "Amount: " . $response->getAmount() . PHP_EOL;

---

2. Order Items Refund

Service Call: OrderService.RefundItem

Refund specific items within an order.

Examples

Java

RefundItemRequest request = RefundItemRequest.newBuilder()
        .setStoreId("STORE_123")
        .setOrderId("ORDER_456")
        .addItems(RefundItem.newBuilder()
                .setOrderItemId("ITEM_789")
                .setQuantity(2)
        )
        .addItems(RefundItem.newBuilder()
                .setOrderItemId("ITEM_101")
                .setQuantity(1)
        )
        .setReason("Damaged during shipping")
        .setIdempotencyUuid(UUID.randomUUID().toString())
        .build();

var response = client.refundItem(request);
System.out.println("Partial refund processed: " + response.getSuccess());
System.out.println("Refunded amount: " + response.getAmount());

Python

items = [
    kody_model.RefundItemRequest.RefundItem(
        order_item_id="ITEM_789",
        quantity=2
    ),
    kody_model.RefundItemRequest.RefundItem(
        order_item_id="ITEM_101",
        quantity=1
    )
]

request = kody_model.RefundItemRequest(
    store_id="STORE_123",
    order_id="ORDER_456",
    items=items,
    reason="Damaged during shipping",
    idempotency_uuid=str(uuid.uuid4())
)

response = client.RefundItem(request, metadata=metadata)
print(f"Refunded {response.amount} for {len(items)} items")

.NET

var items = new List<RefundItemRequest.Types.RefundItem> {
    new() { OrderItemId = "ITEM_789", Quantity = 2 },
    new() { OrderItemId = "ITEM_101", Quantity = 1 }
};

var request = new RefundItemRequest {
    StoreId = "STORE_123",
    OrderId = "ORDER_456",
    Items = { items },
    Reason = "Damaged during shipping",
    IdempotencyUuid = Guid.NewGuid().ToString()
};

var response = await client.RefundItemAsync(request);
Console.WriteLine($"Refunded {response.Amount} for {items.Count} items");

PHP

$items = [
    (new RefundItem())
        ->setOrderItemId('ITEM_789')
        ->setQuantity(2),
    (new RefundItem())
        ->setOrderItemId('ITEM_101')
        ->setQuantity(1)
];

$request = (new RefundItemRequest())
    ->setStoreId('STORE_123')
    ->setOrderId('ORDER_456')
    ->setItems($items)
    ->setReason('Damaged during shipping')
    ->setIdempotencyUuid(Uuid::uuid4()->toString());

$response = $client->RefundItem($request, $metadata);
echo "Refund ID: " . $response->getIdempotencyUuid() . PHP_EOL;