Skip to main content

Refund

POST 
/payment/refund

Enables you to perform a partial or full refund of a captured/settled transaction.

info

Each message sent via API is a request and should include a unique modificationId as request identifier for the purpose of detecting duplicate requests. If you need to retry a request due to a timeout or other exception, send the exact same message using the same modificationId to ensure the message is not processed multiple times.
In retry situations, please make sure to always use the same modificationId as provided in the initial request. SmartPay uses the modificationId to recognize retries and will always provide you this the same result as in the initial request posted with the same modificationId.

Request​

Header Parameters

    Content-Type stringrequired

    Must be application/json

    Accept-Language stringrequired

    Must be be en-US

    Origin stringrequired

    The origin of the request

    User-Agent stringrequired

    The client making the request

Bodyrequired

    transactionIdstringrequired

    Unique transaction identifier for the original transaction to be refunded.

    modificationIdstringrequired

    Your unique reference for the requested modification. This should be unique for each refund request to allow detection of duplicate requests.

    merchantKeystringrequired

    Merchant identifier.

    Possible values: <= 36 characters

    modifiedAmount object

    Additional transaction data for partial refunds. Required for partial refunds.

    amountnumber<decimal>

    Refund transaction amount. Must be greater than 0 and less than or equal to the original transaction amount.

    currencyCodestring

    The 3-letter currency ISO-4217 code.

    Possible values: >= 3 characters and <= 3 characters

    descriptionstring

    Description of the refund, e.g., the reason for the refund.

    customReferencesobject

    For external party usage. Please refer to Data Model for more details. Can be used to store additional information about the refund.

Responses​

Successful cancellation

