List transactions

Browse API reference

GET/transactionsgetTransactions

Use this method to return a paginated list of your merchants’ transactions.

Note: If you want to view the details of a specific transaction and you have its transactionId, use our Retrieve Transaction method.

Use query parameters to filter the list of results that we return, for example, to search for transactions for a specific merchant.

Important: You must provide a value for either the date query parameter or the batchId query parameter.

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

Merchant and processing account that ran the transaction.
Transaction type, date, amount, and the payment method that the customer used.
Batch that contains the transaction, and authorization details for the transaction.
Processor that settled the transaction and the ACH deposit containing the transaction.

Parameters

Name	In	Type	Description
`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.
`date`	query	`string`	Filter transactions by the date that the merchant submitted the batch that contains the transaction. The format of this value is YYYY-MM-DD. You must provide either the batchId or the date.
`batchId`	query	`integer`	Filter transactions by the unique identifier of the batch that contains the transaction. You must provide either the batchId or the date.
`merchantId`	query	`string`	Filter results by the unique identifier that the processor assigned to the merchant.
`transactionType`	query	`string`	Filter transactions by transaction type.

Responses

Successful request. Returns a paginated list of transactions.

200 OK · application/json

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

Response schema · 48 of 60 fields

countinteger
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMoreboolean
Indicates whether there is another page of results available.
limitinteger
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 transaction objects.
- amountinteger
  Transaction amount. We return the value in the currency's lowest denomination, for example, cents.
- authorizationobject
  Object that contains information about the authorization.
  - amountinteger
    Authorization amount. We return the value in the currency's lowest denomination, for example, cents.
  - authorizationIdinteger
    Unique identifier of the authorization.
  - avsResponseCodestring
    Response code that indicates if the address matches the address registered to the customer.
  - codestring
    Authorization code. Note: For returns, the card brands may not provide an authorization code.
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
- batchobjectnull
  Object that contains information about the batch. If we can't match a dispute to a batch, we don't return 'batch' object.
  - batchIdinteger
    Unique identifier of the batch.
  - cyclestring
    Indicates the cycle that contains the batch.
  - datestringdate
    Date that the merchant submitted the batch.
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
- cardobject
  Object that contains information about the card.
  - avsRequestboolean
    Indicates whether the merchant used the Address Verification Service (AVS) to verify the cardholder's address.
  - avsResponsestring
    Response from the Address Verification Service (AVS).
  - cardNumberstring
    Masked card number. Our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000.
  - cvvPresenceIndicatorboolean
    Indicates whether the cardholder provided the Card Verification Value (CVV).
  - typestringnull
    Card type, for example, Visa. Note: If we can’t match a dispute to a transaction, we don’t return a type object.visamasterCarddiscoverdebitebtwrightExpressvoyageramex+8 more
- cashbackAmountinteger
  Cashback amount. We return the value in the currency's lowest denomination, for example, cents.
- createdDatestringdate
  Date that we received the transaction. The format of this value is YYYY-MM-DD.
- currencystring
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.
- datestringdate
  Date of the transaction. The format of this value is YYYY-MM-DD.
- entryMethodstringnull
  Indicates how the merchant received the payment details.barcodeReadsmartChipReadswipedOriginUnknowncontactlessChipecommercemanuallyEnteredmanuallyEnteredFallbackswiped+5 more
- interchangeobject
  Object that contains information about the interchange fees for the transaction.
  - basisPointinteger
    Interchange basis points that we apply to the transaction.
  - transactionFeeinteger
    Interchange fee for the transaction. We return the value in the currency's lowest denomination, for example, cents.
- lastModifiedDatestringdate
  Date that the transaction was last changed. The format of this value is YYYY-MM-DD.
- merchantobject
  Object that contains information about the merchant.
  - doingBusinessAsstring
    Trading name of the business.
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
  - merchantIdstring
    Unique identifier that the processor assigned to the merchant.
  - processingAccountIdinteger
    Unique identifier that we assigned to the processing account.
- settledobject
  Object that contains information about the settlement.
  - achDatestringdate
    Date that the processor settled the transaction. The format of this value is YYYY-MM-DD.
  - achDepositIdinteger
    Unique identifier of the ACH deposit.
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
  - settledBystring
    Processor that settled the transaction.
- statusstring
  Indicates the status of the transaction. The value is one of the following: fullSuspense – Merchant ran the transaction while their account was in full suspense. heldAudited – We have moved a transaction from fullSuspense and placed it on hold. heldReleasedAudited – We audited and released the transaction that we had previously held. holdForSettlement30Days We are holding the transaction for a maximum of 30 days. holdForSettlementDuplicate We held the transaction because the transaction may be a duplicate. holdLongTerm We are holding the transaction for an extended period. paid – We have paid the transaction funds to the merchant. paidByThirdParty A third party has paid the transaction funds to the merchant. partialRelease – We partially released the transaction funds. pull We pulled the transaction, and the merchant does not receive funds for the transaction. release We released the transaction that we previously held. new – We have prepared the funds from the transaction to send to the merchant. held – We held the transaction. unknown – No transaction status available.fullSuspenseheldAuditedheldReleasedAuditedholdForSettlement30DaysholdForSettlementDuplicateholdLongTermpaidpaidByThirdParty+6 more
- transactionIdintegernull
  Unique identifier that we assigned to the transaction.
- typestring
  Indicates the type of transaction. The value is one of the following: capture Transaction is a sale. return Transaction is a refund.capturereturn

Validation error

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid value",
      "message": "Expected integer, got abc",
      "parameter": "before"
    }
  ],
  "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

review-settlement-reporting