Create a Refund

When you are initiating a refund you need to provide the Refund Amount and the Merchant Transaction ID, that is automatically generated. You can change this ID by introducing your ID value.

Definition: POST /v1/payments/{id}/refunds

Where:
  • {id} – GlobalPay Payment ID

A 201 HTTP response (Created) is returned if the refund was correctly initialized.

Request:

POST https://paytest.smart2pay.com/v1/payments/4520424/refunds
Authorization: Basic MzAyMDE6KzlLZUd6S0Y3VzhTLzc5YTVSMzNZSlVnN0U3V0ZOY1piakdmekxWM2JYU25GQ095RnQ=

{
  "Refund": {
    "MerchantTransactionID": "s2ptest_gi10",
    "Amount": 100,
    "Description": "Refund Test Description"
   }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Refund": {
        "ID": 36675,
        "Created": "20190516075916",
        "MerchantTransactionID": "s2ptest_gi10",
        "OriginatorTransactionID": null,
        "InitialPaymentID": 4520424,
        "Amount": "100",
        "Currency": "EUR",
        "Description": "Refund Test Description",
        "TypeID": 5,
        "SiteID": 30201,
        "Details": null,
        "Customer": null,
        "BillingAddress": null,
        "BankAddress": null,
        "Articles": null,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "SplitID": 0
    }
}

For some payment methods to be processed correctly, depending on the type of refund, we require additional parameters, specific details, such as customer IBAN.

Please check Get information for a refund for more information on what parameters you need to send in order to initiate a specific refund.

  • A particular case is for Klarna Invoice payment method where in order to initiate a refund you will need to provide Merchant Article ID and Quantity parameters, like in the below example:

    Request:

    POST https://paytest.smart2pay.com/v1/payments/3006154/refunds
Authorization: Basic MzAyMDE6KzlLZUd6S0Y3VzhTLzc5YTVSMzNZSlVnN0U3V0ZOY1piakdmekxWM2JYU25GQ095RnQ=

{
  "Refund": {
    "MerchantTransactionID": "s2ptest_g30",
    "Amount": 980,
    "Articles": [
      {
        "MerchantArticleID": "1231",
        "Quantity": 1
      }
    ]
  }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "Refund": {
    "ID": 0,
    "Created": null,
    "MerchantTransactionID": "s2ptest_g30",
    "OriginatorTransactionID": null,
    "InitialPaymentID": 0,
    "Amount": "980",
    "Currency": null,
    "Description": null,
    "TypeID": 0,
    "SiteID": 30201,
    "Details": null,
    "Customer": null,
    "BillingAddress": null,
    "BankAddress": null,
    "Articles": [
      {
        "MerchantArticleID": "1231",
        "Name": null,
        "Quantity": 1,
        "Price": 0,
        "VAT": 0,
        "Discount": 0,
        "Type": null,
        "DiscountValue": 0
      }
    ],
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": null
    },
    "SplitID": 0
  }
}
  • A particular case is for Klarna Pay Now Standalone payment method where in order to initiate a refund you need to provide Amount and Currency parameters.
    However, the recommendation is:
    – to use a full request, where you can have the Description and the OriginatorTransactionID
    – to send the Articles: Merchant Article ID and Quantity parameters, if they have been provided in the initial payment, as shown in the example below:

    Request:

    POST https://paytest.smart2pay.com/v1/payments/6906966/refunds
Authorization: Basic MzAxOTk6OG16L0lsZkpaejIyVVhVUlFSeXRvdExQQ3pkWVJQekVmNHpyNDdBUWROWWxiUUxpTWc=
{
    "Refund": {
        "MerchantTransactionID": "Refund_{{$timestamp}}",
        "Amount": 100,
        "Currency": "GBP",
        "Description": "test",
        "OriginatorTransactionID": "12345",
        "Articles": [
            {
                "MerchantArticleID": "5009000",
                "Quantity": 1
            }
        ]
    }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Refund": {
        "ID": 93602,
        "Created": "20240520103545",
        "MerchantTransactionID": "Refund_1716201346",
        "OriginatorTransactionID": "12345",
        "InitialPaymentID": 6906966,
        "Amount": "100",
        "Currency": "GBP",
        "Description": "test",
        "TypeID": 1,
        "SiteID": 30563,
        "Details": null,
        "Customer": null,
        "BillingAddress": null,
        "BankAddress": null,
        "Articles": [
            {
                "MerchantArticleID": "5009000",
                "Name": null,
                "Quantity": 1,
                "Price": "0",
                "VAT": "0",
                "Discount": "0",
                "Type": null,
                "TaxType": 0,
                "DiscountValue": "0"
            }
        ],
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "SplitID": 0
    }
}
  • Another particular case is for LATAM payment methods (Cash Payment and Online Banking payment methods – see the list below).The refunds for most LATAM payment methods are made by our local provider. In order for the refund to be processed the Customer bank details/ and customer full name are required. There are 2 possibilities:
    1. The Customer bank details are sent in full in the request, like in the below example. In this case, the refund should be processed within 48 hours.
    2. The Customer bank details are not sent in request. However, in this case, the local provider will contact the customer in order to obtain the bank details so the refund can be performed.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4070604/refunds
