Refund Creation Endpoint

Create refunds requests from a completed deposit

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

Request Body

{
    "refund_id": 168284
}

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

  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.

  5. Send the body of the request as JSON.

Example Request

// 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"
}'

Request fields description

bank_account Object

Account types

Example Response

CASH Success Response Example

{
    "refund_id": 168284
}

CASH Success Response Fields

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

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

Last updated