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

Synchronous response

{
  "refund_id": "80000001",
  "deposit_id": 300533647,
  "merchant_invoice_id": "newIUnit45328732",
  "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"
  }
}

Asynchronous response

In case of receiving IN_PROGRESS status for a card deposit refund, we will notify to the notification_url when the refund status change. Afterwards you should perform an additional Refund status check

For more information please visit the API Reference Get refund status

{
  "refund_id": "80000001",
  "deposit_id": 300533647,
  "merchant_invoice_id": "newIUnit45328732",
  "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"
  }
}

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_id": "80000001"
}

---

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

{
  "deposit_id": 80000001,
  "merchant_invoice_id": "newIUnit45328732",
  "status": "COMPLETED",
  "amount": 505.95
}

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