List refunds

Browse API reference

GET/refundslistRefunds

Use this method to return a paginated list of refunds.

Note: If you want to view the details of a specific refund and you have its refundId, use our Retrieve Refund method.

Use query parameters to filter the list of results that we return, for example, to search for refunds for a customer, a tender type, or a date range. Our gateway returns the following information about each refund in the list:

Order details, including the refund amount and when we processed the refund.
Payment card details, including the masked card number, expiry date, and payment method.
Cardholder details, including their contact information and shipping address.

For referenced refunds, our gateway also returns details about the payment that the refund is linked to.

Parameters

Name	In	Type	Description
`processingTerminalId`	query	`string`	Filter by terminal ID.
`orderId`	query	`string`	Filter refunds by the unique identifier that the merchant assigned to the order.
`operator`	query	`string`	Filter refunds by the operator who initiated the request.
`cardholderName`	query	`string`	Filter refunds by cardholder name.
`first6`	query	`string`	Filter refunds by the first six digits of the card number.
`last4`	query	`string`	Filter refunds by the last four digits of the card number.
`tender`	query	`string`	Filter by tender type.
`status`	query	`array`	Filter refunds by the current status of the refund.
`dateFrom`	query	`string`	Filter by refunds processed after a specific date. The date format follows the ISO 8601 standard.
`dateTo`	query	`string`	Filter by refunds processed before a specific date. The date format follows the ISO 8601 standard.
`settlementState`	query	`string`	Status of the settlement.
`settlementDate`	query	`string`	Date the transaction was settled.
`before`	query	`string`	Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter.
`after`	query	`string`	Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter.
`limit`	query	`integer`	Limit the maximum number of results that we return for each page.

Responses

Successful request. Returns a paginated list of refunds.

200 OK · application/json

{
  "count": 0,
  "data": [],
  "hasMore": false,
  "limit": 10,
  "links": []
}

Response schema · 63 of 120 fields

countintegerrequired
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMorebooleanrequired
Indicates whether there is another page of results available.
limitintegerrequired
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
dataobject[]required
Array of refund objects.
- cardobjectrequired
  Object that contains the details of the payment card.
  - balancesobject[]
    Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card.+3 more fields at deeper levels — see the full spec
  - cardNumberstringrequired
    Masked card number. Our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000.12–19 chars
  - cardholderNamestring
    Cardholder’s name.1–50 chars
  - cardholderSignaturestring
    Cardholder’s signature.
  - emvTagsobject[]
    Array of emvTag objects.+2 more fields at deeper levels — see the full spec
  - entryMethodstring
    Method that the device used to capture the card details.icckeyedswipedswipedFallbackcontactlessIcccontactlessMsr
  - expiryDatestringrequired
    Expiry date of the customer's card. The format is in MMYY.[0-9]{4}
  - secureTokenobject
    Object that contains information about the secure token.+8 more fields at deeper levels — see the full spec
  - securityChecksobject
    Object that contains information about card verification and security checks.+2 more fields at deeper levels — see the full spec
  - typestringrequired
    Card brand that the card is linked to. For example, Visa.
- customFieldsobject[]
  Array of customField objects.
  - namestringrequired
    Name of the custom field.1–56 chars
  - valuestringrequired
    Value for the custom field.1–100 chars
- customerobject
  Object that contains the customer's contact details and address information.
  - billingAddressobject
    Object that contains information about the address.+7 more fields at deeper levels — see the full spec
  - contactMethodsobject[]
    Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number+12 more fields at deeper levels — see the full spec
  - dateOfBirthstringdate
    Customer's date of birth. The format for this value is YYYY-MM-DD.
  - firstNamestring
    Customer's first name.0–60 chars
  - lastNamestring
    Customer's last name.0–60 chars
  - notificationLanguagestringiso-639-1
    Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard.2–2 charsenfr
  - referenceNumberstring
    Identifier of the transaction, also known as a customer code. For requests, you must send a value for referenceNumber if the customer provides one.0–48 chars
  - shippingAddressobject
    Object that contains information about the customer and their shipping address.+9 more fields at deeper levels — see the full spec
- operatorstring
  Operator who requested the refund.0–50 chars
