Refund Request

URL: /api/v1/tx/refund/

METHOD: POST

FORMAT: JSON

DIRECTION: Integrator -> PM Gateway

Request is considered idempotent by following parameters:

  • merchantId
  • originTxId
  • merchantRefundId
  • requestId
  • amount

Request Parameters

Parameter Name

Type

Mandatory

Description
amount Numeric

Yes

 The amount to refund in currency's smallest re-presentable unit (e.g cents). No decimal placeholder .
currencyCode ASCII

Yes

3-letter ISO currency code of the transaction
description UTF-8

Yes

Description of the refund.Depending on payment or refund method, the actual outcome on the consumer’s statement varies, for instance the set of allowed characters or maximum length. The text resulting from your input value is automatically stripped of white space and truncated if it exceeds the maximum length. We may adapt the text if required e.g. for reconciliation purposes.
merchantId ASCII

Yes

Merchant ID in Elavon. Max length is 16 symbols.
merchantRefundId ASCII

Yes

 Client's Refund Identifier( Generated by Ecommerce third party provider or Terminal). Allowed characters: [a-zA-Z0-9 -]. Max length 30 symbols.
originShortTxId ASCII   Short ID of the original transaction(authorization), provided by PM. Mandatory if originTxId is not specified. Min 8 digits, max 9 digits
originTxId ASCII

Yes

 ID of the original transaction(authorization), provided by PM. Possible values : [a-zA-Z0-9 -]. Max length 36 symbols. Mandatory if originShortTxId is not specified. 
payload JSON

Yes

 Reserved for addition information to be passed. JSON formatted, key/value String. In general to be used to transfer local payment method specific data
pushStatusUrl ASCII   URL where refund status changes will be pushed. If URL is not provided, status changes will not be pushed. 
reason ASCII  

Reason for the refund :

  • TIMEOUT - the original transaction response timed out. Client initiated refund
  • ERROR - terminal/portal is unable to obtain the status of original transaction due to unknown error
  • USER - refund was requested by user.
requestId ASCII

Yes

 Any Random String/Number generated by the caller. Used for tracing purposes. Allowed characters : [a-zA-Z0-9 -]. Max length 60 symbols
systemId ASCII

Yes

Terminal ID when payment is originated from terminal. Ecommerce third party provider system id when payment originated from Ecommerce third party providererge. Max length 60.

 

 

Example Request:

JSON Encoded
{
  "requestId": "d7da6bc5-ba4f-4615-8680-a28c67b115a9",
  "merchantId": "testRandomMerchantString",
  "originTxId": "e066f47b-2f1f-49e2-a0d4-142cbed6e846",
  "originShortTxId" : "",
  "merchantRefundId": "48afcb27-8ba5-4b36-aedf-4be2a8",
  "amount":1005,
  "systemId": "systemId123",
  "currencyCode": "EUR",
    "property1": "value1",
    "property2": "value2"
  }
}

Response

Parameter Name Type Mandatory Description
status ASCII Yes

Status of Refund request. One of:

  • PENDING - refund is being processed.  This status should be treated as technical success, where all business validations has passed. The actual refund with the payment method(scheme) will be executed asynchronously. In case the status changes should be detected, getRefundStatus call can be used. 
  • DECLINED - refund failedrefundId
refundID ASCII Yes Refund identifier in PM. Always a valid refund identifier is returned. Possible values : [a-zA-Z0-9 -]. Max length 40 symbols.
merchantRefundId ASCII Yes Value of merchantRefundId set in the request.
errorMessage UTF-8 No Human readable message, up to 200 characters. Set in case of error code <> ERR_OK
error ASCII Yes Error code. Refer to possible error codes for more info.
payload JSON No Key - value json structure. Used to set payment type specific parameters.
fundState ASCII No

Define the funds status. Mandatory when status is set to SUCCEEDED.

Possible values:

  • FUNDS_RECEIVED - shopper refunded successfully
  • FUNDS_REJECTED - shopper's account is not refunded
paymentMethod ASCII Yes Local payment method used by Refund

 

Error Codes

Error Code Description
ERR_OK Processing was successful
ERR_INPUT Request parameters doesn't pass required validations
ERR_SYSTEM Unknown error. Transaction failed due to unknown reason
ERR_LOCAL_DECLINE Refund failed due to PM limitations.
ERR_REMOTE Refund processing failed in Acquirer due to unknown reason
ERR_REMOTE_DECLINE Refund was declined by remote system due to some limitations(e.g amount limit)
ERR_TX_NOT_FOUND Transaction not found

 

Example Response:

JSON Encoded
{
  "status": "DECLINED",
  "refundId": "2f139d20-7a34-4c3f-a808-c5016c21d051",
  "merchantRefundId": "48afcb27-8ba5-4b36-aedf-4be2a8",
  "errorMessage": "\"Refund failed due to... \"",
  "error": "ERR_REMOTE_DECLINE",
  "paymentMethod" :"paysera",
  "payload": {
    "property1": "value1",
    "property2": "value2"
  }
}