Authorization: Basic MzAyMDE6KzlLZUd6S0Y3VzhTLzc5YTVSMzNZSlVnN0U3V0ZOY1piakdmekxWM2JYU25GQ095RnQ=

{
  "Refund": {
    "MerchantTransactionID": "s2ptest_f201",
    "Amount": 400,
    "Details": {
      "CustomerAccountNumber":"A88888888888",
      "BankAccountType":"I",
      "BankName":"Banco do Brasil",
      "BankBranch":"Branch1234"
      },
    "Customer": {
      "Email":"test@test.com",
      "FirstName":"John",
      "LastName":"Smith"            
    }
  }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "Refund": {
    "ID": 27601,
    "Created": "20180914091320",
    "MerchantTransactionID": "s2ptest_f201",
    "OriginatorTransactionID": null,
    "InitialPaymentID": 4070604,
    "Amount": "400",
    "Currency": "PLN",
    "Description": null,
    "TypeID": 10,
    "SiteID": 30201,
    "Details": {
      "CustomerAccountNumber": "A88888888888",
      "BankName": "Banco do Brasil",
      "BankAccountType": "I",
      "BankBranch": "Branch1234"
      },
    "Customer": {
      "ID": 336,
      "MerchantCustomerID": null,
      "Email": "test@test.com",
      "FirstName": "John",
      "LastName": "Smith",
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": null,
      "Company": null,
      "DateOfBirth": null
      },
    "BillingAddress": null,
    "BankAddress": null,
    "Articles": null,
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": null
    },
    "SplitID": 0
  }
}
    Latam payment methods
    Method ID Method Name
    32 Debito Banco do Brasil
    1080 Santander Rio
    1081 Cash Payments Argentina
    1083 Boleto Brazil
    1084 Online Bank Transfer Brazil
    1086 Servipag
    1087 WebPay
    1089 PSE Colombia
    1090 Cash payment Colombia
    1092 Oxxo
    1093 SPEI
    1094 Bank Transfer Mexico
    1096 Redpagos
    1098 Cash payment Peru
    1099 Bank Transfer Peru
    1103 Rapi Pago
    1104 Pago Fácil
    1107 Netbanking
    1108 UPI
  • For Direct Card transactions you can initiate refunds only for those with a Captured payment status. When you are initiating a refund you need to provide the Refund Amount and the Merchant Transaction ID, that is automatically generated. You can change this ID by introducing your ID value. When refunding a payment that has multiple partial captures, you also need to send the CaptureID parameter in the request.

    Request:

    POST https://securetest.smart2pay.com/v1/payments/202246/refunds
Authorization: Basic MTAxMDpnYWJp

{
 "Refund": { 
   "MerchantTransactionID": "s2ptest_h19",
   "OriginatorTransactionID": "108_a",
   "Amount": 1000,   
   "Description": "refund reason",
   "StatementDescriptor": "refund ",
   "CaptureID": 546
  }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "Refund": {
    "ID": 263,
    "SiteID": 1010,
    "Created": "20161205095348",
    "MerchantTransactionID": "s2ptest_h19",
    "OriginatorTransactionID": "108_a",
    "InitialPaymentID": 0,
    "Amount": 1000,
    "Currency": "EUR", 
    "Description": "refund reason",
    "StatementDescriptor": null,
    "CaptureID": 546,
    "Customer": null,
    "BillingAddress": null,
    "BankAddress": null,
    "Articles": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    },
    "SplitID": 0
  }
}

    In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

    For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4520424/refunds
Authorization: Basic MzAyMDE6KzlLZUd6S0Y3VzhTLzc5YTVSMzNZSlVnN0U3V0ZOY1piakdmekxWM2JYU25GQ095RnQ=

{
  "Refund": {
    "MerchantTransactionID": "s2ptest_gi11",
    "Amount": 100,
    "Description": "Refund Test Description"
   }
}

    Response:

    HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "Refund": {
        "ID": 36677,
        "Created": "20190516080948",
        "MerchantTransactionID": "s2ptest_gi11",
        "OriginatorTransactionID": null,
        "InitialPaymentID": 4520424,
        "Amount": "100",
        "Currency": "EUR",
        "Description": "Refund Test Description",
        "TypeID": 5,
        "SiteID": 30201,
        "Details": null,
        "Customer": null,
        "BillingAddress": null,
        "BankAddress": null,
        "Articles": null,
        "Status": {
            "ID": 4,
            "Info": "Failed",
            "Reasons": [
                {
                    "Code": "134",
                    "Info": "Another refund is already in process"
                }
            ]
        },
        "SplitID": 0
    }
}