# 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)
    Limits the number of collection items to be returned.

  - `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 (application/json):

  - `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: "payment-card"

  - `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 [Deactivate a payment instrument](./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)

  - `riskMetadata.ipAddress` (string | null)
    Customer's IP address.
    Example: 93.92.91.90

  - `riskMetadata.fingerprint` (string | null)
    Customer's device fingerprint.
A device fingerprint is a unique token that is used to identify the customer.
The device fingerprint is generated based on device attributes, such as: hardware,
software, IP address, language, browser, and more.
    Example: pIUt3xbgX3l9g3YDiLbx

  - `riskMetadata.httpHeaders` (any)

  - `riskMetadata.browserData` (object | null)
    Browser data used for 3D Secure and risk scoring.

  - `riskMetadata.browserData.colorDepth` (integer, required)
    Browser color depth in bits per pixel.
This value is obtained using the `screen.colorDepth` property.
    Example: 24

  - `riskMetadata.browserData.isJavaEnabled` (boolean, required)
    Specifies if Java is enabled in a browser.
This value is obtained from the `navigator.javaEnabled` property.

  - `riskMetadata.browserData.language` (string, required)
    Browser language settings.
This value is obtained from the `navigator.language` property.
    Example: en-US

  - `riskMetadata.browserData.screenWidth` (integer, required)
    Width of the browser screen.
This value is obtained from the `screen.width` property.
    Example: 1920

  - `riskMetadata.browserData.screenHeight` (integer, required)
    Height of the browser screen.
This value is obtained from the `screen.height` property.
    Example: 1080

  - `riskMetadata.browserData.timeZoneOffset` (integer, required)
    Browser time zone offset in minutes from UTC.
A positive offset indicates that the local time is behind UTC.
A negative offset indicates that the local time is ahead of UTC.
You can find this value using the `(new Date()).getTimezoneOffset()` property.
    Example: 300

  - `riskMetadata.browserData.isAdBlockEnabled` (boolean)
    Specifies if the usage of ad block has been detected in the browser.

  - `riskMetadata.extraData` (object | null)
    Third-party data used for risk scoring.

  - `riskMetadata.extraData.kountFraudSessionId` (string)
    Alpha-numeric `fraudSessionId` as provided by the Kount SDK.
    Example: abcdefg12345abababab123456789012

  - `riskMetadata.extraData.payPalMerchantSessionId` (string)
    PayPal `MerchantSessionID` as generated by the PayPal Fraudnet SDK.
    Example: dd65ratxc5qv15iph3vyoq7l6davuowa

  - `riskMetadata.extraData.threatMetrixSessionId` (string)
    Temporary identifier that is unique to the visitor session and passed to ThreatMetrix.
    Example: dd65ratxc5qv15iph3vyoq7l6davuowadd65ratxc5qv15iph3vyoq7l6davuowa

  - `riskMetadata.isProxy` (boolean)
    Specifies if the customer's IP address is related to a proxy.

  - `riskMetadata.isVpn` (boolean)
    Specifies if the customer's IP address is related to a VPN.

  - `riskMetadata.isTor` (boolean)
    Specifies if the customer's IP address is related to TOR.

  - `riskMetadata.isHosting` (boolean)
    Specifies if the customer's IP address is related to hosting.

  - `riskMetadata.hostingName` (string | null)
    Name of the data center or hosting provider, if available.

  - `riskMetadata.isp` (string | null)
    Internet Service Provider (ISP) name, if available.

  - `riskMetadata.country` (string | null)
    Country ISO Alpha-2 code of the specified IP address.
    Example: US

  - `riskMetadata.region` (string | null)
    Region of the specified IP address.
    Example: NY

  - `riskMetadata.city` (string | null)
    City of the specified IP address.
    Example: New York

  - `riskMetadata.latitude` (number)
    Latitude of the specified IP address.

  - `riskMetadata.longitude` (number | null)
    Longitude of the specified IP address.

  - `riskMetadata.postalCode` (string | null)
    Postal code of the specified IP address.

  - `riskMetadata.timeZone` (string | null)
    Time zone of the specified IP address.
    Example: America/New_York

  - `riskMetadata.accuracyRadius` (integer | null)
    Accuracy radius of the specified IP address, in kilometers.

  - `riskMetadata.distance` (integer | null)
    Distance between the customer's IP address and the billing address geolocation, in kilometers.

  - `riskMetadata.hasMismatchedBillingAddressCountry` (boolean)
    Specifies if the customer's billing address country and geo-IP address are not the same.

  - `riskMetadata.hasMismatchedBankCountry` (boolean)
    Specifies if the customer's bank country and geo-IP address are not the same.

  - `riskMetadata.hasMismatchedTimeZone` (boolean)
    Specifies if the customer's browser time zone and the IP address associated time zone are not the same.

  - `riskMetadata.hasMismatchedHolderName` (boolean)
    Specifies if the customer's billing address name and primary address name are not the same.

  - `riskMetadata.hasFakeName` (boolean)
    Specifies if the holder name seems fake.

  - `riskMetadata.isHighRiskCountry` (boolean)
    Specifies if the geo-IP country, or the customer's billing country, is considered a high risk country.

  - `riskMetadata.paymentInstrumentVelocity` (integer)
    Number of transactions for this payment instrument, based on fingerprint, in the last 24 hours.

  - `riskMetadata.declinedPaymentInstrumentVelocity` (integer)
    Number of declined transactions for this payment instrument fingerprint in the last 24 hours.

  - `riskMetadata.deviceVelocity` (integer)
    Number of transactions for this device, based on fingerprint, in the last 24 hours.

  - `riskMetadata.ipVelocity` (integer)
    Number of transactions for this IP address in the last 24 hours.

  - `riskMetadata.emailVelocity` (integer)
    Number of transactions for this email address in the last 24 hours.

  - `riskMetadata.billingAddressVelocity` (integer)
    Number of transactions for this billing address in the last 24 hours.

  - `riskMetadata.paymentInstrumentApprovedTransactionCount` (integer)
    Number of approved transactions for this payment instrument.

  - `riskMetadata.score` (integer)
    Computed risk score based on IP risk data,
such as: `isVpn`, `isTor`, and `isProxy`.

  - `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"

  - `fingerprint` (string)
    Unique value which identifies the payment instrument.
This value contains alphanumeric characters.
This value is generated from the card number, CVV, and expiration date.

  - `number` (string)
    Khelocard card masked number.

  - `last4` (string)
    Last 4 digits of the number.

  - `expYear` (integer)
    Khelocard card expiration year.

  - `expMonth` (integer)
    Khelocard card expiration month.

  - `status` (string)
    Payment instrument status.
    Enum: "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", "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", "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"

## Response 401 fields (application/json):

  - `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 (application/json):

  - `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.