--- updatedAt: 2026-09-04T11:23:27.000Z agentTools: projectIndex: https://docs.us.zip.co/llms.txt --- # /orders/{orderId}/refund Sandbox (Testing): https://gateway.sand.us.zip.co/orders/{orderId}/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. ```json Success Message { “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. ```json Success Message { “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. ```json Failure Message { “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" } ``` # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "gateway-api-1", "version": "1.0" }, "servers": [ { "url": "https://gateway.us.zip.co" } ], "components": { "securitySchemes": { "sec0": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://example.com/oauth2/token", "scopes": {} } } } } }, "security": [ { "sec0": [] } ], "paths": { "/orders/{orderId}/refund": { "post": { "summary": "/orders/{orderId}/refund", "description": "Sandbox (Testing): https://gateway.sand.us.zip.co/orders/{orderId}/refund\n\nRefunds 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.\n\nDefault sync value is false for asynchronous behavior.\n\nIf you are a pay-on-ship/DFC merchant, you can only apply up to your captured amount.", "operationId": "ordersorderidrefund", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "sync", "in": "query", "schema": { "type": "boolean" } }, { "name": "QP-Territory", "in": "header", "description": "Territory of the request (US)", "required": true, "schema": { "type": "string" } }, { "name": "X-QP-Signature", "in": "header", "description": "The signature for merchant validation", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId", "currency", "amount", "merchantReference" ], "properties": { "merchantId": { "type": "string", "description": "Gets or sets the MerchantId" }, "currency": { "type": "string", "description": "Gets or sets the Currency of the capture" }, "amount": { "type": "number", "description": "Gets or sets the Amount of the capture", "format": "double" }, "merchantReference": { "type": "string", "description": "Gets or sets the Merchant Reference of the capture" }, "callbackUrl": { "type": "string", "description": "Gets or sets the url to callback with the refund result" }, "test": { "type": "boolean", "description": "Gets or sets a value indicating whether this is a test order" }, "metadata": { "type": "object", "description": "Gets or sets optional metadata associated with this capture", "properties": {} } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"timestamp\": \"2021-12-01T16:35:29.632Z\",\n \"merchantId\": \"44444444-4444-4444-4444-444444444444\",\n \"orderId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"currency\": \"string\",\n \"amount\": 0,\n \"merchantReference\": \"string\",\n \"test\": true,\n \"success\": true,\n \"message\": \"string\",\n \"metadata\": {\n \"additionalProp\": \"string\"\n },\n \"operation\": \"string\"\n}" } }, "schema": { "type": "object", "properties": { "timestamp": { "type": "string", "example": "2021-12-01T16:35:29.632Z" }, "merchantId": { "type": "string", "example": "44444444-4444-4444-4444-444444444444" }, "orderId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "currency": { "type": "string", "example": "string" }, "amount": { "type": "integer", "example": 0, "default": 0 }, "merchantReference": { "type": "string", "example": "string" }, "test": { "type": "boolean", "example": true, "default": true }, "success": { "type": "boolean", "example": true, "default": true }, "message": { "type": "string", "example": "string" }, "metadata": { "type": "object", "properties": { "additionalProp": { "type": "string", "example": "string" } } }, "operation": { "type": "string", "example": "string" } } } } } } }, "deprecated": false, "security": [] } } }, "x-readme": { "headers": [], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```