Refund Creation Endpoint

Create refunds requests from a completed deposit

Refund Creation

POST https://api-stg.directa24.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

{
    "refund_id": 168284
}

{
    "code": 802,
    "description": "Amount to refund not valid",
    "type": "INVALID_AMOUNT_TO_REFUND"
}

{
    "code": 208,
    "description": "Resource not found",
    "type": "RESOURCE_NOT_FOUND"
}

Description

The refunds endpoint allows you to create a full/partial(depending on the market) 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 total amount of those refunds doesn't exceed the original amount deposited.

Refunds Request

In order to start creating refunds, you need to:

Send the request with POST method.
Use the headers described here.
Specify a valid deposit_id and invoice_id related to the deposit to be refunded.
Send the Authorization header calculated in the same way than for deposits, as explained here.
Send the body of the request as JSON.

Example Request

// 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

Valid deposit_id of a completed deposit

invoice_id

String (max length: 128)

The invoice_id you sent while 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.

document

string (max length: 30)

Beneficiary's document ID

Valid document for the country of the deposit.

bank_code

string (max length: 5)

Beneficiary's valid bank_code for the country. Use the

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 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

CREDIT CARD Responses Example

{
    "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 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 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.

description

String

Description of the error

type

String

Type of the error.

PreviousCountry States Codes Endpoint NextNotifications

Last updated 1 month ago

Refund Creation

Headers

Request Body

Description

Refunds Request

Example Request

Request fields description

bank_account Object

Account types

Example Response

CASH Success Response Example

CASH Success Response Fields

CREDIT CARD Responses Example

Error Responses Example

Error Responses Fields

`bank_account` Object