Refund a deposit

This service enables you to issue and view refunds for completed payments.

• For card deposits: The original charge is reversed, returning funds to the cardholder.

• For alternative payment methods: The customer receives a refund via a bank transfer.

Please note, a processing fee may apply to refunds.

---

For technical details please visit the API Reference Create refunds

Card deposits

Example request

Total refund

curl -L \
  --request POST \
  --url 'https://api-stg.onekeypayments.com/v3/refunds' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-25T13:13:08.220Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "deposit_id": 300533647,
    "invoice_id": "newIUnit45328732",
    "comments": "Test refund",
    "notification_url": "https://merchant.com/webhooks/onekeypayments/refunds"
  }'

Partial refund

curl -L \
  --request POST \
  --url 'https://api-stg.onekeypayments.com/v3/refunds' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-25T13:13:08.220Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "deposit_id": 300533647,
    "invoice_id": "newIUnit45328732",
    "amount": 50,
    "comments": "Test refund",
    "notification_url": "https://merchant.com/webhooks/onekeypayments/refunds"
  }'

Example response

Alternative payment methods

Example request

curl -L \
  --request POST \
  --url 'https://api-stg.onekeypayments.com/v3/refunds' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-25T13:13:08.220Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "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 response

---

Refund status

Each time that a refund changes its status we will send a webhook notification

Example refund webhook notification

{
    "refund_id": 80000001
}

Then, you will know that you should retrieve the status of the refund

Example request

curl -L \
  --url 'https://api-stg.onekeypayments.com/v3/refunds/80000001' \
  --header 'Content-Type: text' \
  --header 'X-Date: 2023-05-27T10:30:00Z' \
  --header 'X-Login: your-x-login-key' \
  --header 'Authorization: OKP-HMAC-SHA256 SignedHeaders=x-date;x-login, Signature=your_signature_hash' \
  --header 'Accept: */*'

Example response

For technical details regarding refunds status retrieval, please visit the API Reference Get refund status