Exirom Payment API Documentation

POST /api/v1/refunds/card

Refund a previously successful card payment (full or partial). The refund is linked to the original transaction via transactionId. Note: refunds are currently supported for card payments only — APM refunds are not available.

Guide: Initiating a Refund — conceptual walkthrough, flow diagrams, and integration patterns.

#Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer {token}` — see Authentication

#Request Body Parameters

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for the request. Used for idempotency — if you retry with the same `requestId`, the system will return the original response instead of processing a duplicate.
`mid`	String	Yes	Merchant account ID. Identifies which merchant account the transaction is associated with.
`transactionId`	Integer	Yes	Unique transaction identifier assigned by Exirom. Use this ID to query status, retrieve info, or reference the transaction in support requests.
`amount`	String	Yes	Transaction amount as a decimal string in major currency units (e.g. `"10.00"` = ten dollars). Values with more than two decimal places are automatically rounded.
`reason`	String	Yes	Reason for the refund (e.g. `customer_request`, `duplicate`, `fraudulent`). Stored for reporting and reconciliation.
`callbackUrl`	String	No	Server-to-server webhook URL. Exirom sends a POST with the final transaction result to this URL. See Webhook Callbacks.
`metadata`	Map<String, String>	No	Arbitrary key-value pairs for your own use (e.g. order reference, campaign ID). Returned unchanged in responses and callbacks.

#Response

Field	Type	Description
`refundId`	String	Unique identifier for the refund transaction.
`transactionStatus`	String (NEW, PENDING, FAILED, REFUNDED, CUSTOMER_VERIFICATION, ...)	Current status of the transaction. See Transaction Status Guide for the full lifecycle.
`declineCode`	Integer	Numeric code indicating the reason for a decline. Only present when the transaction is `FAILED`. See Decline Codes Reference.
`paymentType`	String (CARD)	Payment type identifier: `CARD` for card transactions, `APM` for alternative payment methods.

{
  "requestId": "req_abc123",
  "mid": "merchant_123",
  "transactionId": 12345,
  "amount": "100.00",
  "reason": "customer_request",
  "callbackUrl": "https://yourserver.com/callback",
  "metadata": {
    "key1": "value1"
  }
}

{
  "refundId": "example_refundId",
  "transactionStatus": "NEW",
  "declineCode": 12345,
  "paymentType": "CARD"
}

Idempotency: The requestId field ensures idempotent processing. If you retry a request with the same requestId, the original response is returned without reprocessing.

#Error Responses

HTTP Status	Description
`400`	Bad Request — missing or invalid parameters. Check the response body for field-level details.
`401`	Unauthorized — missing, expired, or invalid bearer token. Re-authenticate via `POST /api/v1/auth`.
`404`	Not Found — the requested resource does not exist.
`500`	Internal Server Error — an unexpected error occurred. Retry with exponential backoff.

curl -X POST https://sandbox.api.exirom.com/api/v1/refunds/card \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
  "requestId": "req_abc123",
  "mid": "merchant_123",
  "transactionId": 12345,
  "amount": "100.00",
  "reason": "customer_request",
  "callbackUrl": "https://yourserver.com/callback",
  "metadata": {
    "key1": "value1"
  }
}'

#Try It

SandboxTry it

https://sandbox.api.exirom.com/api·Production URL: contact your account manager

Auth Token

Example

Request Body