Refund Creation Endpoint

Create refunds requests from a completed deposit

post
https://api-stg.directa24.com
/v3/refunds
Refund Creation
Description
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.
​
Refunds Request
In order to start creating refunds, you need to:
1.Send the request with POST method.
2.Use the headers described here.
3.Specify a valid deposit_id and invoice_id related to the deposit to be refunded.
4.Send the Authorization header calculated like for deposits, as explained here.
5.Send the body of the request as JSON.
​
Example Request
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;
​
​
​
Request fields description
Field
Format
Description
Validations
deposit_id
Integer
D24 deposit_id. It is obtained when creating the deposit​
Valid deposit_id of a completed deposit
invoice_id
String (max length: 128)
The invoice_id you sent while creating the deposit or the merchant_invoice_id auto-generated by us
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
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.​
​Bank Codes API​
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​
Account types
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
Example Response
CASH Success Response Example
{
    "refund_id": 168284
}
CASH Success Response Fields
Field
Format
Description
refund_id
Integer
ID of the refund on D24 end. Store this ID for future checks of its status​
​
​
CREDIT CARD Responses Example
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.
​
Error Responses Example
// 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​
description
String
Description of the error
type
String
Type of the error. Click here to check all the possible error types for refund​
​
​
​

Country States Codes Endpoint

Notifications

Last modified 1mo ago

Field	Format	Description	Validations
`deposit_id`	Integer	D24 `deposit_id`. It is obtained when creating the deposit	Valid `deposit_id` of a completed deposit
`invoice_id`	String (max length: 128)	The `invoice_id` you sent while creating the deposit or the `merchant_invoice_id` auto-generated by us	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. 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.	Bank Codes API
`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

`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