Schema
    reconciliationReferenceIdstringrequired

    External payment provider unique transaction identifier.
    Within SmartPay, each order on your side is represented by one checkout transactionID. You may use this transactionID to perform the initial checkout, retrieve an overall status or for later modifications, like manual capture or refunds.
    On the payment side, this may lead to multiple financial transactions, e.g., one payment transaction about the captured amount (which will be settled to your account), and later a refund transaction (which will be debited from your account / deducted from your payout).
    The reconciliationReferenceId has been introduced to allow you to keep track of those financial transactions, as it represents the financial transactionID, as you would see it in the payment provider's merchant portal (e.g., our Merchant Panel) or settlement files.

    Example: QixTLEO28YngDAUuaUEOi
    descriptionstringrequired

    Transaction description, as specified by you in the checkout API request.

    Example: 4 pcs windscreen wipers
    paymentStatusstringrequired

    Current payment status of the initial transaction. Please refer here for more information.

    Possible values: [CREATED, CAPTURED, AUTHORIZATION_PENDING, AUTHORIZATION_COMPLETED, FAILED, CAPTURE_PENDING, CANCELLATION_PENDING, EXPIRED, CANCELLED, SETTLED, CHARGEBACK]

    Example: CAPTURED
    creationDatestringrequired

    Transaction creation date and time.

    Example: 2020-12-15T14:38:59.150Z
    lastStatusDatestringrequired

    Transaction status changing date and time

    Example: 2020-12-15T14:40:25.008Z
    partnerReferencestring

    Transaction identifier provided by the merchant

    Example: GHssjkauhdaku658702
    transactionOverview objectrequired
    transactionIdstringrequired

    The unique identifier of the transaction generated on transaction creation.

    Possible values: <= 36 characters

    Example: 123e4567-e89b-12d3-a456-426614174000
    acquirerResponsestring

    paymentProviderResponse sent in the Complete Autorize response in case of error.

    amountnumber<decimal>required

    Transaction modification amount

    Possible values: Value must match regular expression ^\d{1,18}\.\d{2}$

    Example: false
    currencyCodestringrequired

    Transaction modification currency. The 3-letter currency ISO-4217 code.

    Example: EUR
    customReferences object

    For external party usage. Please refer to Data Model for more details.

    custom1string

    generic custom reference

    Possible values: <= 255 characters

    custom2string

    generic custom reference

    Possible values: <= 255 characters

    custom3string

    generic custom reference

    Possible values: <= 255 characters

    customerAccountIdstring

    Unique customer identifier

    Example: john-doe-27
    deal object

    Details of the deal. Used only for 3RI payments (Partial or split shipment and Delayed shipment use cases).

    amountnumber<decimal>

    The total amount of the deal. The sum of all payments with the same dealReference may not exceed this amount. Used only for Split Shipment flow.

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Example: 19.99
    dealReferencestring

    Deal identifier.

    Possible values: <= 21 characters

    Example: rJIUUztdDPPqh4Zaw98pq
    typeCodestring

    Deal type

    Possible values: <= 6 characters, [3RIPSS, 3RIDS]

    Example: 3RIPSS
    mitboolean

    Flag to show if created transaction relates to merchant-initiated transactions.

    Example: false
    paymentMethodstring

    Used payment option code. Please refer to the Data Model for more information.
    Payment option CARDS is returned by SmartPay in case the actual card brand has not been selected by the consumer yet or if it could not be determined.

    Example: CARDS
    paymentOriginstring

    Displays the origin flag marked upon creation of the transaction.

    Possible values: [HOSTED_PAYMENT_PAGE, PAYMENT_AUTHORIZE_S2S, CHECKOUT, SUBSCRIPTION_MIT, MERCHANT_MIT]

    Example: CHECKOUT
    targetMerchantAccountReferencestring

    If provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored.

    Example: 123456789
    transactionReferencestring

    External payment provider reference of the Pre-Payment or Payment Upon Invoice. To be sent each time there is a value present in the data source.

    Example: THNkjjkfdhjk7798798
    modification objectrequired

    Array of all performed transaction modifications.

    creationDatestring<date-time>

    Date and time of the modification processing start.

    error errorBadRequestExternal
    errorstring

    indicates at which level of processing the error appeared

    Possible values: [gateway_processing, payment_provider_processing]

    errorDetails object
    contextobject

    Additional error details, as received from the third party

    gatewayDescriptionstring

    Error message returned by payment gateway

    Possible values: <= 400 characters

    paymentProviderDescriptionstring

    Error message returned by payment provider

    Possible values: <= 400 characters

    lastStatusDatestring<date-time>

    Date and time of the modification processing completion.

    modificationAmount object

    The payment amount to be charged against the payment option.

    amountnumber<decimal>required

    Transaction modification amount

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Example: 49.99
    currencyCodestringrequired

    Transaction modification currency. The 3-letter currency ISO-4217 code

    Possible values: >= 3 characters and <= 3 characters

    Example: EUR
    descriptionstringrequired

    A terse description of the good or service being sold i.e., the reason for the payment

    Possible values: <= 127 characters

    Example: windscreen wipers 4 pcs
    modificationData object

    Additional details of the modification

    cancelIdstring<uuid>

    SmartPay internal unique identifier for cancel request.

    captureIdstring<uuid>

    SmartPay internal unique identifier for capture request.

    customReferences object

    A list of custom references submitted by the merchant along with a modification request (e.g., Capture, Cancel, Refund). Can be different from the customReference value provided in the Create Checkout API.

    custom1string

    generic custom reference

    Possible values: <= 255 characters

    custom2string

    generic custom reference

    Possible values: <= 255 characters

    custom3string

    generic custom reference

    Possible values: <= 255 characters

    modificationIdstringrequired

    For external party usage.

    Example: abcd123
    paymentSplitResults object[]

    Defines destinations for which the payment was split and their results.

  • Array [
    • amountnumber<decimal>required

    Transaction modification amount

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Example: 49.99
    currencyCodestringrequired

    Transaction modification currency. The 3-letter currency ISO-4217 code

    Possible values: >= 3 characters and <= 3 characters

    Example: EUR
    descriptionstringrequired

    A terse description of the good or service being sold i.e., the reason for the payment

    Possible values: <= 127 characters

    Example: windscreen wipers 4 pcs
    destinationReferencestringrequired

    Destination merchant account alias

    Possible values: <= 127 characters

    Example: destination-ref-1
    errorstring

    In case of a failed Debit Account or Refund request, contains error description in the following format [ {'responseCode'} ] {responseDescription}.

    splitUniqueReferencestringrequired

    Unique reference of the split transaction received in response of Debit Account or Refund.

    statusstringrequired

    Mapped to responseCode received from Debit Account or Refund. If the code returns 0000, it is a SUCCESS, otherwise it's ERROR.

    Possible values: <= 127 characters

  • ]
    • programRefundErrorMessagestring

    Message in case of error during KC Program refund.

    programRefundIdstring

    Stores the refund reference in case the merchant to program refund was successful.

    programRefundStatusstring

    Reflects the status of the refund from merchant to program level in SmartPay - success/error.

    reconciliationReferenceIdstring

    External provider unique transaction identifier - unique reference for capture or cancel and refund unique reference for refund.

    refundIdstring<uuid>

    SmartPay internal unique identifier for refund request.

    typestringrequired

    Type of the performed transaction modification.

    Possible values: [CAPTURE, CANCELATION, CHARGEBACK, SETTLEMENT, REFUND]

    Example: CAPTURE
    statusstring

    Actualized transaction or refund status after the performed modification.

    statusHistory object[]
  • Array [
    • errorstring

    Text message explaining the error issue

    modificationAmount objectrequired
    amountnumber<decimal>required

    Transaction modification amount

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Example: 49.99
    currencyCodestringrequired

    Transaction modification currency. The 3-letter currency ISO-4217 code

    Possible values: >= 3 characters and <= 3 characters

    Example: EUR
    descriptionstringrequired

    A terse description of the good or service being sold i.e., the reason for the payment

    Possible values: <= 127 characters

    Example: windscreen wipers 4 pcs
    optionstring

    SmartPay code of the payment option used.

    Example: VISA
    storedPaymentOptionReferencestring

    stored payment option reference

    Example: 8ac7a4a18d43bde5018d44ede3d21db5
    statusstring

    Status of the transaction modification or initial payment transaction.

    statusDatestring<date-time>required

    Modification transaction status changing date and time.

  • ]
 Imprint
|
Data protection and privacy
© 2026 J.P. Morgan Mobility Payments Systems GmbH. All rights reserved.