Use this method to return a paginated list of payments.
Note: If you want to view the details of a specific payment and you have its paymentId, use our Retrieve Payment method.
Use query parameters to filter the list of results that we return, for example, to search for payments for a customer, a date range, or a settlement state.
Our gateway returns the following information about each payment in the list:
Order details, including the transaction amount and when it was processed.
Bank account details, including the customer’s name and account number.
Customer's details, including the customer’s phone number.
Transaction details, including any refunds or re-presentments.
For each transaction, we also return the paymentId and an optional secureTokenId, which you can use to perform follow-on actions.
Parameters
Name
In
Type
Description
processingTerminalIdRequired
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 payment.
nameOnAccount
query
string
Filter results by the account holder'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 payment.
dateFrom
query
string
Filter results by payments that the merchant ran after a specific date. The value follows the ISO 8601 standard.
dateTo
query
string
Filter results by payments 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.
paymentLinkId
query
string
Filter results by the paymentLinkId.
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.
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 payments.
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 transaction.
breakdownobject
Object that contains information about the transaction.
taxesobject[]
Array of tax objects.
amountintegerint64
Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
namestringrequired
Name of the tax.1–64 chars
ratenumberdoublerequired
Tax percentage for the transaction.0–99.99999
subtotalintegerint64required
Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents.
tipobject
Object that contains information about the tip.
amountintegerint64
If the value for type is fixedAmount, this value is the tip amount in the currency's lowest denomination, for example, cents.
modestring
Indicates how the tip was added to the transaction. prompted – The customer was prompted to add a tip during payment. adjusted – The customer added a tip on the receipt for the merchant to adjust post-transaction.promptedadjusted
percentagenumberdouble
If the value for type is percentage, this value is the tip as a percentage.≤ 100
typestringrequired
Indicates if the tip is a fixed amount or a percentage. Note: Our gateway applies the percentage tip to the total amount of the transaction after tax.percentagefixedAmount
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.
descriptionstring
Description of the transaction.0–1024 chars
orderIdstringrequired
Unique identifier that the merchant assigns to the transaction.1–24 chars
paymentIdstringrequired
Unique identifier that we assigned to the payment.10–10 chars
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars
refundsobject[]
List of refunds issued against the payment.
amountintegerint64required
Amount of the refund. 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 refund 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.
refundIdstringrequired
Unique identifier of the refund.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
responseMessagestringrequired
Description of the response from the processor.1–48 chars
statusstringrequired
Current status of the refund.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
representmentobject
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
returnsobject[]
List of returns issued against the payment.
closedbooleanrequired
Indicates whether the merchant accepted an alternative payment method to complete the payment.
datestringdaterequired
The date that the check was returned.
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 that our gateway assigned to the payment.10–10 chars
representedbooleanrequired
Indicates whether the return has been re-presented.
returnCodestringrequired
The NACHA return code.
returnReasonstringrequired
The reason why the check was returned.
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"}