In-Store Payments

Refund a payment

Send a refund to return captured funds to a consumer. Except for a standalone refund, the Online Payments API uses the payment method from a previous payment for your refund. Unreferenced or standalone refunds are not supported.

In this guide, learn how to perform the following:

Full refund
Partial refund

Note

We process refund authorizations on your behalf as part of a refund call.

Attention

For Mastercard refund transactions (referenced and standalone), you don't need to send the originalTransactionLinkId in the request. J.P. Morgan Payments automatically identifies the TLID associated with the original transaction. For more information, refer to Mastercard transaction link identifier.

Before you begin

Before you send a full or partial refund, obtain the transactionId of the original payment transaction.

To refund a partial amount:

Determine that the amount of the refund is less than the amount of the original payment.
The total amount of multiple partial refunds must not exceed the amount of the original payment.

Note

You can process referenced refunds up to 13 months after the original transaction.

Full refund

Refund the entire original captured amount to the consumer by using the POST /refunds endpoint.

Reference the original payment transaction.
Send the original transactionId value in the paymentMethodType.transactionReference.transactionReferenceId field.
The refund amount is optional for full refund requests. If the amount is not provided, the refund defaults to the remaining refundable amount associated with the referenced transaction.
PayFac merchant identification data is inherited from the original transaction.

The following table shows the minimum required fields for full refunds:

Required fields for full refunds
Field name	Description	Comment
paymentMethodType.transactionReference.`transactionReferenceId`	The original `transactionId` value.
merchant.merchantSoftware.`companyName`	The company name of software integrated to this API.
merchant.merchantSoftware.`productName`	The name of the product used for marketing purposes from a consumer's perspective.
merchant.softMerchant.`name`	The name of the merchant who is recognizable to account holder. This is intended to be used in the event where the merchant of record is a payment facilitator.	PayFac required field. Must not exceed 19 alphanumeric characters to prevent truncation.
merchant.softMerchant.`phone`	Phone number of the merchant.	PayFac required field.
merchant.softMerchant.address.`line1`	First line of the street address.	PayFac required field.
merchant.softMerchant.address.`line2`	Second line of the address.	PayFac required field.
merchant.softMerchant.address.`city`	The name of the municipality.	PayFac required field.
merchant.softMerchant.address.`postalCode`	The portion of a party's address that is the encoded representation of a geographic area to facilitate mail delivery services.	PayFac required field.
merchant.softMerchant.address.`countryCode`	The country code of the address based on Alpha 3 ISO standards.	PayFac required field.
merchant.softMerchant.address.`addressTypeCode`	The classification given to the various addresses captured for a party, such as Doing Business As Address, Legal Entity Address, and Tax Address.	PayFac required field.
subMerchantSupplementalData. merchantIdentification.`subMerchantId`	The merchant's account as it appears on the accountholder's statement.	PayFac required field.
subMerchantSupplementalData. merchantIdentification.`serviceEntitlementNumber`	The unique number assigned to a merchant by a payment brand to process conveyed transactions.	PayFac required field.
subMerchantSupplementalData. merchantIdentification.`sellerIdentifier`	A unique identifier generated by the firm to identify the individual Transaction Division processing, using the American Express (AMEX) OptBlue program under the firm's Service Entitlement (SE) Number.	PayFac required field.

HTTP Method: POST
Endpoint: /refunds
Scenario: Performing a full refund on a payment

Json

{
  "amount": 200,
  "merchantOrderNumber": "merchantOrderNumber-116",
  "currency": "EUR",
  "paymentMethodType": {
    "transactionReference": {
      "transactionReferenceId": "ebd9dd83-5cd3-472d-9edb-b6433727530a"
    }
  },
  "merchant": {
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "softwareId": "027C",
      "version": "20240600.1.6"
    }
  }
}

Response:

Json

