# Refund Creation Endpoint ## Refund Creation `POST` `https://api-stg.onekeypayments.com/v3/refunds` This endpoint allows you to create a full or a partial refund over a completed deposit. #### Headers | Name | Type | Description | | ----------------- | ------ | -------------------------------------------------------- | | Content-Type | string | `application/json` | | X-Date | string | ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ` | | X-Login | string | Merchant X-Login API Key | | Authorization | string | Authorization control hash | | X-Idempotency-Key | string | Unique idempotency key | #### Request Body | Name | Type | Description | | ----------------- | ------- | ------------------------------------------------------------------------------------------------------ | | deposit\_id | integer | Directa24 `deposit_id`. It is obtained when creating the deposit | | invoice\_id | string | The `invoice_id` you sent while creating the deposit or the `merchant_invoice_id` auto-generated by us | | amount | number | Amount to refund. If none is sent, the full deposit amount is assumed | | bank\_account | object | Object containing the information of the beneficiary. Not needed for credit cards | | comments | string | Commentaries about the refund, if any | | notification\_url | string | HTTPS URL used to send the notifications about refund's change of status | {% tabs %} {% tab title="200 Refund created successfully" %} ```java { "refund_id": 168284 } ``` {% endtab %} {% tab title="400 Error in the request" %} ```java { "code": 802, "description": "Amount to refund not valid", "type": "INVALID_AMOUNT_TO_REFUND" } ``` {% endtab %} {% tab title="404 Deposit not found" %} ```java { "code": 208, "description": "Resource not found", "type": "RESOURCE_NOT_FOUND" } ``` {% endtab %} {% endtabs %} ## Description The **`refunds`** endpoint allows you to create a **full r**efund over a Credit Card deposit in **completed** state or **full/partial** refunds over other payment methods' deposits in **completed** state. In the case of credit cards, since the refund will be processed to the same card, all you need to send are the fields to identify the deposit. In the case of other payment methods where we don't have the account of the payer, you need to send the beneficiary's ID, bank account details and bank code retrieved with the[ Endpoint for Bank Codes.](https://apidocs.onekeypayments.com/api-documentation/cashouts-api/endpoints/cashout-bank-codes) You can create as many refunds as needed over a completed deposit, as long as the total amount of those refunds doesn't exceed the original amount deposited. ## Refunds Request In order to start creating refunds, you need to: 1. Send the request with **POST** method. 2. Use the headers described [here](https://apidocs.onekeypayments.com/api-documentation/technical-and-security-aspects#headers). 3. Specify a valid `deposit_id` and `invoice_id` related to the deposit to be refunded. 4. Send the Authorization header calculated in the same way than for deposits, as [explained here](https://apidocs.onekeypayments.com/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature). 5. Send the body of the request as JSON. ## Example Request {% tabs %} {% tab title="cURL" %} ```java // CASH Method: curl --location --request POST 'https://api-stg.onekeypayments.com/v3/refunds' \ --header 'X-Login: {{X-Login}}' \ --header 'X-Date: {{X-Date}}' \ --header 'Authorization: {{Authorization}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "deposit_id": 300533646, "invoice_id": "newIUnit45328731", "amount": "100", "bank_account": { "beneficiary": "Carlos Ramirez", "bank_code": 1, "branch": "9283", "account_number": "18293435", "account_type": "SAVING" }, "comments": "Test refund over v3", "notification_url": "https://webhook.site/url" }' // CREDIT CARD method: curl --location --request POST 'https://api-stg.directa24.com/v3/refunds' \ --header 'X-Login: {{X-Login}}' \ --header 'X-Date: {{X-Date}}' \ --header 'Authorization: {{Authorization}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "deposit_id": 300533647, "invoice_id": "newIUnit45328732", "comments": "Test CREDIT CARD refund over v3", "notification_url": "https://webhook.site/url" }' ``` {% endtab %} {% tab title="JAVA" %} ```java import java.io.*; import okhttp3.*; public class main { public static void main(String []args) throws IOException{ OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"deposit_id\": 300533646,\n \"invoice_id\": \"newIUnit45328731\",\n \"amount\": \"100\",\n \"bank_account\": {\n \"beneficiary\": \"Carlos Ramirez\",\n \"bank_code\": 1,\n \"branch\": \"9283\",\n \"account_number\": \"18293435\",\n \"account_type\": \"SAVING\"\n },\n \"comments\": \"Test refund over v3\",\n \"notification_url\": \"https://webhook.site/url\"\n}"); Request request = new Request.Builder() .url("https://api-stg.onekeypayments.com/v3/refunds") .method("POST", body) .addHeader("X-Login", "{{X-Login}}") .addHeader("X-Date", "{{X-Date}}") .addHeader("Authorization", "{{Authorization}}") .addHeader("Content-Type", "application/json") .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using RestSharp; namespace HelloWorldApplication { class HelloWorld { static void Main(string[] args) { var client = new RestClient("https://api-stg.onekeypayments.com/v3/refunds"); client.Timeout = -1; var request = new RestRequest(Method.POST); request.AddHeader("X-Login", "{{X-Login}}"); request.AddHeader("X-Date", "{{X-Date}}"); request.AddHeader("Authorization", "{{Authorization}}"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"deposit_id\": 300533646,\n \"invoice_id\": \"newIUnit45328731\",\n \"amount\": \"100\",\n \"bank_account\": {\n \"beneficiary\": \"Carlos Ramirez\",\n \"bank_code\": 1,\n \"branch\": \"9283\",\n \"account_number\": \"18293435\",\n \"account_type\": \"SAVING\"\n },\n \"comments\": \"Test refund over v3\",\n \"notification_url\": \"https://webhook.site/url\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); } } } ``` {% endtab %} {% tab title="PHP" %} ```php "https://api-stg.onekeypayments.com/v3/refunds", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS =>"{\n \"deposit_id\": 300533646,\n \"invoice_id\": \"newIUnit45328731\",\n \"amount\": \"100\",\n \"bank_account\": {\n \"beneficiary\": \"Carlos Ramirez\",\n \"bank_code\": 1,\n \"branch\": \"9283\",\n \"account_number\": \"18293435\",\n \"account_type\": \"SAVING\"\n },\n \"comments\": \"Test refund over v3\",\n \"notification_url\": \"https://webhook.site/url\"\n}", CURLOPT_HTTPHEADER => array( "X-Login: {{X-Login}}", "X-Date: {{X-Date}}", "Authorization: {{Authorization}}", "Content-Type: application/json" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ### Request fields description
FieldFormatDescriptionValidations
FieldFormatDescriptionValidations
deposit_idIntegerOKP deposit_id. It is obtained when creating the depositValid deposit_id of a completed deposit
invoice_idString (max length: 128)The invoice_id you sent while creating the deposit or the merchant_invoice_id auto-generated by usValid invoice_id of a completed deposit
amountBig decimal (positive, up to 2 decimals)Amount to refund. Only used in case of partial refunds. If none is sent, a full refund will be assumedPositive. Equal or smaller than the deposit amount
bank_account[]Object[]Object containing the details where the refund should be sent to
commentsString (max length: 200)Commentaries about the refund, if anyString of up to 200 characters
notification_urlString (max length: 2048)Valid HTTPS URL used to send the notifications about refund's change of statusHTTPS URL
### `bank_account` Object | Field name | Format | Description | Validations | | ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `beneficiary` | string (max length: 255) | Beneficiary's name and last name | String of up to 255 characters | | `document_type` | string (max length: 10) | Beneficiary's document type |

