Skip to content
developers

List payments

Browse API reference

GET/paymentslistPayments

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 tip mode, or a date range.

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

  • Order details, including the transaction amount and when it was processed.
  • Payment card details, including the masked card number, expiry date, and payment method.
  • Cardholder details, including their contact information and shipping address.
  • Payment details, including the payment type, status, and response.

For each transaction, we also return the paymentId and an optional secureTokenId, which you can use to perform follow-on actions.

Parameters

NameInTypeDescription
processingTerminalIdquerystring

Filter by terminal ID.

orderIdquerystring

Filter payments by order ID.

operatorquerystring

Filter payments by operator.

cardholderNamequerystring

Filter payments by the cardholder’s name.

first6querystring

Filter payments by the first six digits of the card number that the customer used in the transaction.

last4querystring

Filter payments by the last four digits of the card number that the customer used in the transaction.

tenderquerystring

Filter by tender type.

tipModequeryarray

Filter payments by tip.

typequeryarray

Filter payments by transaction type.

statusqueryarray

Filter payments by the status of the transaction.

dateFromquerystring

Filter by payments that the processor processed after a specific date. The date format follows the ISO 8601 standard.

dateToquerystring

Filter by payments that the processer processed before a specific date. The date format follows the ISO 8601 standard.

settlementStatequerystring

Filter payments by the settlement status of the transaction.

settlementDatequerystring

Filter by payments that the processor settled on a specific date in the format YYYY-MM-DD.

paymentLinkIdquerystring

Unique identifier that our gateway assigned to the payment link.

beforequerystring

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.

afterquerystring

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.

limitqueryinteger

Limit the maximum number of results that we return for each page.

Responses

Successful request. Returns a list of payments.