{
  "transactionId": "f8797bd4-852e-48ea-b7cb-d31792f0e875",
  "requestId": "6fabba2f-15f1-44cf-9f73-5d631f32ce3a",
  "transactionState": "AUTHORIZED",
  "captureTime": "2026-07-10T15:03:54.550Z",
  "amount": 200,
  "currency": "EUR",
  "responseStatus": "SUCCESS",
  "responseCode": "APPROVED",
  "responseMessage": "Transaction approved by Issuer",
  "transactionReferenceId": "ebd9dd83-5cd3-472d-9edb-b6433727530a",
  "remainingRefundableAmount": 700,
  "approvalCode": "205282",
  "hostMessage": "00",
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "NOT_STORED",
  "transactionDate": "2026-07-10T15:12:21.814Z",
  "merchant": {
    "merchantId": "109151579001",
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "version": "20240600.1.6",
      "softwareId": "027C"
    },
    "merchantCategoryCode": "6540",
    "softMerchant": {
      "name": "softmerchant",
      "address": {
        "line1": "18 BAYARD AVE",
        "city": "Paris",
        "state": "FR",
        "postalCode": "068912",
        "countryCode": "FRA"
      }
    }
  },
  "merchantOrderNumber": "merchantOrderNumber-116",
  "paymentMethodType": {
    "card": {
      "accountNumberType": "TRACK",
      "cardTypeName": "MASTERCARD",
      "cardType": "MC",
      "maskedAccountNumber": "545301XXXXXX2210",
      "networkResponse": {
        "banknetReferenceNumber": "MCS408871350",
        "networkTransactionId": "MCS4088713500710",
        "networkResponseCode": "00"
      }
    }
  },
  "paymentRequest": {
    "paymentRequestId": "ebd9dd83-5cd3-472d-9edb-b6433727530a",
    "paymentRequestStatus": "CLOSED",
    "authorizations": [
      {
        "authorizationId": "ebd9dd83-5cd3-472d-9edb-b6433727530a",
        "amount": 2900,
        "transactionStatusCode": "CAPTURED",
        "authorizationType": "INITIAL",
        "transactionTimestamp": "2026-07-10T15:03:54.550Z",
        "expirationTimestamp": "2026-07-17T15:03:54.550Z"
      }
    ],
    "captures": [
      {
        "captureId": "ebd9dd83-5cd3-472d-9edb-b6433727530a",
        "amount": 2900,
        "transactionStatusCode": "CLOSED",
        "captureRemainingRefundableAmount": 700,
        "referencedAuthorizationIdentifier": "ebd9dd83-5cd3-472d-9edb-b6433727530a"
      }
    ],
    "refunds": [
      {
        "refundId": "bdf0f36d-e454-41d9-b578-0f50e32146b3",
        "amount": 2000,
        "transactionStatusCode": "CLOSED"
      },
      {
        "refundId": "f8797bd4-852e-48ea-b7cb-d31792f0e875",
        "amount": 200,
        "transactionStatusCode": "CLOSED"
      }
    ]
  },
  "subMerchantSupplementalData": {
    "merchantIdentification": {
      "subMerchantId": "39016507",
      "sellerIdentifier": "123456"
    }
  },
  "pointOfInteraction": {
    "device": {
      "capabilities": [
        "EMV_CONTACTLESS"
      ],
      "pinCapability": "PIN_ELIGIBLE",
      "location": "ON_PREMISE",
      "attendance": "ATTENDED",
      "applicationInfo": {
        "deviceType": "IPHONE"
      },
      "vendorId": "0181",
      "terminalDeviceSerialNumber": "P10_C467D3003",
      "deviceId": "0001"
    },
    "inPerson": {
      "isCardholderPresent": true,
      "entryMethod": "EMV_CONTACTLESS",
      "emvInformation": {
        "emvData": "5F2A020840820220008407A00000000310108A0200008F0192950500000000009A032406179C01009F02060000000002009F03060000000000009F0607A00000000310109F100706010A03A000009F1A0208409F1E0834363744333030339F21031453559F2608E42C02D382E2C07E9F2701809F3303E028C09F34033F00009F3501229F360201549F37041DF5C23D9F3901079F4005F000A0A0019F410200039F6E0420700000",
        "applicationId": "A0000000031010",
        "emvSequenceNumber": "0002",
        "hostReturnedData": "910a9E765D1834E581BE3035"
      }
    }
  },
  "merchantDefined": {
    "merchantDefinedData": "HjBerA1jsrYy3eMZCZhy2H"
  }
}

