Detached / Unlinked Refunds

Detached Refund Request

The Detached Refund request follows a similar format of a standard PayPal refund request

Resource: POST /api/v5/apmTransactions

Request Parameters

Name	Required	Data Type	Description
merchantId	Mandatory	String	Unique Merchant Id provided by PXP
storeId	Mandatory	String	Unique Store Id provided by PXP
userId	Mandatory	String	A username allocated to a service user when the service is set up
type	Mandatory	String	"detached.refund". Only detached refunds are supported at present
amount	Mandatory	String	The monetary value of the transaction in minor units. See Note1.
currencyCode	Mandatory	String	The currency of the transaction. A three character code in accordance with ISO 4217.
clientSystemTransactionId	Mandatory	String	The merchant’s own unique reference for the refund
parentTransactionId	Mandatory	String	This is the transaction Identifier from the original transaction to refund, specified in the migration process.
providerDiscretionaryData	Optional	String	The merchant’s external facing order number with the consumer, which if supported, will be passed to the Provider as an additional descriptor.
apmDetails
apmProvider	Mandatory	String	The alternative payment method provider name. There is value “PayPalV2”

Note1: The decimal separator/radix character used is the Period ('.') used to indicate decimal places. Other characters such as Comma (',') will not be recognised and may result in an unintended amount being processed.

Example:

{
  "merchantId": "PSH",
  "storeId": "PSH500000001",
  "userId": "PSH001",
  "type": "detached.refund",
  "amount": 1.00,
  "currencyCode": "USD",
  "clientSystemTransactionId": "PPRefund20250101090101",
  "parentTransactionId": "AP03536792",
  "providerDiscretionaryData": "detachedRefund.1",
  "apmdetails": {
    "apmProviderName": "paypalv2"
  }
}

Detached Refund Response(s)

Approved Responses

Response Parameters

Name	Data Type	Description
State	String	Transaction state
providerResponseCode	String	The Response code from the provider
providerAuthorizationID	String	Payment identifier
providerResponseMessage	String	the Response Message from the provider
currencyCode	String	The currency of transaction.
clientSystemTransactionId	String	The merchant’s own unique reference for the transaction.
responseMessage	String	The response message. may differ from providerResponseMessage
amount	String	The amount which was Refunded
apmDetails
apmProvider	String	"PayPal"

Some Example responses to a Detached Refund are:

Approved

{
    "state": "Approved",
    "providerResponseCode": "",
    "providerAuthorizationID": "1b648675-8654-4399-8193-c6ac3f54fbbf ",
    "providerResponseMessage": "Requested refund amount is 1.00 and actual refunded amount is 1.00.",
    "currencyCode": "USD",
    "clientSystemTransactionId": " PPRefund20250101090101",
    "apmdetails": {
        "apmProviderName": "PayPal"
    },
    "responseMessage": "Requested refund amount is 1.00 and actual refunded amount is 1.00.",
    "amount": "1.00"  
}

{
    "state": "Approved",
    "providerResponseCode": "",
    "providerAuthorizationID": "",
    "providerResponseMessage": "Requested refund amount is 15.00 and actual refunded amount is 2.00.",
    "currencyCode": "USD",
    "clientSystemTransactionId": "PPRefund2025010109010202",
    "apmdetails": {
        "apmProviderName": "PayPal"
    },
    "responseMessage": "Requested refund amount is 15.00 and actual refunded amount is 2.00.",
    "amount": "1.00"
}

Error Responses

Error Response Parameters

Name	Data Type	Description
code	String	The FaultResponseCode of the error
details
message	String	a more detailed description of the error where available.

RefundLimitExceeded

{
    "code": "4107940",
    "details": {
        "message": "RefundAmountExceeded Refund amount exceeded! Deposit amount = 40.0000; Refunded amount = 40.0000; Max refundable amount = 0.0000; Refund amount = 1.00"
    }
}

General Error

{
    "code": "4107940",
    "details": {
        "message": "SchemaValidationError The MerchantId field is required.”
    }
}