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

Parameter Name Type Mandatory Description
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
merchantId ASCII Yes Merchant ID in Elavon. Max length is 60 symbols.
originTxId ASCII No 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.
originShortTxId ASCII No Short ID of the original transaction(authorization), provided by PM. Mandatory if originTxId is not specified. Min 8 digits, max 9 digits
merchantRefundId ASCII Yes Client's Refund Identifier( Generated by Converge or Terminal). Allowed characters: [a-zA-Z0-9 -]. Max length 30 symbols.
amount Numeric Yes The amount to refund in currency's smallest re-presentable unit (e.g cents). No decimal placeholder.
systemId ASCII Yes Terminal ID when payment is originated from terminal. Converge system id when payment originated from converge.Max length 60.
currencyCode ASCII Yes 3 letter ISO currency code of the transaction
description UTF-8 No 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).
payload JSON No 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 No URL where refund status changes will be pushed. If URL is not provided, status changes will not be pushed.

 

Example Request:

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

Response

Parameter Name Type Mandatory Description
status ASCII Yes

Status of Refund request. One of:

  • PENDING - refund is being processed.
  • DECLINED - refund failed
  • SUCCEEDED - refund is successful
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

 

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)

 

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",
	"payload": {
		"property1": "value1",
		"property2": "value2"
	}
}