List secure tokens

Browse API reference

GET/processing-terminals/{processingTerminalId}/secure-tokenslistSecureTokens

Use this method to return a paginated list of secure tokens.

Note: If you want to view the details of a specific secure token and you have its secureTokenId, use our Retrieve Secure Token method.

Use query parameters to filter the list of results that we return, for example, to search for secure tokens by customer or by the first four digits of a card number.

Our gateway returns information about the following for each secure token in the list:

Payment details that the secure token represents.
Customer details, including shipping and billing addresses.
Secure token that you can use to carry out transactions.

For each secure token, we also return the secureTokenId, which you can use to perform follow-on actions.

Parameters

Name	In	Type	Description
`processingTerminalId`Required	path	`string`	Unique identifier that we assigned to the terminal.
`secureTokenId`	query	`string`	Unique identifier that the merchant assigned to the secure token.
`customerName`	query	`string`	Filter by the customer's name.
`phone`	query	`string`	Filter by the customer's phone number.
`email`	query	`string`	Filter by the customer's email address.
`token`	query	`string`	Filter by the token that the merchant used in a transaction to represent the customer's payment details.
`first6`	query	`string`	Filter by the first six digits of the card number.
`last4`	query	`string`	Filter by the last four digits of the card or account number.
`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 secure tokens that are currently saved on the terminal.

200 OK · application/json

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

Response schema · 78 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 saved payment details.
- 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
- mitAgreementstring
  Indicates how the merchant can use the customer's card details, as agreed by the customer: unscheduled Transactions for a fixed or variable amount that are run at a certain pre-defined event. recurring Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. installment Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration.unscheduledrecurringinstallment
- processingTerminalIdstringrequired
  Unique identifier that we assigned to the terminal.4–50 chars
- secureTokenIdstringrequired
  Unique identifier that the merchant created for the secure token that represents the customer's payment details.0–200 chars
- sourceobjectrequired
  Polymorphic object that contains the payment method that we tokenized. The value of the type parameter determines which variant you should use: ach Automated Clearing House (ACH) details pad Pre-authorized debit (PAD) details card Payment card details
  - achobject
    Object that contains the customer's account details.
    accountNumberstringrequired
    Customer's account number.4–17 chars^[0-9]*$
    nameOnAccountstringrequired
    Customer's name.1–50 chars
    routingNumberstringrequired
    Routing number of the customer's account.9–9 chars^[0-9]*$
    typestringrequired
    ach
  - padobject
    Object that contains the customer's account details.
    accountNumberstringrequired
    Customer's account number.7–12 chars^[0-9]*$
    institutionNumberstringrequired
    Three-digit code that represents the customer's bank.3–3 chars^[0-9]*$
    nameOnAccountstringrequired
    Customer's name.1–29 chars
    transitNumberstringrequired
    Five-digit code that represents the customer's banking branch.5–5 chars^[0-9]*$
    typestringrequired
    pad
  - Cardobject
    Object that contains the customer's card details.
    cardNumberstringrequired
    Primary account number of the customer's card.12–19 chars
    cardTypestring
    Card brand of the card, for example, Visa.
    cardholderNamestringrequired
    Cardholder's name.1–50 chars
    currencystring
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
    debitboolean
    Indicates if the card is a debit card.
    expiryDatestring
    Expiry date of the customer's card.[0-9]{4}
    surchargingobject
    Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions.
    allowedbooleanrequired
    Indicates if the merchant can add a surcharge when the customer uses this card.
    amountintegerint64
    Surcharge amount to add to the transaction. Note: Our gateway returns the surcharge amount only if you include a transaction amount in the request.
    disclosurestring
    Statement that informs the customer about the surcharge fee.
    percentagenumberdouble
    Surcharge rate that the merchant configures on their account.≤ 100
    typestringrequired
    Type of payment.card
- statusstringrequired
  Outcome of a security check on the status of the customer's payment card or bank 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

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

delete-a-saved-payment-method refresh-a-saved-payment-method update-a-saved-payment-method