Partial refund

Refunds only a portion of the original captured amount by using the POST /refunds endpoint.

Send the original transactionId value in the paymentMethodType.transactionReference.transactionReferenceId field.
Include the amount to refund.
The amount of the refund must be less than the original payment amount. You may process multiple partial refunds, but the total refunded amount cannot exceed the original payment.
Payfac required fields are inherited from the original transaction.

The following table shows the minimum required fields for this transaction:

Required fields for partial refunds
Field name	Description	Comment
paymentMethodType.transactionReference.`transactionReferenceId`	The original `transactionId` value.
merchant.merchantSoftware.`companyName`	The company name of software integrated to this API.
merchant.merchantSoftware.`productName`	The name of the product used for marketing purposes from a consumer's perspective.
merchant.softMerchant.`name`	The name of the merchant who is recognizable to account holder. This is intended to be used in the event where the merchant of record is a payment facilitator.	PayFac required field. Must not exceed 19 alphanumeric characters to prevent truncation.
merchant.softMerchant.`phone`	Phone number of the merchant.	PayFac required field.
merchant.softMerchant.address.`line1`	First line of the street address.	PayFac required field.
merchant.softMerchant.address.`line2`	Second line of the address.	PayFac required field.
merchant.softMerchant.address.`city`	The name of the municipality.	PayFac required field.
merchant.softMerchant.address.`postalCode`	The portion of a party's address that is the encoded representation of a geographic area to facilitate mail delivery services.	PayFac required field.
merchant.softMerchant.address.`countryCode`	The country code of the address based on Alpha 3 ISO standards.	PayFac required field.
merchant.softMerchant.address.`addressTypeCode`	The classification given to the various addresses captured for a party, such as Doing Business As Address, Legal Entity Address, and Tax Address.	PayFac required field.
subMerchantSupplementalData. merchantIdentification.`subMerchantId`	The merchant's account as it appears on the accountholder's statement.	PayFac required field.
subMerchantSupplementalData. merchantIdentification.`serviceEntitlementNumber`	The unique number assigned to a merchant by a payment brand to process conveyed transactions.	PayFac required field.
subMerchantSupplementalData. merchantIdentification.`sellerIdentifier`	A unique identifier generated by the firm to identify the individual Transaction Division processing, using the American Express (AMEX) OptBlue program under the firm's Service Entitlement (SE) Number.	PayFac required field.

HTTP Method: POST
Endpoint: /refunds
Scenario: Performing a partial refund on a payment

Json

{
  "amount": 200,
  "merchantOrderNumber": "merchantOrderNumber-126",
  "currency": "EUR",
  "paymentMethodType": {
    "transactionReference": {
      "transactionReferenceId": "3f895e14-95ab-45a7-9028-0c56b547dc4f"
    }
  },
  "merchant": {
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "softwareId": "027C",
      "version": "20240600.1.6"
    }
  }
}

Response:

Json

