Refund Creation Endpoint
Create refunds requests from a completed deposit
post
https://api-stg.directa24.com
/v3/refunds
Refund Creation
The
refunds
endpoint allows you to create a full refund 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.
You can create as many refunds as needed over a completed deposit, as long as the summation of those refunds doesn't exceed the deposit amount itself.
In order to start creating refunds, you need to:
- 1.Send the request with POST method.
- 2.
- 3.Specify a valid
deposit_id
andinvoice_id
related to the deposit to be refunded. - 4.
- 5.Send the body of the request as JSON.
cURL
JAVA
C#
PHP
// CASH 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": 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"
}'
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.directa24.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());
}
}
using System;
using RestSharp;
namespace HelloWorldApplication {
class HelloWorld {
static void Main(string[] args) {
var client = new RestClient("https://api-stg.directa24.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);
}
}
}
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api-stg.directa24.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;
Field | Format | Description | Validations |
deposit_id | Integer | Valid deposit_id of a completed deposit | |
invoice_id | String (max length: 128) | Valid invoice_id of a completed deposit | |
amount | Big 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 assumed | Positive. Equal or smaller than the deposit amount |
bank_account[] | Object[] | Object containing the details where the refund should be sent to | |
comments | String (max length: 200) | Commentaries about the refund, if any | String of up to 200 characters |
notification_url | String (max length: 2048) | Valid HTTPS URL used to send the notifications about refund's change of status | HTTPS URL |
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. |
document | string (max length: 30) | Beneficiary's document ID | Valid document for the country of the deposit. |
bank_code | string (max length: 5) | ||
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 |
account_type | Description |
SAVING | Savings account |
CHECKING | Checkings account |
VISTA | Salary account |
MASTER | Master account |
SAVING_SET | Joint savings account |
CHECKING_SET | Joint checkings |
DEFAULT | Default |
{
"refund_id": 168284
}
Field | Format | Description |
refund_id | Integer |
SUCCESS
IN PROGRESS
REJECTED
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
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 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 for more information about the notifications of the refunds.
// 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"
}
Field | Format | Description |
code | Integer | |
description | String | Description of the error |
type | String |