List refunds

Browse API reference

GET/bank-transfer-refundslistBankTransferRefunds

Use this method to return a paginated list of bank transfer 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, an orderId, or a date range.

Our gateway returns the following information about each refund in the list:

Order details, including the refund amount and when it was processed.
Bank account details, including the customer’s name and account number.

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

Parameters

Name	In	Type	Description
`processingTerminalId`Required	query	`string`	Filter results by the unique identifier that we assigned to the terminal.
`orderId`	query	`string`	Filter results by the order ID of the refund.
`nameOnAccount`	query	`string`	Filter results by the accountholder's name.
`last4`	query	`string`	Filter results by the last four digits of the account number.
`type`	query	`array`	Filter results by transaction type.
`status`	query	`array`	Filter results by the status of the refund.
`dateFrom`	query	`string`	Filter results by refunds that the merchant ran after a specific date. The value follows the ISO 8601 standard.
`dateTo`	query	`string`	Filter results by refunds that the merchant ran before a specific date. The value follows the ISO 8601 standard.
`settlementState`	query	`string`	Filter results by the settlement status.
`settlementDate`	query	`string`	Filter results by the settlement date. Send a value in YYYY-MM-DD format.
`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 list of refund transactions.

200 OK · application/json

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

Response schema · 85 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 transactions.
- bankAccountobjectrequired
  Polymorphic object that contains bank account information. The value of the type field determines which variant you should use: ach Automated Clearing House (ACH) details pad Pre-authorized debit (PAD) details
  - achobject
    Object that contains the customer's account details.
    accountNumberstringrequired
    Customer's bank account number. We mask all digits except the last four digits.4–17 chars
    nameOnAccountstringrequired
    Customer's name.1–50 chars
    routingNumberstringrequired
    Routing number of the customer’s account. Note: In responses, our gateway shows only the last four digits of the account's routing number, for example, *****4162.9–9 chars
    secCodestring
    Indicates the type of authorization for the transaction. Note: The field is mandatory for ACH secure token. web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction.webtelccdppd
    secureTokenobject
    Object that contains information about the secure token.
    customerNamestringrequired
    Customer's name.1–50 chars
    linkobject
    Object that contains HATEOAS links for the resource.
    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.
    secureTokenIdstringrequired
    Unique identifier that the merchant assigned to the secure token.1–200 chars
    statusstringrequired
    Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
    tokenstringrequired
    Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
    typestringrequired
    ach
  - padobject
    Object that contains the customer's account details.
    accountNumberstringrequired
    Customer's bank account number. We mask all digits except the last four digits.7–12 chars
    institutionNumberstringrequired
    Three-digit code that represents the customer's bank.3–3 chars
    nameOnAccountstringrequired
    Customer's name.1–29 chars
    secureTokenobject
    Object that contains information about the secure token.
    customerNamestringrequired
    Customer's name.1–50 chars
    linkobject
    Object that contains HATEOAS links for the resource.
    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.
    secureTokenIdstringrequired
    Unique identifier that the merchant assigned to the secure token.1–200 chars
    statusstringrequired
    Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
    tokenstringrequired
    Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
    transitNumberstringrequired
    Five-digit code that represents the customer's banking branch.5–5 chars
    typestringrequired
    pad
- 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 information about the customer.
  - 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
    emailobject
    typestringrequired
    Type of contact method.email
    valuestringrequired
    Email address.≤ 50 chars
    phoneobject
    typestringrequired
    Type of contact method.phone
    valuestringrequired
    Phone number.≤ 15 chars
    mobileobject
    typestringrequired
    Type of contact method.mobile
    valuestringrequired
    Mobile number.≤ 15 chars
    faxobject
    typestringrequired
    Type of contact method.fax
    valuestringrequired
    Fax number.≤ 15 chars
  - notificationLanguagestringiso-639-1
    Customer's preferred notification language. This code follows the ISO 639-1 standard.2–2 charsenfr
- orderobjectrequired
  Object that contains information about the order.
  - 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
- 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.
    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.
  - 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
- transactionResultobjectrequired
  Object that contains information about the transaction.
  - authorizedAmountintegerint64
    Amount of the transaction. Note: The amount is negative for a refund.
  - currencystring
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  - 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.
  - responseMessagestring
    Description of the response 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 when the batch is closed. declined Unsuccessful transaction. The customer's bank declined the transfer. complete Successful transaction. The funds have moved to the merchant’s bank account. admin Transaction under review. We have flagged an issue with the transaction. reversal Transaction canceled. The transaction was canceled, and we removed the transaction from the open batch. returned Unsuccessful transaction. Automated clearing house (ACH) returned the transaction due to an error. For more information about the error, view the returns object.readypendingdeclinedcompleteadminreversalreturned
  - typestringrequired
    Type of transaction.paymentrefundunreferencedRefundaccountVerification

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

reverse-a-bank-transfer-refund