{
  "transactionId": "04cbd28c-2a0b-4d72-a7c0-aea16fbd6600",
  "requestId": "e7e551ae-af25-47ec-8180-9b71d1868f58",
  "transactionState": "AUTHORIZED",
  "captureTime": "2026-07-13T11:03:35.666Z",
  "amount": 200,
  "currency": "EUR",
  "responseStatus": "SUCCESS",
  "responseCode": "APPROVED",
  "responseMessage": "Transaction approved by Issuer",
  "transactionReferenceId": "3f895e14-95ab-45a7-9028-0c56b547dc4f",
  "remainingRefundableAmount": 2700,
  "approvalCode": "793100",
  "hostMessage": "00",
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "NOT_STORED",
  "transactionDate": "2026-07-13T11:04:05.749Z",
  "merchant": {
    "merchantId": "109151579001",
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "version": "20240600.1.6",
      "softwareId": "027C"
    },
    "merchantCategoryCode": "6540",
    "softMerchant": {
      "name": "softmerchant",
      "address": {
        "line1": "18 BAYARD AVE",
        "city": "Paris",
        "state": "FR",
        "postalCode": "068912",
        "countryCode": "FRA"
      }
    }
  },
  "merchantOrderNumber": "merchantOrderNumber-126",
  "paymentMethodType": {
    "card": {
      "accountNumberType": "TRACK",
      "cardTypeName": "VISA",
      "cardType": "VI",
      "maskedAccountNumber": "422998XXXXXX0012",
      "networkResponse": {
        "last4CardNumber": "0000",
        "networkTransactionId": "123456789012345",
        "paymentAccountReference": "13456789012345678923452349237",
        "networkResponseCode": "00"
      }
    }
  },
  "paymentRequest": {
    "paymentRequestId": "3f895e14-95ab-45a7-9028-0c56b547dc4f",
    "paymentRequestStatus": "CLOSED",
    "authorizations": [
      {
        "authorizationId": "3f895e14-95ab-45a7-9028-0c56b547dc4f",
        "amount": 2900,
        "transactionStatusCode": "CAPTURED",
        "authorizationType": "INITIAL",
        "transactionTimestamp": "2026-07-13T11:03:35.666Z",
        "expirationTimestamp": "2031-03-16T00:00:00Z"
      }
    ],
    "captures": [
      {
        "captureId": "3f895e14-95ab-45a7-9028-0c56b547dc4f",
        "amount": 2900,
        "transactionStatusCode": "CLOSED",
        "captureRemainingRefundableAmount": 2700,
        "referencedAuthorizationIdentifier": "3f895e14-95ab-45a7-9028-0c56b547dc4f"
      }
    ],
    "refunds": [
      {
        "refundId": "04cbd28c-2a0b-4d72-a7c0-aea16fbd6600",
        "amount": 200,
        "transactionStatusCode": "CLOSED"
      }
    ]
  },
  "subMerchantSupplementalData": {
    "merchantIdentification": {
      "subMerchantId": "39016507",
      "sellerIdentifier": "123456"
    }
  },
  "pointOfInteraction": {
    "device": {
      "capabilities": [
        "EMV_CONTACTLESS"
      ],
      "pinCapability": "PIN_ELIGIBLE",
      "location": "ON_PREMISE",
      "attendance": "ATTENDED",
      "applicationInfo": {
        "deviceType": "IPHONE"
      },
      "vendorId": "0181",
      "terminalDeviceSerialNumber": "P10_C467D3003",
      "deviceId": "0001"
    },
    "inPerson": {
      "isCardholderPresent": true,
      "entryMethod": "EMV_CONTACTLESS",
      "emvInformation": {
        "emvData": "5F2A020840820220008407A00000000310108A0200008F0192950500000000009A032406179C01009F02060000000002009F03060000000000009F0607A00000000310109F100706010A03A000009F1A0208409F1E0834363744333030339F21031453559F2608E42C02D382E2C07E9F2701809F3303E028C09F34033F00009F3501229F360201549F37041DF5C23D9F3901079F4005F000A0A0019F410200039F6E0420700000",
        "applicationId": "A0000000031010",
        "emvSequenceNumber": "0002"
      }
    }
  },
  "merchantDefined": {
    "merchantDefinedData": "HjBerA1jsrYy3eMZCZhy2H"
  }
}

Payment fields

Refund a payment

Before you begin

Full refund

Partial refund

Related