GuidesAPI Reference
API Reference

/orders/{orderId}/refund

post https://gateway.us.zip.co/orders//refund

Refunds funds for the specified order and allocates them to the payment plan to apply it to the customer. If sync query parameter is set to true, replies synchronously with callback payload, otherwise, replies asynchronously on callback URL.

Default sync value is false for asynchronous behavior.

If you are a pay-on-ship/DFC merchant, you can only apply up to your captured amount.

Important Notes

Merchant Reference
A new merchantReference should be generated for each call. This allows the system to confirm if there are enough funds left on the order to be refunded. If the same merchantReference is used, you will receive a "Success”: True message, even if there are no funds available to be refunded.

When processing partial refunds, ensure that each refund has a unique reference. This requirement is necessary to prevent the error message: "Can't process a refund with duplicated merchant reference."

Please see below examples:

Example 1
merchantReference is set to 1 and there is $1 left to be refunded. A “Success”: True message is received.

{ 
    		“Amount”: 1.0, 
    		“Currency”: “USD”,
    		“MerchantId”: “44444444-4444-4444-4444-444444444444”,
    		“MerchantReference”: “1”,
    		“Operation”: “RefundOrder”,
    		“OrderId”: “ea1a9b3b-9e63-4653-af45-148ff71d73e9”, 
    		“Success”: True,
    		“Test”: False,
    		“Timestamp”: “2022-02-25T15:00:43.8391167Z"
}

Example 2

merchantReference is still set 1 but there is less than $0 left to be refunded. A “Success”: True message is received because a new merchantReference was not generated.

{ 
    		“Amount”: 1.0, 
    		“Currency”: “USD”,
    		“MerchantId”: “44444444-4444-4444-4444-444444444444”,
    		“MerchantReference”: “1”,
    		“Operation”: “RefundOrder”,
    		“OrderId”: “ea1a9b3b-9e63-4653-af45-148ff71d73e9”, 
    		“Success”: True,
    		“Test”: False,
    		“Timestamp”: “2022-02-25T15:00:43.8391167Z"
}

Example 3

merchantReference is changed to 2 and there is less than $0 left to be refunded. A “Success”: False message is now received.

{ 
    		“Amount”: 1.0, 
    		“Currency”: “USD”,
    		“MerchantId”: “44444444-4444-4444-4444-444444444444”,
    		“MerchantReference”: “2”,
    		“Operation”: “RefundOrder”,
            “Message”: “Amount to be refunded ($1.0) is greater than $0.0 available for refund.”
    		“OrderId”: “ea1a9b3b-9e63-4653-af45-148ff71d73e9”,
    		“Success”: False,
    		“Test”: False,
    	    “Timestamp”: “2022-02-25T15:00:43.8391167Z"
}
Language