Skip to main content
POST
/
payments
Refund or Void Payment
curl --request POST \
  --url https://api.example.com/payments \
  --header 'Content-Type: application/json' \
  --data '
{
  "data.type": "<string>",
  "data.attributes": {},
  "data.attributes.paymentType": "<string>",
  "data.attributes.parentPaymentId": "<string>",
  "data.attributes.transaction": {
    "data.attributes.transaction.amount": "<string>",
    "data.attributes.transaction.currency": "<string>"
  },
  "data.attributes.miscData": "<string>"
}
'
{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Refund amount exceeds original transaction amount"
    }
  ]
}

​
Endpoint

POST https://api.digitzs.com/payments

​
Overview

Use this endpoint to refund a payment or void an eligible transaction. The system automatically determines whether to perform a refund or void based on the transaction timing and type.
Void vs Refund: If the transaction is eligible to be voided, the system will perform a void instead of a refund. Voids are processed faster and don’t incur additional processing fees.

​
Void Eligibility

Transactions can be voided under these conditions:
  • Card Transactions: Can be voided before 11:59 PM PST on the same day the transaction was processed
  • ACH Transactions: Cannot be voided through the API. Contact support for ACH transaction issues.

​
Authentication

HeaderValueRequired
x-api-keyYour API key from onboardingYes
AuthorizationBearer {appToken}Yes
appIdYour application IDYes
Content-Typeapplication/jsonYes

​
Request Body

​
data.type
string
required
Must be "payments"
​
data.attributes
object
required
Container for payment attributes
​
data.attributes.paymentType
string
required
Must be "refund" for refund/void operations
​
data.attributes.parentPaymentId
string
required
The payment ID of the original transaction to refund or void
​
data.attributes.transaction
object
required
Transaction details
​
data.attributes.miscData
string
Optional JSON string with refund reason or additional metadata

​
Example Request - Full Refund

{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "refund",
      "parentPaymentId": "pay_abc123xyz",
      "transaction": {
        "amount": "2500",
        "currency": "USD"
      },
      "miscData": "{\"reason\":\"customer_request\",\"notes\":\"Item damaged\"}"
    }
  }
}

​
Example Request - Partial Refund

{
  "data": {
    "type": "payments",
    "attributes": {
      "paymentType": "refund",
      "parentPaymentId": "pay_abc123xyz",
      "transaction": {
        "amount": "1000",
        "currency": "USD"
      },
      "miscData": "{\"reason\":\"partial_return\"}"
    }
  }
}

​
Response

​
Success Response (201 Created)

{
  "links": {
    "self": "https://api.digitzs.com/payments"
  },
  "data": {
    "type": "payments",
    "id": "pay_refund_xyz789",
    "attributes": {
      "paymentType": "refund",
      "parentPaymentId": "pay_abc123xyz",
      "transaction": {
        "code": "0",
        "message": "Success",
        "amount": "2500",
        "currency": "USD",
        "refundType": "void"
      }
    }
  }
}
​
data.attributes.transaction.refundType
string
Indicates whether transaction was voided ("void") or refunded ("refund")

​
Code Examples

curl -X POST https://api.digitzs.com/payments \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer your-app-token" \
  -H "appId: your-app-id" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "payments",
      "attributes": {
        "paymentType": "refund",
        "parentPaymentId": "pay_abc123xyz",
        "transaction": {
          "amount": "2500",
          "currency": "USD"
        }
      }
    }
  }'

​
Void vs Refund Comparison

FeatureVoidRefund
TimingSame day before 11:59 PM PSTAny time after settlement
Processing SpeedImmediate3-10 business days
Additional FeesNoneMay incur refund processing fees
Fund ReturnInstantly released on customer’s cardProcessed as credit to customer’s card
Transaction RecordTransaction cancelledNew refund transaction created

​
Error Responses

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Refund amount exceeds original transaction amount"
    }
  ]
}

​
Common Error Scenarios

Error: 404 Not FoundSolution: Verify the parentPaymentId is correct and the payment exists in your account.
Error: 400 Bad RequestSolution: Ensure the refund amount doesn’t exceed the original transaction amount or the remaining refundable balance.
Error: 422 Unprocessable EntitySolution: Check the payment status. If already fully refunded, no additional refunds are possible.
Error: 422 Unprocessable EntitySolution: Contact Digitzs support for ACH refund processing. ACH refunds require special handling.

​
Important Notes

ACH Transactions: Do not use this endpoint for ACH transactions. Contact Digitzs support for ACH refund assistance.
Partial Refunds: Multiple partial refunds are supported up to the original transaction amount.
Void Window: Process refunds on the same day before 11:59 PM PST to get instant voids instead of multi-day refunds.

​
Best Practices

  1. Check Timing: If same-day, consider the void window for faster processing
  2. Track Refunds: Monitor all refund transactions for reconciliation
  3. Document Reasons: Use miscData to record why refunds were issued
  4. Validate Amounts: Ensure refund amount doesn’t exceed original or remaining balance
  5. Customer Communication: Inform customers about refund processing time (instant void vs 3-10 day refund)
  6. Handle Splits: Use the split refund endpoint for split payments

​
Next Steps

Refund Split Payment

Learn how to refund split payments

Get Payment Status

Check refund status