Create refund

Create Refund

post

Allows for the creation of a full or partial refund for a previously completed deposit.

• For credit card deposits, the refund is processed to the same card, requiring only deposit identification.

• For other payment methods, beneficiary bank account details are necessary.

• Multiple partial refunds can be issued for a single deposit, provided the total refunded amount does not exceed the original deposit amount.

Header parameters

Content-TypestringRequired

Media type of the body sent to the API.

Default: application/json

X-Datestring · date-timeRequired

ISO8601 Datetime with Timezone (e.g., 2023-05-27T10:00:00Z).

X-LoginstringRequired

Merchant X-Login API Key.

AuthorizationstringRequired

Authorization control hash, calculated as explained in the onekeypayments documentation.

X-Idempotency-KeystringOptional

Unique idempotency key to prevent duplicate processing of the same request.

Body

application/json

deposit_idintegerRequired

onekeypayments deposit_id. It is obtained when creating the deposit. Must be a valid deposit_id of a completed deposit.

Example: 300533646

invoice_idstring · max: 128Required

The invoice_id you sent while creating the deposit or the merchant_invoice_id auto-generated by onekeypayments. Must be a valid invoice_id of a completed deposit.

Example: newIUnit45328731

amountnumber · doubleOptional

Amount to refund. Positive, up to 2 decimal places. Must be equal to or smaller than the deposit amount. If not sent, a full refund is assumed.

Example: 100

commentsstring · max: 200Optional

Optional comments about the refund.

Example: Test refund over v3

notification_urlstring · uri · max: 2048Optional

Valid HTTPS URL (URI) used to send asynchronous notifications about the refund's status changes.

Example: https://webhook.site/url

Responses

200

Refund request accepted and processing initiated, or completed synchronously (for some credit card refunds). The response structure might be more detailed for synchronously processed credit card refunds.

application/json

400

Error in the request, such as invalid amount or missing bank account information.

application/json

401

Unauthorized access. Indicates an issue with authentication credentials (X-Login, X-Date, Authorization).

application/json

404

Resource not found, typically meaning the specified deposit_id or invoice_id does not correspond to an existing deposit.

application/json

post

/v3/refunds

HTTPcURLJavaScriptPython

POST /v3/refunds HTTP/1.1
Host: api-stg.onekeypayments.com
X-Date: 2026-03-03T04:02:58.923Z
X-Login: text
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 280

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

Example request for a CASH method refundExample request for a CREDIT CARD refund (bank_account not needed)

{
  "refund_id": "168284"
}