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.
In this guide, learn how to perform the following:
- Full refund
- Partial refund
- Standalone refund
- Multi-capture order refund
- Manual refund capture
- Delayed refund capture
- Retrieve refund details
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.
To process a multi-capture order refund (for example, to refund one shipment from a split shipment order):
- The amount of the refund must be less than or equal to the amount of the capture (referred to by
captureId), not the amount of the authorization.
Full refund
Refer to the following steps to refund the full amount of a previous transaction:
- Reference the original payment transaction.
- Send the original
transactionIdvalue in thepaymentMethodType.transactionReference.transactionReferenceIdfield. - Omit the amount.
The following is an example of a full refund request:
HTTP method: POST
Endpoint: /refunds
{
"paymentMethodType": {
"transactionReference": {
"transactionReferenceId": "624e78df-a159-4f26-9d20-1f81841e15e7"
}
},
"merchant": {
"merchantSoftware": {
"companyName": "J.P. Morgan Chase",
"productName": "Application Name",
"version": "1.235"
}
}
}Confirm a successful response with an HTTP 200 status. The following fields indicate the result:
responseStatusresponseCoderesponseMessage
Response:
{
"transactionId": "948a288a-fe83-43ed-99eb-c1ca7afa1b3e",
"requestId": "974c5764-e851-442b-8074-fd3d9c8ba08d",
"transactionState": "AUTHORIZED",
"amount": 1234,
"currency": "USD",
"responseStatus": "SUCCESS",
"responseCode": "APPROVED",
"responseMessage": "Transaction approved by Issuer",
"transactionReferenceId": "624e78df-a159-4f26-9d20-1f81841e15e7",
"remainingRefundableAmount": 0,
"approvalCode": "tst862",
"hostMessage": "Approved",
"initiatorType": "CARDHOLDER",
"accountOnFile": "NOT_STORED",
"transactionDate": "2024-07-31T14:21:36.253Z",
"merchant": {
"merchantId": "998482157632",
"merchantSoftware": {
"companyName": "J.P. Morgan Chase",
"productName": "Application Name",
"version": "1.235"
},
"merchantCategoryCode": "4899"
},
"paymentMethodType": {
"card": {
"cardTypeName": "VISA",
"cardType": "VI",
"maskedAccountNumber": "411234XXXXXX4113",
"cardTypeIndicators": {
"issuanceCountryCode": "USA",
"isLevel2Eligible": false,
"isLevel3Eligible": false,
"isDurbinRegulated": false,
"cardProductTypes": [
"COMMERCIAL",
"PINLESS_DEBIT"
]
},
"networkResponse": {
"addressVerificationResult": "NOT_REQUESTED",
"additionalData": {
"electronicCommerceIndicator": "7",
"marketSpecificData": "B",
"productId": "F",
"posEntryMode": "01",
"returnAci": "T",
"validationCode": "CELO"
},
"networkTransactionId": "014213692168435"
},
"isBillPayment": true
}
},
"hostReferenceId": "QZH7049D0Nma9Mg2jyHDX5",
"paymentRequest": {
"paymentRequestId": "624e78df-a159-4f26-9d20-1f81841e15e7",
"paymentRequestStatus": "CLOSED",
"authorizations": [
{
"authorizationId": "624e78df-a159-4f26-9d20-1f81841e15e7",
"amount": 1234,
"transactionStatusCode": "CAPTURED",
"authorizationType": "INITIAL"
}
],
"captures": [
{
"captureId": "624e78df-a159-4f26-9d20-1f81841e15e7",
"amount": 1234,
"transactionStatusCode": "CLOSED",
"captureRemainingRefundableAmount": 0
}
],
"refunds": [
{
"refundId": "948a288a-fe83-43ed-99eb-c1ca7afa1b3e",
"amount": 1234,
"transactionStatusCode": "CLOSED"
}
]
}
}Partial refund
Refund a portion of the original transaction amount to a consumer. Refer to the following steps to refund a partial amount:
- Send the original
transactionIdvalue in thepaymentMethodType.transactionReference.transactionReferenceIdfield. - Include the amount to refund.
The following is an example of a partial refund request:
HTTP method: POST
Endpoint: /refunds
{
"amount": 900,
"currency": "USD",
"paymentMethodType": {
"transactionReference": {
"transactionReferenceId": "2150955d-47f7-4770-b6b7-6a8d0cbc114f"
}
},
"merchant": {
"merchantSoftware": {
"companyName": "Payment Company",
"productName": "Application Name",
"version": 1.235
}
}
}Response:
{
"transactionId": "2150955d-47f7-4770-b6b7-6a8d0cbc114f",
"requestId": "9f4068e9-81b2-40aa-80fc-010e96526b21",
"transactionState": "AUTHORIZED",
"amount": 900,
"currency": "USD",
"responseStatus": "SUCCESS",
"responseCode": "APPROVED",
"responseMessage": "Transaction approved by Issuer",
"transactionReferenceId": "12b2f378-40c8-425d-be1c-71971c21104d",
"remainingRefundableAmount": 3000,
"approvalCode": "tst698",
"hostMessage": "Approved",
"initiatorType": "CARDHOLDER",
"accountOnFile": "NOT_STORED",
"transactionDate": "2025-03-11T20:34:28.278Z",
"merchant": {
"merchantId": "000017904374",
"merchantSoftware": {
"companyName": "Payment Company",
"productName": "Application Name",
"version": "1.235"
},
"merchantCategoryCode": "4899"
},
"paymentMethodType": {
"card": {
"cardTypeName": "VISA",
"cardType": "VI",
"maskedAccountNumber": "411234XXXXXX4113",
"networkResponse": {
"addressVerificationResult": "NOT_REQUESTED",
"additionalData": {
"electronicCommerceIndicator": "7"
}
},
"isBillPayment": true
}
},
"hostReferenceId": "t79zEVoiZ3ZLMZi3Aftym5",
"paymentRequest": {
"paymentRequestId": "12b2f378-40c8-425d-be1c-71971c21104d",
"paymentRequestStatus": "CLOSED",
"authorizations": [
{
"authorizationId": "12b2f378-40c8-425d-be1c-71971c21104d",
"amount": 3900,
"transactionStatusCode": "CAPTURED",
"authorizationType": "INITIAL"
}
],
"captures": [
{
"captureId": "12b2f378-40c8-425d-be1c-71971c21104d",
"amount": 3900,
"transactionStatusCode": "CLOSED",
"captureRemainingRefundableAmount": 3000
}
],
"refunds": [
{
"refundId": "2150955d-47f7-4770-b6b7-6a8d0cbc114f",
"amount": 900,
"transactionStatusCode": "CLOSED"
}
]
}
}Standalone refund
A standalone refund processes independently from your previous transactions and can be processed in real time. The refund applies directly to the consumer’s payment method.
The following is an example of a standalone refund request:
HTTP method: POST
Endpoint: /refunds
{
"merchant": {
"merchantSoftware": {
"companyName": "Payment Company",
"productName": "Application Name",
"version": "1.235"
}
},
"amount": 1234,
"currency": "USD",
"initiatorType": "CARDHOLDER",
"accountOnFile": "NOT_STORED",
"paymentMethodType": {
"card": {
"accountNumberType": "PAN",
"accountNumber": "4012000033330026",
"expiry": {
"month": 5,
"year": 2027
}
}
}
}Response:
{
"transactionId": "94d1dd5b-2c81-4896-a159-c726af81883a",
"requestId": "e8cc1a4a-3869-420f-866c-02c53a370182",
"transactionState": "AUTHORIZED",
"amount": 1234,
"currency": "USD",
"responseStatus": "SUCCESS",
"responseCode": "APPROVED",
"responseMessage": "Transaction approved by Issuer",
"approvalCode": "tst825",
"hostMessage": "Approved",
"initiatorType": "CARDHOLDER",
"accountOnFile": "NOT_STORED",
"transactionDate": "2024-07-31T14:16:04.869Z",
"merchant": {
"merchantId": "000017904371",
"merchantSoftware": {
"companyName": "Payment Company",
"productName": "Application Name",
"version": "1.235"
},
"merchantCategoryCode": "4899"
},
"paymentMethodType": {
"card": {
"cardTypeName": "VISA",
"cardType": "VI",
"maskedAccountNumber": "401200XXXXXX0026",
"cardTypeIndicators": {
"issuanceCountryCode": "USA",
"isLevel2Eligible": false,
"isLevel3Eligible": false,
"isDurbinRegulated": false,
"cardProductTypes": [
"COMMERCIAL",
"PINLESS_DEBIT"
]
},
"networkResponse": {
"addressVerificationResult": "NOT_REQUESTED",
"additionalData": {
"electronicCommerceIndicator": "7",
"productId": "F",
"posEntryMode": "01",
"returnAci": "T",
"validationCode": "V7JO"
},
"networkTransactionId": "014213692168401"
}
}
},
"hostReferenceId": "S6JU1UmjVPOQFCmUjthEF7",
"paymentRequest": {
"paymentRequestId": "94d1dd5b-2c81-4896-a159-c726af81883a",
"paymentRequestStatus": "CLOSED",
"refunds": [
{
"refundId": "94d1dd5b-2c81-4896-a159-c726af81883a",
"amount": 1234,
"transactionStatusCode": "CLOSED"
}
]
}
}Multi-capture refund
To refund a multi-capture order (for example, a split shipment), create a separate refund to the /refunds endpoint for each captureId of the previous payment. Refer to the following steps for a multi-capture refund:
- Send the
captureIdvalue in thepaymentMethodType.transactionReference.transactionReferenceIdfield. - The amount of the refund must be less than or equal to the amount of the capture.
The following is an example of a multi-capture refund request:
HTTP method: POST
Endpoint: /refunds
{
"paymentMethodType": {
"transactionReference": {
"transactionReferenceId": "cf0bd1da-0cff-4bf0-a295-d1310c46c513"
}
},
"merchant": {
"merchantSoftware": {
"companyName": "Payment Company",
"productName": "Application Name",
"version": 1.235
}
}
}Response:
{
"transactionId": "c3bf3975-aec4-4ca4-bf86-c05a7ce94150",
"requestId": "7e0e0d62-6107-4b29-8582-276e74f7362e",
"transactionState": "AUTHORIZED",
"amount": 100,
"currency": "USD",
"responseStatus": "SUCCESS",
"responseCode": "APPROVED",
"responseMessage": "Transaction approved by Issuer",
"transactionReferenceId": "cf0bd1da-0cff-4bf0-a295-d1310c46c513",
"remainingRefundableAmount": 0,
"approvalCode": "tst688",
"hostMessage": "Approved",
"initiatorType": "CARDHOLDER",
"accountOnFile": "NOT_STORED",
"transactionDate": "2023-08-21T20:33:46.507Z",
"merchant": {
"merchantId": "000017904371",
"merchantSoftware": {
"companyName": "Payment Company",
"productName": "Application Name",
"version": "1.235"
},
"merchantCategoryCode": "4899"
},
"paymentMethodType": {
"card": {
"cardTypeName": "VISA",
"cardType": "VI",
"maskedAccountNumber": "411234XXXXXX4113",
"cardTypeIndicators": {
"issuanceCountryCode": "USA",
"isDurbinRegulated": false,
"cardProductTypes": [
"COMMERCIAL",
"PINLESS_DEBIT"
]
},
"networkResponse": {
"addressVerificationResult": "NOT_REQUESTED"
},
"isBillPayment": true
}
},
"hostReferenceId": "Vx8VBdcN0XOgmzRuN4tVq2",
"paymentRequest": {
"paymentRequestId": "cf0bd1da-0cff-4bf0-a295-d1310c46c513",
"paymentRequestStatus": "CLOSED",
"authorizations": [
{
"authorizationId": "cf0bd1da-0cff-4bf0-a295-d1310c46c513",
"amount": 1234,
"transactionStatusCode": "CAPTURED",
"authorizationType": "INITIAL"
}
],
"captures": [
{
"captureId": "cf0bd1da-0cff-4bf0-a295-d1310c46c513",
"amount": 100,
"transactionStatusCode": "CLOSED",
"captureRemainingRefundableAmount": 0
},
{
"captureId": "9883af20-b3b9-4b39-9b6e-6cce1b8790a0",
"amount": 100,
"transactionStatusCode": "CLOSED",
"captureRemainingRefundableAmount": 100
},
{
"captureId": "d9921bb1-ee4e-4038-bf8b-a0005fe7aff1",
"amount": 100,
"transactionStatusCode": "CLOSED",
"captureRemainingRefundableAmount": 100
}
],
"refunds": [
{
"refundId": "c3bf3975-aec4-4ca4-bf86-c05a7ce94150",
"amount": 100,
"transactionStatusCode": "CLOSED"
}
]
}
}Manual refund capture
You can authorize a refund and manually capture it at a later time by performing the following steps:
- Send the following in your
POST /refundsauthorization request:- Set
captureMethod=MANUAL. (if captureMethod is not provided, it defaults to NOW and is captured automatically) - For referenced refunds, send the original
transactionIdvalue in thepaymentMethodType.transactionReference.transactionReferenceIdfield. - For standalone refunds, send the card details in the
paymentMethodType.cardfields.
- Set
- Manually capture the refund by sending the following in your
POST /refunds/{id}/capturescapture request:- Set
captureMethod=NOW. - The
idpath parameter is thetransactionIdfrom the refund authorization.
- Set
The following code sample shows you how to authorize a manual refund:
HTTP method: POST
Endpoint: /refunds
Scenario: Perform authorization to manually capture a refund.
{
"captureMethod": "MANUAL",
"merchant": {
"merchantSoftware": {
"companyName": "Mante LLC",
"productName": "Salad",
"version": "2.0"
}
},
"amount": 10000,
"currency": "USD",
"paymentMethodType": {
"card": {
"accountNumber": "4470051300000000003",
"expiry": {
"month": 12,
"year": 2025
},
"cvv": 411
}
}
}Response:
{
"transactionId": "62b49ac6-8214-4ffd-9019-d77748009810",
"requestId": "a1936b91-2f9b-494e-98e1-2c79d0e9f6f0",
"transactionState": "AUTHORIZED",
"captureMethod": "MANUAL",
"amount": 10000,
"currency": "USD",
"responseStatus": "SUCCESS",
"responseCode": "APPROVED",
"responseMessage": "Transaction approved by Issuer",
"approvalCode": "tst505",
"hostMessage": "Approved",
"initiatorType": "MERCHANT",
"accountOnFile": "NOT_STORED",
"transactionDate": "2026-08-28T11:42:38.662Z",
"merchant": {
"merchantId": "998038398379",
"merchantSoftware": {
"companyName": "Mante LLC",
"productName": "Salad",
"version": "2.0"
},
"merchantCategoryCode": "5969"
},
"paymentMethodType": {
"card": {
"cardTypeName": "VISA",
"cardType": "VI",
"maskedAccountNumber": "447005XXXXXXXXX0003",
"cardTypeIndicators": {
"issuanceCountryCode": "USA",
"isLevel2Eligible": false,
"isLevel3Eligible": false,
"cardTypeCategory": "DEBIT_CARD",
"isDurbinRegulated": false,
"cardProductTypes": [
"SIGNATURE_DEBIT"
]
},
"networkResponse": {
"addressVerificationResult": "AVS_NOT_PERFORMED",
"additionalData": {
"electronicCommerceIndicator": "7"
},
"cardVerificationResult": "NO_MATCH",
"cardVerificationResultCode": "N",
"networkResponseCode": "00"
},
"paymentTokens": [
{
"tokenProvider": "SAFETECH",
"tokenNumber": "4470058475315110003",
"responseStatus": "SUCCESS"
}
]
}
},
"hostReferenceId": "W9SEO4KBQkDT6UPsc6OCx1",
"paymentRequest": {
"paymentRequestId": "62b49ac6-8214-4ffd-9019-d77748009810",
"paymentRequestStatus": "PENDING",
"refunds": [
{
"refundId": "62b49ac6-8214-4ffd-9019-d77748009810",
"amount": 10000,
"transactionStatusCode": "AUTHORIZED"
}
]
}
}The following code sample shows you how to manually capture a refund using the transactionId from the authorization:
HTTP method: POST
Endpoint: /refunds/62b49ac6-8214-4ffd-9019-d77748009810/captures
Scenario: Manually capture the refund.
{
"captureMethod": "NOW"
}Response:
{
"transactionId": "62b49ac6-8214-4ffd-9019-d77748009810",
"requestId": "31740af7-5211-421d-98d4-8fa995824a88",
"transactionState": "CLOSED",
"captureMethod": "NOW",
"captureTime": "2026-08-28T11:54:00.660490477Z",
"amount": 10000,
"currency": "USD",
"responseStatus": "SUCCESS",
"responseCode": "ACCEPTED",
"responseMessage": "Transaction accepted",
"approvalCode": "tst505",
"hostMessage": "Approved",
"initiatorType": "MERCHANT",
"accountOnFile": "NOT_STORED",
"transactionDate": "2026-08-28T11:42:38.662Z",
"merchant": {
"merchantId": "998038398379",
"merchantSoftware": {
"companyName": "Mante LLC",
"productName": "Salad",
"version": "2.0"
},
"merchantCategoryCode": "5969"
},
"paymentMethodType": {
"card": {
"cardTypeName": "VISA",
"cardType": "VI",
"maskedAccountNumber": "447005XXXXXXXXX0003",
"cardTypeIndicators": {
"issuanceCountryCode": "USA",
"isLevel2Eligible": false,
"isLevel3Eligible": false,
"cardTypeCategory": "DEBIT_CARD",
"isDurbinRegulated": false,
"cardProductTypes": [
"SIGNATURE_DEBIT"
]
},
"networkResponse": {
"addressVerificationResult": "AVS_NOT_PERFORMED",
"additionalData": {
"electronicCommerceIndicator": "7"
},
"cardVerificationResult": "NO_MATCH",
"cardVerificationResultCode": "N",
"networkResponseCode": "00"
},
"paymentTokens": [
{
"tokenProvider": "SAFETECH",
"tokenNumber": "4470058475315110003",
"responseStatus": "SUCCESS"
}
]
}
},
"hostReferenceId": "W9SEO4KBQkDT6UPsc6OCx1",
"paymentRequest": {
"paymentRequestId": "62b49ac6-8214-4ffd-9019-d77748009810",
"paymentRequestStatus": "CLOSED",
"captures": [],
"refunds": [
{
"refundId": "62b49ac6-8214-4ffd-9019-d77748009810",
"amount": 10000,
"transactionStatusCode": "CLOSED"
},
{
"refundId": "cd38f7c4-dd61-4abf-9395-b4a20eb8a784",
"amount": 10000,
"transactionStatusCode": "CANCELLED"
}
]
}
}Delayed refund capture
You can authorize a refund and automatically capture it at a later time by sending the following in your POST /refunds request:
- Set
captureMethod=DELAYED. (if captureMethod is not provided, it defaults to NOW and gets captured immediately) - For referenced refunds, send the original
transactionIdvalue in thepaymentMethodType.transactionReference.transactionReferenceIdfield. - For standalone refund, send the card details in the
paymentMethodType.cardfields.
The refund is automatically captured based on the capture time set in your profile settings. (captureTime = current time + capture delay time from merchant's profile)
The following code sample shows how to perform a delayed refund transaction:
HTTP method: POST
Endpoint: /refunds
Scenario: Performing an authorization and delayed capture on a refund.
{
"captureMethod": "DELAYED",
"merchant": {
"merchantSoftware": {
"companyName": "Kling, Botsford and Lynch",
"productName": "Fish",
"version": "2.0"
}
},
"amount": 10000,
"currency": "USD",
"paymentMethodType": {
"card": {
"accountNumber": "4470051300000000003",
"expiry": {
"month": 12,
"year": 2025
},
"cvv": 411
}
}
}Response:
{
"transactionId": "cc7c6f9d-1971-49b8-a688-8f2c0451fabb",
"requestId": "5f4dc1a8-7979-40a1-a642-660ae6eca41f",
"transactionState": "AUTHORIZED",
"captureMethod": "DELAYED",
"captureTime": "2026-08-28T14:00:48.119Z",
"amount": 10000,
"currency": "USD",
"responseStatus": "SUCCESS",
"responseCode": "APPROVED",
"responseMessage": "Transaction approved by Issuer",
"approvalCode": "tst304",
"hostMessage": "Approved",
"initiatorType": "MERCHANT",
"accountOnFile": "NOT_STORED",
"transactionDate": "2026-08-28T12:00:48.119Z",
"merchant": {
"merchantId": "998038398379",
"merchantSoftware": {
"companyName": "Kling, Botsford and Lynch",
"productName": "Fish",
"version": "2.0"
},
"merchantCategoryCode": "5969"
},
"paymentMethodType": {
"card": {
"cardTypeName": "VISA",
"cardType": "VI",
"maskedAccountNumber": "447005XXXXXXXXX0003",
"cardTypeIndicators": {
"issuanceCountryCode": "USA",
"isLevel2Eligible": false,
"isLevel3Eligible": false,
"cardTypeCategory": "DEBIT_CARD",
"isDurbinRegulated": false,
"cardProductTypes": [
"SIGNATURE_DEBIT"
]
},
"networkResponse": {
"addressVerificationResult": "AVS_NOT_PERFORMED",
"additionalData": {
"electronicCommerceIndicator": "7"
},
"cardVerificationResult": "NO_MATCH",
"cardVerificationResultCode": "N",
"networkResponseCode": "00"
},
"paymentTokens": [
{
"tokenProvider": "SAFETECH",
"tokenNumber": "4470058475315110003",
"responseStatus": "SUCCESS"
}
]
}
},
"hostReferenceId": "10co0HkJP7UtecHVGofzJ4",
"paymentRequest": {
"paymentRequestId": "cc7c6f9d-1971-49b8-a688-8f2c0451fabb",
"paymentRequestStatus": "PENDING",
"refunds": [
{
"refundId": "cc7c6f9d-1971-49b8-a688-8f2c0451fabb",
"amount": 10000,
"transactionStatusCode": "AUTHORIZED"
}
]
}
}Retrieve refund details
After you process a refund, refer to the following steps to obtain the refund details:
- Send a
GETrequest to the/refundsendpoint in one of two ways:- Use the
requestIdfrom the original response as a query parameter in a newGETrequest. - Use the
transactionIdfrom the original response as a path parameter in a newGETrequest.
- Use the