# Create refund

## Create Refund

> Allows for the creation of a full or partial refund for a previously completed deposit.\
> \- For credit card deposits, the refund is processed to the same card, requiring only deposit identification.\
> \- For other payment methods, beneficiary bank account details are necessary.\
> \- Multiple partial refunds can be issued for a single deposit, provided the total refunded amount does not exceed the original deposit amount.<br>

```json
{"openapi":"3.0.0","info":{"title":"onekeypayments Refund API","version":"v3"},"servers":[{"url":"https://api-stg.onekeypayments.com","description":"Staging environment"}],"paths":{"/v3/refunds":{"post":{"summary":"Create Refund","description":"Allows for the creation of a full or partial refund for a previously completed deposit.\n- For credit card deposits, the refund is processed to the same card, requiring only deposit identification.\n- For other payment methods, beneficiary bank account details are necessary.\n- Multiple partial refunds can be issued for a single deposit, provided the total refunded amount does not exceed the original deposit amount.\n","tags":["Refunds"],"parameters":[{"in":"header","name":"Content-Type","required":true,"schema":{"type":"string","default":"application/json"},"description":"Media type of the body sent to the API."},{"in":"header","name":"X-Date","required":true,"schema":{"type":"string","format":"date-time"},"description":"ISO8601 Datetime with Timezone (e.g., 2023-05-27T10:00:00Z)."},{"in":"header","name":"X-Login","required":true,"schema":{"type":"string"},"description":"Merchant X-Login API Key."},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Authorization control hash, calculated as explained in the onekeypayments documentation."},{"in":"header","name":"X-Idempotency-Key","required":false,"schema":{"type":"string"},"description":"Unique idempotency key to prevent duplicate processing of the same request."}],"requestBody":{"required":true,"description":"Details for the refund request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"200":{"description":"Refund request accepted and processing initiated, or completed synchronously (for some credit card refunds). The response structure might be more detailed for synchronously processed credit card refunds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundSuccessResponse"}}}},"400":{"description":"Error in the request, such as invalid amount or missing bank account information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized access. Indicates an issue with authentication credentials (X-Login, X-Date, Authorization).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found, typically meaning the specified deposit_id or invoice_id does not correspond to an existing deposit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"RefundRequest":{"type":"object","required":["deposit_id","invoice_id"],"properties":{"deposit_id":{"type":"integer","description":"onekeypayments `deposit_id`. It is obtained when creating the deposit. Must be a valid `deposit_id` of a completed deposit."},"invoice_id":{"type":"string","maxLength":128,"description":"The `invoice_id` you sent while creating the deposit or the `merchant_invoice_id` auto-generated by onekeypayments. Must be a valid `invoice_id` of a completed deposit."},"amount":{"type":"number","format":"double","description":"Amount to refund. Positive, up to 2 decimal places. Must be equal to or smaller than the deposit amount. If not sent, a full refund is assumed."},"bank_account":{"$ref":"#/components/schemas/BankAccount"},"comments":{"type":"string","maxLength":200,"description":"Optional comments about the refund."},"notification_url":{"type":"string","format":"uri","maxLength":2048,"description":"Valid HTTPS URL (URI) used to send asynchronous notifications about the refund's status changes."}}},"BankAccount":{"type":"object","description":"Contains the beneficiary's bank account details. Required for refunds to bank accounts (not for credit card refunds).","required":["beneficiary","bank_code","account_number","account_type"],"properties":{"beneficiary":{"type":"string","maxLength":255,"description":"Beneficiary's full name and last name."},"document_type":{"type":"string","maxLength":10,"description":"Beneficiary's document type (e.g., CPF, DNI). Valid types depend on the country of the deposit."},"document":{"type":"string","maxLength":30,"description":"Beneficiary's document ID number. Valid document for the country of the deposit."},"bank_code":{"type":"string","maxLength":5,"description":"Beneficiary's valid `bank_code` for the country. Obtainable via the Bank Codes Endpoint."},"branch":{"type":"string","maxLength":45,"description":"Beneficiary's bank branch."},"account_number":{"type":"string","maxLength":45,"description":"Beneficiary's bank account number."},"account_type":{"type":"string","maxLength":45,"description":"Beneficiary's bank account type. Possible values include:\n- `SAVING`: Savings account\n- `CHECKING`: Checkings account\n- `VISTA`: Salary account\n- `MASTER`: Master account\n- `SAVING_SET`: Joint savings account\n- `CHECKING_SET`: Joint checkings\n- `DEFAULT`: Default account type or when the specific type is not otherwise categorized.\n","enum":["SAVING","CHECKING","VISTA","MASTER","SAVING_SET","CHECKING_SET","DEFAULT"]}}},"RefundSuccessResponse":{"type":"object","properties":{"refund_id":{"type":"string","description":"Unique ID for the created refund. This might be an integer or a string depending on the refund method."},"deposit_id":{"type":"integer","description":"onekeypayments `deposit_id`. Returned for synchronously processed credit card refunds."},"merchant_invoice_id":{"type":"string","description":"The `merchant_invoice_id`. Returned for synchronously processed credit card refunds."},"refund_info":{"$ref":"#/components/schemas/RefundInfo"}}},"RefundInfo":{"type":"object","description":"Detailed information about the refund, often provided for synchronous credit card refund processing.","properties":{"type":{"type":"string","description":"Type of refund processed."},"result":{"type":"string","description":"The outcome of the refund attempt.","enum":["SUCCESS","IN_PROGRESS","REJECTED"]},"reason":{"type":"string","description":"A textual explanation if the refund is not 'SUCCESS' (e.g., for 'REJECTED' or 'IN_PROGRESS' states)."},"reason_code":{"type":"string","description":"A codified reason for the refund status, if applicable."},"payment_method":{"type":"string","description":"Code for the payment method used (e.g., 'AE' for American Express)."},"payment_method_name":{"type":"string","description":"Full name of the payment method."},"amount":{"type":"number","format":"double","description":"The amount of the refund."},"currency":{"type":"string","description":"The currency of the refund amount (e.g., 'MXN')."},"created_at":{"type":"string","description":"Timestamp indicating when the refund was created or processed by the provider, in 'YYYY-MM-DD HH:mm:ss' format."}}},"ApiError":{"type":"object","required":["code","description"],"properties":{"code":{"type":"integer","description":"Numeric error code."},"description":{"type":"string","description":"Human-readable description of the error."},"type":{"type":"string","description":"Categorical type of the error. May not be present for all error types."}}}}}}
```