# Retrieve payment instruments

Retrieves a list of payment instruments.

Endpoint: GET /payment-instruments
Version: latest
Security: SecretApiKey, JWT

## Query parameters

- `filter` (string)
  Criteria for filtering collection items. This field requires a special format. Use `,` to specify multiple allowed values. Use `;` to specify multiple fields. For more information, see [Search filters](https://www.rebilly.com/docs/dev-docs/search-filters).
- `sort` (array)
  Sorts and orders the collection of items. To sort in descending order, prefix with `-`. Multiple fields can be sorted by separating each with `,`.
- `limit` (integer)
  Limit the number of collection items to be returned. Use `0` to return an empty collection and still receive the count of matching items in `Pagination-Total`.
- `offset` (integer)
  Specifies the starting point within the collection of items to be returned.
- `q` (string)
  Use this field to perform a partial search of text fields.
- `expand` (string)
  Expands a request to include embedded objects within the `_embedded` property of the response. This field accepts a comma-separated list of objects. For more information, see [Embedded resources](https://www.rebilly.com/docs/dev-docs/expand-embedded-resources).

## Response 200 fields

- `id` (string)
  ID of the payment instrument.
  Example: inst_0YVB8KPKNXCBR9EDX7JHSED75N
- `customerId` (string)
  ID of the customer resource.
  Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF
- `method` (string, required)
  Method of payment instrument.
  Enum: "paypal"
- `status` (string)
  Status of the payment instrument. An `active` status means that a payment instrument has been used at least once for an approved transaction. To remove an instrument from use, set this value to `deactivated`. For more information, see [`POST /payment-instruments/{id}/deactivation`](https://www.rebilly.com/catalog/all/payment-instruments/postpaymentinstrumentdeactivation).
  Enum: "active", "inactive", "expired", "deactivated", "verification-needed"
- `fingerprint` (string)
  Unique value that is used to identify the payment instrument. This value is generated from the `bin` and the `last4` values. This value contains alphanumeric characters.
- `bin` (string)
  Bank Identification Number (BIN) of the payment card. This value is the same as the first 6 digits of the associated Primary Account Number (PAN).
- `last4` (string)
  Last 4 digits of the associated Primary Account Number (PAN).
- `fpanLast4` (string | null)
  Last 4 digits of the Funding Primary Account Number (FPAN) of the payment card. This value is only present for payment cards created from digital wallet tokens, where the FPAN is the physical card number visible to the cardholder, as opposed to the Device Primary Account Number (DPAN) used in the digital wallet transaction.
- `expYear` (integer)
  Expiration year of the payment card.
- `expMonth` (integer)
  Expiration month of the payment card.
- `brand` (string)
  Brand of payment card.
  Enum: "Visa", "MasterCard", "American Express", "Discover", "Maestro", "Solo", "Electron", "JCB", "Voyager", "Diners Club", "Switch", "Laser", "China UnionPay", "AstroPay Card"
- `bankCountry` (string | null)
  Bank country of the payment instrument.
- `bankName` (string)
  Bank name of the payment instrument.
- `isPayoutable` (boolean)
  Specifies if payouts are supported for cards with this BIN. Defaults to `true`. This value is `false` if the BIN does not support payouts.
- `billingAddress` (object)
  Contact's information.
- `billingAddress.firstName` (string | null)
  Contact's first name.
  Example: Benjamin
- `billingAddress.lastName` (string | null)
  Contact's last name.
  Example: Franklin
- `billingAddress.organization` (string | null)
  Contact's organization.
  Example: Rebilly
- `billingAddress.address` (string | null)
  First line of the contact's street address.
  Example: 36 Craven St
- `billingAddress.address2` (string | null)
  Second line of the contact's street address.
- `billingAddress.city` (string | null)
  Contact's city of residence.
  Example: Austin
- `billingAddress.region` (string | null)
  Contact's region of residence.
  Example: Texas
- `billingAddress.country` (string | null)
  Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see [ISO.org](https://www.iso.org/obp/ui/#search/code/).
  Example: GB
- `billingAddress.postalCode` (string | null)
  Contact's postal code.
  Example: WC2N 5NF
- `billingAddress.phoneNumbers` (array)
  List of phone numbers associated with the contact.
- `billingAddress.phoneNumbers.label` (string, required)
  Phone number label or name.
  Example: main
- `billingAddress.phoneNumbers.value` (string, required)
  Phone number value.
  Example: 1-512-777-0269
- `billingAddress.phoneNumbers.primary` (boolean)
  Specifies if the phone number is the contact's primary phone number.
  Example: true
- `billingAddress.emails` (array)
  List of email addresses associated with the contact.
- `billingAddress.emails.label` (string, required)
  Email label or name.
  Example: main
- `billingAddress.emails.value` (string, required)
  Email address value.
  Example: rebilly@example.com
- `billingAddress.emails.primary` (boolean)
  Specifies if the email address is the contact's primary email address.
  Example: true
- `billingAddress.dob` (string | null)
  Contact's date of birth in ISO-8601 `YYYY-MM-DD` format.
  Example: 1980-04-01
- `billingAddress.jobTitle` (string | null)
  Contact's job title.
  Example: CEO
- `billingAddress.hash` (string)
  Hash value for the contact. Use this value to compare contacts for identical attribute values.
  Example: 056ae6d97c788b9e98b049ebafd7b229bf852221
- `useAsBackup` (boolean)
  Specifies if this payment instrument can be used as a backup for invoice payment retries.
- `billingPortalUrl` (string)
  URL of the billing portal where the card can be updated.
- `createdTime` (string)
  Date and time when the resource is created. This value is set automatically when the resource is created.
- `updatedTime` (string)
  Date and time when the resource is updated. This value is set automatically when the resource is updated.
- `lastPaymentTime` (string | null)
  Date and time of the last approved payment. Payments are the result of `sale` or `capture` transactions.
- `customFields` (object)
  Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see [Custom fields](https://www.rebilly.com/catalog/all/custom-fields).
  Example: {"foo":"bar"}
- `stickyGatewayAccountId` (string | null)
  ID of the sticky gateway account. All future payments are processed by this gateway account. For more information, see [Gateway routing](https://www.rebilly.com/docs/settings/intelligent-payment-routing/#sticky-gateway-accounts).
- `expirationReminderTime` (string | null)
  Date and time when an expiration reminder event is triggered.
- `expirationReminderNumber` (integer | null)
  Number of expiration reminder events that have triggered.
- `digitalWallet` (string | null)
  Digital wallet type.
  Enum: "Apple Pay", "Google Pay", "Samsung Pay", null
- `riskMetadata` (any)
- `revision` (integer)
  Number of times the payment instrument data has been modified. Use this value when analyzing webhook data to determine if a change must take precedence over the current representation.
- `_links` (array)
  Related links.
- `_links.href` (string)
  Link URL.
- `_links.rel` (string)
  Type of link.
  Enum: "self", "customer"
- `_embedded` (object)
  Embedded objects that are requested by the `expand` query parameter.
- `_embedded.customer` (object)
- `bankName` (string)
  Name of the bank.
- `routingNumber` (string)
  Bank routing number.
- `accountNumberType` (string)
  Type of bank account number. A valid value is a Basic Bank Account Number (BBAN) or an International Bank Account Number (IBAN).
  Enum: "BBAN", "IBAN"
- `accountType` (string)
  Type of bank account.
  Enum: "checking", "savings", "other"
- `bic` (string | null)
  Bank Identifier Code (BIC).
- `fingerprint` (string)
  Unique value which identifies the bank account. This value contains alphanumeric characters. Depending on the type of bank account number, a bank account fingerprint is generated using one of the following: - BBAN: `last4` and `routingNumber` values. - IBAN: First 8 characters of the IBAN and the `last4` value.
- `last4` (string)
  Last 4 digits of the bank account number.
- `status` (string)
  Status of the bank account.
  Enum: "active", "deactivated"
- `stickyGatewayAccountId` (string | null)
  ID of the sticky gateway account. All future payments are processed by this gateway account. For more information, see [Gateway routing](https://www.rebilly.com/docs/settings/intelligent-payment-routing/#sticky-gateway-accounts).
- `username` (string)
  PayPal username.
- `status` (string)
  PayPal account status.
  Enum: "inactive", "active", "deactivated"
- `method` (string, required)
  Payment method of the payment instrument.
  Enum: "cash", "check", "paypal", "AdvCash", "Aera", "Affirm", "Afterpay", "Aircash", "Alfa-click", "Alipay", "AstroPay Card", "AstroPay-GO", "BankReferenced", "bank-transfer", "bank-transfer-2", "bank-transfer-3", "bank-transfer-4", "bank-transfer-5", "bank-transfer-6", "bank-transfer-7", "bank-transfer-8", "bank-transfer-9", "Baloto", "Beeline", "Belfius-direct-net", "bitcoin", "Bizum", "Boleto", "cash-deposit", "CASHlib", "CashToCode", "China UnionPay", "Clearpay", "Cleo", "CODVoucher", "Conekta-oxxo", "Cupon-de-pagos", "cryptocurrency", "domestic-cards", "Directa24Card", "echeck", "ecoPayz", "ecoPayzTurkey", "ecoVoucher", "Efecty", "EPS", "ePay.bg", "eZeeWallet", "FasterPay", "Flexepin", "Giropay", "Gpaysafe", "Google Pay", "iDebit", "iDEAL", "ING-homepay", "INOVAPAY-pin", "INOVAPAY-wallet", "InstaDebit", "instant-bank-transfer", "InstantPayments", "Interac", "Interac-online", "Interac-eTransfer", "invoice", "iWallet", "Jeton", "JetonCash", "jpay", "KakaoPay", "Khelocard", "Klarna", "KNOT", "loonie", "Matrix", "MaxiCash", "Megafon", "MercadoPago", "MiFinity-eWallet", "miscellaneous", "MobilePay", "Bancontact", "Bancontact-mobile", "MTS", "Mollie", "MuchBetter", "MuchBetterVoucher", "Multibanco", "Neosurf", "Netbanking", "Neteller", "Nordea-Solo", "OchaPay", "online-bank-transfer", "Onlineueberweisen", "oriental-wallet", "OXXO", "P24", "Pagadito", "PagoEffectivo", "Pagsmile-deposit-express", "Pagsmile-lottery", "PayCash", "Payco", "Payeer", "PaymentAsia-crypto", "Paymero", "Perfect-money", "Piastrix", "PIX", "PIX-Automatico", "plaid-account", "PayTabs", "Paysafecard", "Paysafecash", "Pay4Fun", "Paynote", "PinPay", "phone", "PhonePe", "POLi", "PostFinance-card", "PostFinance-e-finance", "QIWI", "QPay", "QQPay", "Quickpay", "rapyd-checkout", "Resurs", "SafetyPay", "Samsung Pay", "SEPA", "Skrill", "Skrill Rapid Transfer", "SMSVoucher", "Sofort", "SparkPay", "swift-dbt", "Tele2", "Terminaly-RF", "Thunes-Checkout", "ToditoCash-card", "Trustly", "Tupay", "UPayCard", "UPI", "USD-coin", "VCreditos", "VegaWallet", "VenusPoint", "Viva", "voucher", "voucher-2", "voucher-3", "voucher-4", "Wallet88", "Webmoney", "Webpay", "Webpay-2", "Webpay Card", "WeChat Pay", "wire", "XPay-P2P", "XPay-QR", "Yandex-money", "Zotapay", "Zimpler", "Zip"
- `status` (string)
  Payment instrument status.
  Enum: "active", "deactivated"

## Response 401 fields

- `status` (integer)
  HTTP status code.
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

## Response 403 fields

- `status` (integer)
  HTTP status code.
- `error` (string)
  Message that describes why the request is forbidden. Most responses use a descriptive message, such as `Not allowed to change security settings`. If the organization requires multi-factor authentication (MFA) and MFA verification has not been completed for the session, this value is `mfa_required`. If the request sets `requireMfa` to `true` and MFA verification has not been completed for the session, this value is `mfa_required_for_caller`. If the organization restricts access to a list of IP addresses and the request comes from an IP address that is not in the list, this value is `ip_not_allowed`.
- `organizationId` (string)
  Unique organization identifier. An organization is an entity that represents a company. For more information, see [Obtain an organization ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
  Example: org_0YVDM8RC7GDADADSBSMW124JA8
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.