Payment instruments

Use these operations to manage payment instruments. Payment instrument is a term which describes any means of making a digital payment, such as: credit cards, debit cards, direct debits, payment service providers, and digital wallets.

For more information on payment instruments, see Payment instruments.

Operations
Webhooks

Retrieve payment instruments

Request

Retrieves a list of payment instruments.
Security
SecretApiKey or JWT
Query
filterstring

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.

sortArray of strings

Sorts and orders the collection of items. To sort in descending order, prefix with -. Multiple fields can be sorted by separating each with ,.

limitinteger, [ 0 .. 1000 ]

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.

offsetinteger, [ 0 .. 1000 ]
Specifies the starting point within the collection of items to be returned.
qstring
Use this field to perform a partial search of text fields.
expandstring

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.

curl -i -X GET \
  'https://www.rebilly.com/_mock/catalog/all/payment-instruments?filter=string&sort=string&limit=0&offset=0&q=string&expand=string' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'

Responses

List of payment instruments retrieved.
Headers
Pagination-Totalinteger

Total number of items that match the request. The value is independent of limit, including when limit is 0.

Example:332
Pagination-Limitinteger
Maximum number of items per page.
Example:100
Pagination-Offsetinteger

Specifies the starting point within the collection of resource results. For example, a request with limit=20 retrieves and displays the first 20 results on a page. A following request with limit=20 and offset=20, retrieves the next page of 20 results.

Example:2
Bodyapplication/json
Array [
idstring, <= 50 charactersread-only
ID of the payment instrument.
Example:"inst_0YVB8KPKNXCBR9EDX7JHSED75N"
customerIdstring, <= 50 characters(CustomerId)
ID of the customer resource.
Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
methodstringrequired
Method of payment instrument.
Value:"payment-card"
Discriminator
statusstring

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.

Enum:"active""inactive""expired""deactivated""verification-needed"
fingerprintstringread-only

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.

binstring, (bin)read-only

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

last4stringread-only

Last 4 digits of the associated Primary Account Number (PAN).

fpanLast4string or nullread-only

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.

expYearinteger
Expiration year of the payment card.
expMonthinteger
Expiration month of the payment card.
brandstring(PaymentCardBrand)read-only
Brand of payment card.
Enum:"Visa""MasterCard""American Express""Discover""Maestro""Solo""Electron""JCB""Voyager""Diners Club"
bankCountrystring or nullread-only
Bank country of the payment instrument.
bankNamestringread-only
Bank name of the payment instrument.
isPayoutablebooleanread-only

Specifies if payouts are supported for cards with this BIN. Defaults to true. This value is false if the BIN does not support payouts.

billingAddressobject(ContactObject)
Contact's billing address.
useAsBackupboolean(UseAsBackup)
Specifies if this payment instrument can be used as a backup for invoice payment retries.
Default:false
billingPortalUrlstringread-only
URL of the billing portal where the card can be updated.
createdTimestring, (date-time)(CreatedTime)read-only
Date and time when the resource is created. This value is set automatically when the resource is created.
updatedTimestring, (date-time)(UpdatedTime)read-only
Date and time when the resource is updated. This value is set automatically when the resource is updated.
lastPaymentTimestring or null, (date-time)(LastPaymentTime)read-only

Date and time of the last approved payment. Payments are the result of sale or capture transactions.

customFieldsobject(ResourceCustomFields)

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.

Default:{}
Example:
{
  "foo": "bar"
}
stickyGatewayAccountIdstring or nullread-only

ID of the sticky gateway account. All future payments are processed by this gateway account.

For more information, see Gateway routing.

expirationReminderTimestring or null, (date-time)read-only
Date and time when an expiration reminder event is triggered.
expirationReminderNumberinteger or nullread-only
Number of expiration reminder events that have triggered.
referenceDataobject
Payment instrument reference data.
Example:
{
  "gatewayTransactionId": "GAT123"
}
digitalWalletstring or nullread-only
Digital wallet type.
Enum:"Apple Pay""Google Pay""Samsung Pay"null
riskMetadataRisk metadata (object) or null
One of:
Risk metadata used for 3D Secure and risk scoring.
revisionintegerread-only
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.
_linksArray of objectsread-only
Related links.
_embeddedobjectread-only

Embedded objects that are requested by the expand query parameter.

]
Response
[
  {
    "id": "inst_0YVB8KPKNXCBR9EDX7JHSED75N",
    "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
    "method": "payment-card",
    "status": "active",
    "fingerprint": "string",
    "bin": "string",
    "last4": "string",
    "fpanLast4": "string",
    "expYear": 0,
    "expMonth": 0,
    "brand": "Visa",
    "bankCountry": "string",
    "bankName": "string",
    "isPayoutable": true,
    "billingAddress": { … },
    "useAsBackup": false,
    "billingPortalUrl": "string",
    "createdTime": "2019-08-24T14:15:22Z",
    "updatedTime": "2019-08-24T14:15:22Z",
    "lastPaymentTime": "2019-08-24T14:15:22Z",
    "customFields": { … },
    "stickyGatewayAccountId": "string",
    "expirationReminderTime": "2019-08-24T14:15:22Z",
    "expirationReminderNumber": 0,
    "referenceData": { … },
    "digitalWallet": "Apple Pay",
    "riskMetadata": { … },
    "revision": 0,
    "_links": [ … ],
    "_embedded": { … }
  }
]