Unreferenced refund

Unreferenced refunds are a way to return any amount to any card presented to the terminal. You can use an unreferenced refund, for example, if someone received a holiday gift and wants to return the item. You also need to integrate unreferenced refunds to support Interac transactions.

You can only refund a payment after the authorization is captured. Payments that have not been captured yet have to be cancelled instead.

Making a host-to-host unreferenced refund is a two-step process:

1. authorize the unreferenced refund with a POST request to the /pos/v#/unreferencedRefunds endpoint.
2. Complete the unreferenced refund with a POST request to the /pos/v#/unreferencedRefunds/{pspreference}/completions endpoint. The PSP reference in the URL is the PSP reference of the unreferenced refund authorization request. It is not the PSP reference of the original payment request.

Enable unreferenced refunds

Unreferenced refunds are not linked to the original payments. This offers flexibility, but also implies a bigger return fraud risk compared to referenced refunds. For example, refunding the original payment more than once is not possible with referenced refunds, but could happen with unreferenced refunds. Because of the bigger risk, you need to complete a compliance process before you can issue host-to-host unreferenced refunds.

• Reach out to your Adyen contact to start the compliance process.

Step 1: Make a refund authorization request

The request to authorize a host-to-host unreferenced refund is the same as a host-to-host payment authorization request, but you must send it to a different endpoint.

After the customer has presented their card to your payment terminal, initiate an unreferenced refund:

1. Make a POST /pos/v#/unreferencedRefunds request with the following required parameters:

   Field	Required	Type	Description
   amount		object	An object with amount information consisting of: currency (string): the three-character ISO currency code for the transaction. value (integer): the final amount of the transaction, in minor units (without a decimal point).
   merchantAccount		string	The merchant account identifier that you want to process the transaction with.
   posEntryMode		string	A two-character code indicating how the card data was obtained. Consists of the first two characters of field 22 from the ISO 8583:2023 specification. For example, 05 represents ICC (chip card), 02 represents magnetic stripe, and 01 represents Manual Key Entry (MKE).
   reference		string	Your unique reference for the transaction.
   terminalCapabilities		string	A 3-byte hex-encoded value representing terminal capabilities, in accordance with Annex A2 of EMV Book 4.
   terminalCountryCode		string	The country code of the terminal's location. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
   terminalIdentification		string	Unique location of a terminal at a merchant. Equivalent to EMV tag 9F1C. Length: 16 characters.
   terminalType		string	Indicates the environment of the terminal, its communications capabilities, and its operational control. Equivalent to EMV tag 9F35.
   transactionSequenceCounter		integer	Counter maintained by the terminal that is incremented by one for each transaction. Equivalent to EMV tag 9F41.
   transactionDate		string	Transaction date and time in ISO 8601 format (YYYY-MM-DDThh:mm:ss.sssTZD). If not specified, defaults to the date and time of the request.

   Depending on your use case and the entry mode, add more parameters as needed:

   • Optional parameters, including routing parameters and shopper statement.
   • Split payment data for use in a platform model.
   • Submerchant data, which is required if you are a payment facilitator.
   • MSR or MKE entry mode.
   • Chip card entry mode.

   This example shows an unreferenced refund request when the card details are obtained using a card reader or NFC reader.

2. When you receive the unreferenced refund response, check the resultCode. If this is Authorised, save the pspReference. Also save your reference and other details that you need for reconciliation or for your particular business model.
   The response contains:

   Field	Description
   authorisationResponseCode	Response code generated by the issuer. Equivalent to tag8a for chip transactions.
   emvData	EMV chip data. If present, contains tag8a: the Authorisation Response Code.
   paymentMethod	The payment method (card type) used in the transaction. You can include this in the shopper receipt.
   pspReference	Our unique identifier for the request. Save this value, because you need it for the completion request. You can also use it to look up the transaction in your Customer Area.
   reference	Your unique reference for the transaction, echoed from the request.
   resultCode	The current state of the transaction. See Result codes. Authorised indicates that the issuer approved the transaction.

Handle a failed authorization

If an authorization is declined, use the following authorization response fields to determine the cause and decide on your next step:

• resultCode: Authorised, Refused, Error, or Cancelled.
• refusalReason: Adyen's mapped reason for the refusal. This is a generalization of similar refusal reasons from different card schemes.
• refusalReasonCode: a code corresponding to Adyen's mapped refusal reason.
• emvData.tag8a: the raw Authorisation Response Code (ARC) for a chip card transaction.
• authorisationResponseCode: the ARC for a transaction, corresponding to the raw response value.