Valid document type for the country of the deposit.

See validations here

| | `document` | string (max length: 30) | Beneficiary's document ID |

Valid document for the country of the deposit.

See validations here

| | `bank_code` | string (max length: 5) | Beneficiary's valid `bank_code` for the country. Use the [Bank Codes Endpoint.](https://apidocs.onekeypayments.com/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | [Bank Codes API](https://apidocs.onekeypayments.com/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | | `branch` | string (max length: 45) | Beneficiary's bank branch | String of up to 45 characters | | `account_number` | string (max length: 45) | Beneficiary's bank account number | String of up to 45 characters | | `account_type` | string (max length: 45) | Beneficiary's account type | [List of account\_type](https://apidocs.onekeypayments.com/cashouts-api/countries-validations#account-types) | #### Account types
account_typeDescription
account_typeDescription
SAVINGSavings account
CHECKINGCheckings account
VISTASalary account
MASTERMaster account
SAVING_SETJoint savings account
CHECKING_SETJoint checkings
DEFAULTDefault
## Example Response ### CASH Success Response Example ```java { "refund_id": 168284 } ``` ### CASH Success Response Fields | Field | Format | Description | | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `refund_id` | Integer | ID of the refund on OKP end. Store this ID for future [checks of its status](https://apidocs.onekeypayments.com/api-documentation/deposits-api/endpoints/refund-status-endpoint) | ### CREDIT CARD Responses Example {% tabs %} {% tab title="SUCCESS" %} ```java { "refund_id": "80000001", "deposit_id": 300604089, "merchant_invoice_id": "test766106146", "refund_info": { "type": "CREDIT_CARD", "result": "SUCCESS", "payment_method": "AE", "payment_method_name": "American Express", "amount": 505.95, "currency": "MXN", "created_at": "2021-02-05 22:10:45" } } ``` {% endtab %} {% tab title="IN PROGRESS" %} ```java { "refund_id": "80000001", "deposit_id": 300604089, "merchant_invoice_id": "test766106146", "refund_info": { "type": "CREDIT_CARD", "result": "IN_PROGRESS", "reason": "Check refund status or await its notification", "payment_method": "AE", "payment_method_name": "American Express", "amount": 505.95, "currency": "MXN", "created_at": "2021-02-05 22:10:45" } } ``` {% endtab %} {% tab title="REJECTED" %} ```java { "refund_id": "80000001", "deposit_id": 300604089, "merchant_invoice_id": "test766106146", "refund_info": { "type": "CREDIT_CARD", "result": "REJECTED", "reason": "Insufficient funds", "reason_code": "INSUFFICIENT_FUNDS", "payment_method": "AE", "payment_method_name": "American Express", "amount": 505.95, "currency": "MXN", "created_at": "2021-02-05 22:10:45" } } ``` {% endtab %} {% endtabs %} When the refund is made over a CREDIT CARD deposit, it might be (depending upon availability) completed instantaneously, and so all the details of the refund are returned. In case the result is SUCCESS, it means the refund was successfully created and the user should receive the money back into their card soon. In case the result is REJECTED, the response of the API will return two fields called `reason` and `reason_code` providing more information about the rejection reason. In case the result is IN\_PROGRESS, it means the refund will be processed asynchronously and so a notification will be sent to the `notification_url` specified at the time of creating the refund as soon as it gets completed or rejected. [Click here](https://apidocs.onekeypayments.com/api-documentation/deposits-api/endpoints/refund-creation-endpoint/notifications) for more information about the notifications of the refunds. ### Error Responses Example ```java // Invalid amount to refund. The amount is bigger than the deposit or // it has been already refunded { "code": 802, "description": "Amount to refund not valid", "type": "INVALID_AMOUNT_TO_REFUND" } // The object_bank account needs to be sent { "code": 804, "description": "Missing bank account information", "type": "MISSING_BANK_ACCOUNT" } // The deposit_id and/or the merchant_invoice_id didn't belong to a deposit { "code": 208, "description": "Resource not found", "type": "RESOURCE_NOT_FOUND" } ``` ### Error Responses Fields | Field | Format | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Integer | Error code. [Click here to check all the possible error codes for refund](https://apidocs.onekeypayments.com/api-documentation/api-codes#refund-error-codes) | | `description` | String | Description of the error | | `type` | String | Type of the error. [Click here to check all the possible error types for refund](https://apidocs.onekeypayments.com/api-documentation/api-codes#refund-error-codes) | �