Refund

Last changes: 09-04-2023

The API method Refund enables you to perform a partial or fully refund of a captured/settled transaction.

API Parameters

Field	Description	Type	Length	Mandatory
transactionId	Unique transaction identifier.	String	36	Yes
modifiedAmount	Additional transaction data.	Object	No	Only for partial refunds.
modifiedAmount.description	Description of the i.e. the reason for the payment.	String	127	No
modifiedAmount.currencyCode	The 3-letter currency ISO-4217 code.	String	3	Only for partial refunds.
modifiedAmount.amount	Refund transaction amount.	Decimal	18,2	Only for partial refunds.
modificationId	Your unique reference for the requested modification. Used to distinguish between retry and new modification.	String	36	Yes
merchantKey	Merchnat identifier.	String	36	Yes
customReferences	For external party usage	customReferences	Object	No

The request must have the following headers:

Content-Type: application/json

Accept-Language: en-US

Origin: { Origin }

Example

Request

Path:: POST {Base URL}/payment/refund
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "merchantKey": "31928de9-1344-469f-b0eb-8e5d0fef3d21",  
  "transactionId": "933a0fab-80a0-42c5-b010-c71174f4ab32",
  "modificationId": "f7c55bb3-0002-4363-9a33-56af8d5e691e",
  "modifiedAmount": {
    "description": "SMP-Transaction-01"                    
    "amount": 25,
    "currencyCode": "EUR"
  }
}

In retry situations, please make sure to always use the same modificationID as provided in the initial request. SmartPay uses the modificationID to reccognize retrys and will always provide you this the same result as in the initial request posted with the same modificationID.

Response on success

Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
"reconciliationReferenceId": "RTEvocd9ZkGirboB8haVlw",
"description": "SMP-UAT-02*k2t3gn",
"paymentStatus": "CAPTURED",
"creationDate": "2020-12-15T14:35:44.532Z",
"lastStatusDate": "2020-12-15T14:36:45.031Z",
"transactionOverview": {
    "amount": 35.99,
    "currencyCode": "EUR",
    "transactionId": "933a0fab-80a0-42c5-b010-c71174f4ab32",
    "paymentMethod": "IDEAL"
},
"modification": {
    "modificationData": {
        "type": "REFUND",
        "modificationId": "Refund-1234",
        "reconciliationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY"
    },
    "modificationAmount": {
        "description": "SMP-Transaction-01"        
        "amount": 35.99,
        "currencyCode": "EUR"
    },
    "status": "REFUNDED",
    "creationDate": "2020-12-15T14:35:44.532Z",
    "statusHistory": [
    {
        "status": "REFUND_PENDING",
        "statusDate": "2020-12-15T14:36:44.328Z",
        "modificationAmount": {
            "amount": 35.99,
            "currencyCode": "EUR"
        }
    },
    {
        "status": "REFUNDED",
        "statusDate": "2020-12-15T14:36:44.852Z",
        "modificationAmount": {
            "amount": 35.99,
            "currencyCode": "EUR"
        }
    }
    ]
}
}

We unified the modification API responses. Please refer to the modification API response model for further details on API responses and error handling.

Document version 2.2 - 2021-05-10 - Updated description of modification reference

Document version 2.1 - 2021-03-17 - Added "description" API field

Previous

Next