Note that the ARC can differ depending on the card scheme, so in general it is not recommended to code against this field. But if you have a multiple-acquirer setup where your code is already based on variable ARC values, you can use the ARC to determine the authorization status.

Not enough balance

Refunds are deducted from your in-process funds. Or in a platform model, refunds are deducted from the balance accounts indicated in the split instructions provided in the refund request.

If there are insufficient funds, the refund fails. You receive an unreferenced refund authorization response like the following example:

{
    "status": 422,
    "errorCode": "917",
    "message": "There is not enough balance available for account ADYEN_MERCHANT_ACCOUNT. Available balance: EUR 329.11; Requested amount: EUR 400.00",
    "errorType": "validation"
}

To fix this issue, increase your refund balance. In a platform model, set up automatic top-ups or make an internal funds transfer.

Step 2: Make a refund completion request

After you receive an Authorised response for the unreferenced refund, you must send a completion request. Otherwise, the customer is not refunded.

To complete an unreferenced refund:

1. Make a POST request to the /pos/v#/unreferencedRefunds/{pspreference}/completions endpoint, where {pspReference} is the PSP reference you received in the unreferenced refund authorization response.

   Specify the following parameters:

   Field	Required	Type	Description
   merchantAccount		string	The merchant account identifier that you want to process the transaction with.
   reference		string	Your unique reference for the transaction. Max. 80 characters. If you include it, use the same reference that you provided in the authorization request.
   merchantTerminalIdentifier		string	Your unique identification of the payment terminal.

   Unlike a payment completion request, the completion request for an unreferenced refund doesn't need to include emvdata for chip card transactions. The global card schemes do not require this data for refunds.

2. When you receive the completion response, check the result code. The response contains:

   Field	Description
   pspReference	Our unique identifier for the completion request. Note that this is different from the PSP reference of the unreferenced refund authorization that you are completing.
   reference	If the completion request included your unique reference for the transaction, the reference is included in the response.
   resultCode	The status of the completion request. Received indicates your request is being processed.

3. Wait for a REFUND_WITH_DATA webhook to learn the result of the unreferenced refund after authorization and completion.

If completion of the unreferenced refund succeeded, the transaction has the status Authorised in your Customer Area.

REFUND_WITH_DATA webhook

Before we send your host-to-host unreferenced refund request to be processed, we perform various validations. If these validations succeed, usually the refund itself also succeeds. You receive the outcome of the validations asynchronously, in a REFUND_WITH_DATA webhook that includes:

• eventCode: REFUND_WITH_DATA.
• additionalData: the information in this objects depends on the additional settings that you enabled.
• originalReference: the PSP reference returned in the /pos/v#/unreferencedRefunds response.
• pspReference: the PSP reference returned in the /pos/v#/unreferencedRefunds/{pspreference}/completions response.

• success: indicates the outcome of the refund validations. Possible values:

  • true: Adyen's validations were successful and we sent the refund request to the card scheme. This usually means that the refund will be processed successfully. However, in rare cases the refund can be rejected by the card scheme, or reversed. For information about these exceptions, see REFUND_FAILED webhook, and REFUNDED_REVERSED webhook.

  • false: the refund validations failed. The webhook includes a reason field with a short description of the problem. Review the reason, fix the issue if possible, and resubmit the refund request.

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
                "fundingSource":"CREDIT"
            },
            "amount":{
               "currency":"EUR",
               "value":40000
            },
            "eventCode":"REFUND_WITH_DATA",
            "eventDate":"2023-04-27T17:46:51+02:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference": "YOUR_MODIFICATION_REFERENCE",
            "originalReference":"NV4ZPV72LV5X8N82",
            "paymentMethod":"mc",
            "pspReference":"NC6HT9CRT65ZGN82",
            "reason":"",
            "success":"true"
         }
      }
   ]
}

For more information about the included fields, see the REFUND_WITH_DATA webhook reference.

Reasons for failed refund validation

When our validations of a refund fail, you receive a webhook for the refund with success: false and the reason of the failure. The next table shows the most common reasons.

Where the table mentions the balance on the payment, this refers to the amount that remains from the original payment. For example, if a transaction has a total of EUR 10 and no refund or chargeback is processed, then the balance on the payment is EUR 10. After a refund or chargeback of EUR 3 is processed, the remaining balance on the payment is EUR 7.

See also