Refund a payment

Refunds an existing payment. Requires an idempotency key to prevent duplicate refunds on retry.

Idempotency Key Benefits for Refunds

Refunds are critical financial operations where duplicates can cause serious issues. Using idempotency keys ensures:

1. Prevent duplicate refunds: Even if a request times out or fails, retrying with the same key won’t issue multiple refunds
2. Safe retries: Network failures or timeouts won’t risk creating multiple refunds
3. Consistent response: Always get the same response for the same operation

Example Request (curl)

curl -X POST \
  https://api.example.com/rest-api/v0/test-payment/pay_abc123xyz456/refund \
  -H 'Content-Type: application/json' \
  -H 'Client-Key: your-api-key' \
  -H 'Client-Secret: your-api-secret' \
  -H 'Idempotency-Key: refund_123456_unique_key'

Example Response (First Request)

{
  "id": "ref_xyz789",
  "paymentId": "pay_abc123xyz456",
  "amount": 100.00,
  "status": "succeeded",
  "timestamp": "2023-07-01T14:30:00.000Z"
}

Example Response (Duplicate Request)

The exact same response will be returned for any duplicate request with the same idempotency key, without creating a new refund.

Idempotency Key Guidelines

• Use a unique key for each distinct refund operation
• Store keys client-side to ensure you can retry with the same key if needed
• Keys expire after 24 hours by default

POST /api/v0/test-payment/{id}/refund

Refund a payment

cURL

curl --request POST \
  --url https://api.devdraft.ai/api/v0/test-payment/{id}/refund \
  --header 'idempotency-key: <idempotency-key>' \
  --header 'x-client-secret: <api-key>'

200

{
  "id": "ref_12345abcdef",
  "paymentId": "pay_12345abcdef",
  "amount": 100.5,
  "status": "succeeded",
  "timestamp": "2023-07-01T12:00:00.000Z"
}

Authorizations

x-client-secretx-client-key

x-client-secret · string · header · required

Your secret API key. Keep this secure and never expose it in client-side code.

Headers

idempotency-key · string<uuid> · required

Unique key to ensure the refund request is idempotent. If a request with the same key is sent multiple times, only the first will be processed, and subsequent requests will return the same response.

Example:

"refund_123456_unique_key"

Path Parameters

id · string · required

Payment ID to refund

Response

200

application/json

Payment refunded successfully

id · string · required

Refund ID

Example:

"ref_12345abcdef"

paymentId · string · required

Original payment ID

Example:

"pay_12345abcdef"

amount · number · required

The amount refunded

Example:

100.5

status · string · required

Refund status

Example:

"succeeded"

timestamp · string · required

Timestamp of the refund

Example:

"2023-07-01T12:00:00.000Z"