- orderobjectrequired
  Object that contains information about the refund.
  - amountintegerint64required
    Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents.
  - currencystringrequired
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  - dateTimestringdate-time
    Date and time that the processor processed the transaction. Our gateway returns this value in the ISO 8601 format.
  - descriptionstringrequired
    Description of the transaction.0–1024 chars
  - orderIdstringrequired
    Unique identifier that the merchant assigns to the transaction.1–24 chars
  - dccOfferobject
    Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to Dynamic Currency Conversion.+11 more fields at deeper levels — see the full spec
- paymentobject
  Object that contains information about a payment.
  - amountintegerint64required
    Amount of the payment. This value is in the currency’s lowest denomination, for example, cents.
  - currencystringrequired
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  - dateTimestringdate-timerequired
    Date and time that the payment was processed.
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
  - paymentIdstringrequired
    Unique identifier of the payment.10–10 chars
  - responseCodestringrequired
    Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
  - responseMessagestring
    Response description from the processor.1–48 chars
  - statusstringrequired
    Current status of the payment.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
- processingTerminalIdstringrequired
  Unique identifier that we assigned to the terminal.4–50 chars
- refundIdstringrequired
  Unique identifier that our gateway assigned to the refund.10–10 chars
- supportedOperationsstring[]
  Array of operations that you can perform on the transaction. Our gateway can return any of the following values: capture Capture the payment. refund Refund the payment. fullyReverse Fully reverse the transaction. partiallyReverse Partially reverse the payment. incrementAuthorization Increase the amount of the authorization. adjustTip Adjust the tip post-payment. addSignature Add a signature to the payment. setAsReady Set the transaction’s status to `ready`. setAsPending Set the transaction’s status to `pending`.
- transactionResultobjectrequired
  Object that contains information about the transaction response details.
  - approvalCodestring
    Authorization code that the processor assigned to the transaction.1–48 chars
  - authorizedAmountintegerint64
    Amount that the processor authorized for the transaction. This value is in the currency’s lowest denomination, for example, cents. Notes: For partial authorizations, this amount is lower than the amount in the request. If the value for authorizedAmount is negative, this indicates that the merchant sent funds to the customer.
  - cardSchemeReferenceIdstring
    Identifier that the card brand assigns to the payment instruction.1–64 chars
  - currencystring
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  - ebtTypestring
    Indicates the subtype of EBT in the transaction.cashPurchasecashPurchaseWithCashbackfoodStampPurchasefoodStampVoucherPurchasefoodStampReturnfoodStampVoucherReturncashBalanceInquiryfoodStampBalanceInquiry+1 more
  - healthcareIndicatorstring
    Indicates if we processed the payment as a healthcare expense. The value is one of the following: Y We processed the payment as a healthcare expense. N We processed the payment but it didn't contain any healthcare expenses. C We processed the payment but the card isn't linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). R We processed the payment but the card doesn't support healthcare expenses.YNCR
  - processorResponseCodestring
    Original response code that the processor sent.
  - responseCodestringrequired
    Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
  - responseMessagestring
    Response description from the processor.1–48 chars
  - statusstringrequired
    Status of the transaction. The value is one of the following: ready Successful transaction. We added the payment to the open batch. pending Successful transaction. We added the payment to the open batch, but we don't collect the funds until the merchant captures the transaction. declined Unsuccessful transaction. The cardholder's issuing bank declined the transaction. complete Successful transaction. The funds have moved to the merchant's bank account. referral Unsuccessful transaction. The issuing bank identified an issue with the transaction. You should treat a referral status as a declined transaction. pickup Unsuccessful transaction. The issuing bank has reported that the card is lost or stolen. reversal Transaction canceled. The transaction was canceled, and we removed the transaction from the open batch. admin Transaction under review. We have flagged an issue with the transaction. expired Transaction expired. If a transaction stays in pending status for too long, it expires. accepted Transaction in progress. The transaction is in progress with the processor but we can't confirm the result yet.readypendingdeclinedcompletereferralpickupreversaladmin+2 more
  - typestring
    Transaction type.salerefundpreAuthorizationpreAuthorizationCompletion

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

adjust-a-refund reverse-a-refund