200 OK · application/json
{
  "count": 0,
  "data": [],
  "hasMore": false,
  "limit": 10,
  "links": []
}
Response schema · 168 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 transactions.
    • 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.
        • amountintegerint64required
          Current balance of the account. This value is in the currency's lowest denomination, for example, cents.
        • benefitCategorystringrequired
          Indicates if the balance relates to an EBT Cash account or EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
        • currencystringrequired
          Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
      • 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.
        • hexstringrequired
          Hex code of the EMV tag.
        • valuestringrequired
          Value of the EMV tag.
      • 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.
        • 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
      • securityChecksobject
        Object that contains information about card verification and security checks.
        • avsResultstring
          Indicates if the address that the customer provided in the request matches the address linked to the card. Y – The address in the request matches the address linked to the card. N – The address in the request doesn’t match the address linked to the card. A – The street address matches, but ZIP code or postal code doesn’t match. Z The ZIP code or postal code matches, but street address doesn’t match. U – The address information is unavailable. G – The issuer or card brand doesn’t support the Address Verification Service (AVS). R – The AVS is currently unavailable. Try again later. S – There was no AVS data in the request, or it was sent in the wrong format. F For UK addresses, the address in the request matches the address linked to the card. W – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. X – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. Note: Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account.YAZNURGS+3 more
        • cvvResultstring
          Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. M – The CVV matches the card’s CVV. N – The CVV doesn’t match the card’s CVV. P – The CVV wasn’t processed. U – The CVV isn’t registered. Note: Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account.MNPU
      • 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.
        • address1string
          Address line 1.≤ 150 chars
        • address2string
          Address line 2.≤ 150 chars
        • address3string
          Address line 3.≤ 150 chars
        • citystring
          City.≤ 50 chars
        • countrystring
          Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
        • postalCodestring
          Zip code or postal code.≤ 10 chars
        • statestring
          Name of the state or state abbreviation.≤ 50 chars
      • 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
      • 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.
        • addressobject
          Object that contains information about the address.
          • address1string
            Address line 1.≤ 150 chars
          • address2string
            Address line 2.≤ 150 chars
          • address3string
            Address line 3.≤ 150 chars
          • citystring
            City.≤ 50 chars
          • countrystring
            Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
          • postalCodestring
            Zip code or postal code.≤ 10 chars
          • statestring
            Name of the state or state abbreviation.≤ 50 chars
        • recipientNamestring
          Recipient's name.0–50 chars
    • operatorstring
      Operator who initiated the request.0–50 chars
    • orderobjectrequired
      Object that contains information about the payment.
      • breakdownobject
        Object that contains information about the breakdown of the transaction. Contains parameters required for Level 2, Level 3, and CEDP transactions.
        • convenienceFeeobject
          Object that contains information about the convenience fee for the transaction.
          • amountintegerint64required
            If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents.
        • dutyAmountintegerint64
          Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
        • freightAmountintegerint64
          Amount for shipping in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
        • itemsobject[]
          Array of objects that contain information about each item that the customer purchased. Contains parameters required for Level 3 and CEDP transactions.
          • commodityCodestring
            Commodity code of the item. Required for Level 3 and CEDP transactions.0–45 chars
          • descriptionstring
            Description of the item. Required for Level 3 and CEDP transactions.0–250 chars
          • discountRatenumberdouble
            Discount rate that the merchant applies to the item. Required for Level 3 and CEDP transactions.
          • productCodestring
            Product code of the item. Required for Level 3 and CEDP transactions.0–45 chars
          • quantitynumberdoublerequired
            Number of units. Required for Level 3 and CEDP transactions.
          • unitOfMeasurestring
            Unit of measurement for the item. For more information about units of measurement, go to Units of measurement.ACRAMHAMPAPZAREASMASVATM+208 more
          • unitPriceintegerint64required
            Price of each unit. Required for Level 3 and CEDP transactions.
          • taxesobject[]
            Array of objects that contain information about each tax that applies to the item. Required for Level 3 and CEDP transactions.
            • 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
        • cashbackAmountintegerint64
          Amount of cashback for the transaction.
        • dualPricingobject
          Object that contains information about dual pricing.
          • alternativeTenderstring
            Payment method that the merchant presented to the customer as an alternative to their chosen method. Note: For requests, if the value for offered is true, you must send a value for alternativeTender in the request.cardcashbankTransfer
          • choiceRateobject
            Object that contains information about the choice rate. We return this only if the value for offered was true.
            • amountintegerint64required
              If the customer used a card to pay for the transaction, this value indicates the amount that our gateway added to the transaction amount. This value is in the currency’s lowest denomination, for example, cents. Note: Our gateway returns a value for amount only if the value for applied in the request is true.
            • appliedbooleanrequired
              Indicates if the merchant applies a choice rate to the transaction amount. Our gateway adds a choice rate to the transaction when the merchant offers an alternative payment type, but the customer chooses to pay by card.
            • ratenumberdoublerequired
              If the customer used a card to pay for the transaction, this value indicates the percentage that our gateway added to the transaction amount. Note: Our gateway returns a value for rate only if the value for applied in the request is true.≤ 100
          • offeredbooleanrequired
            Indicates if the merchant offered dual pricing to the customer.
        • healthcareExpensesobject[]
          Array of healthcareExpense objects that contain information about healthcare expenses.
          • amountintegerint64required
            Amount of the healthcare expense. The value is in the currency's lowest denomination, for example, cents.
          • typestringrequired
            Type of healthcare expense.copayclinicdentalprescriptiontransitvision
        • subtotalintegerint64required
          Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. Required for Level 2, Level 3, and CEDP transactions.
        • surchargeobject
          Object that contains information about the surcharge.
          • amountintegerint64
            If the merchant added a surcharge fee, this value indicates the amount of the surcharge fee in the currency’s lowest denomination, for example, cents.
          • bypassboolean
            Indicates if the merchant wants to remove the surcharge fee from the transaction. true Gateway removes the surcharge fee from the transaction. false Gateway adds the fee to the transaction.
          • percentagenumberdouble
            If the merchant added a surcharge fee, this value indicates the surcharge percentage.≤ 100
        • 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
        • taxesobject[]
          List of taxes.
          • 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
      • 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
      • dccOfferobject
        Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to Dynamic Currency Conversion.
        • acceptedboolean
          Indicates if the cardholder accepted DCC offer.
        • fxAmountintegerint64required
          Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents.
        • fxCurrencystringrequired
          Currency of the transaction in the card’s currency. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
        • fxCurrencyCodestring
          Three-digit currency code for the card. This code follows the ISO 4217 standard.3–3 chars
        • fxCurrencyExponentintegerint32
          Number of decimal places between the smallest currency unit and a whole currency unit. For example, for GBP, the smallest currency unit is 1p and it is equal to £0.01. If you use GBP, the value for fxCurrencyExponent is 2.
        • fxRatenumberdoublerequired
          Foreign exchange rate for the card's currency.
        • markupnumberdoublerequired
          Markup percentage rate that the DCC provider applies to the foreign exchange rate.
        • markupTextstring
          Supporting text for the markup rate.
        • offerReferencestring
          Unique identifier of the DCC offer.
        • providerstring
          Name of the DCC provider.
        • sourcestring
          Source that the DCC provider used to get the foreign exchange rates.
      • standingInstructionsobject
        Object that contains information about repeat payments. Include this object if the payment is part of a recurring billing schedule and you don't use our subscriptions feature.
        • processingModelstringrequired
          Indicates the type of payment schedule. 'unscheduled' – The payment is not part of a regular billing cycle. 'recurring' – The payment is part of a regular billing cycle with no end date. 'installment' – The payment is part of a regular billing cycle with an end date.unscheduledrecurringinstallment
        • referenceDataOfFirstTxnobject
          Object that contains information about the first payment.
          • cardSchemeReferenceIdstring
            Identifier that the card brand assigned to the first payment.1–64 chars
          • paymentIdstring
            Unique identifier of the first payment. Note: We recommend that you always send a value for the paymentId parameter.10–10 chars
        • sequencestringrequired
          Indicates if this payment is the first payment or if it is a subsequent payment.firstsubsequent
    • paymentIdstringrequired
      Unique identifier that our gateway assigned to the transaction.10–10 chars
    • processingTerminalIdstringrequired
      Unique identifier of the terminal that initiated the transaction.4–50 chars
    • refundsobject[]
      Array of refundSummary objects. Each object contains information about refunds linked to the transaction.
      • 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
    • 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

Used in workflows

adjust-a-paymentrefund-a-card-paymentreverse-a-card-payment

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer