This endpoint requires the payment-methods.read scope.
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Filters the results to only the items for which the buyer has an
id that matches this value.
Filters the results to only the items for which the buyer has an
external_identifier that matches this value.
Filters the results to only the payment methods for which the status
matches with any of the provided status values.
Available options:
processing,
buyer_approval_required,
succeeded,
failed
Filters the results to only the items for which the resource has an
external_identifier that matches this value.
Defines the maximum number of items to return for this request.
Required range: 1 < x < 100
A cursor that identifies the page of results to return. This is used to
paginate the results of this API.
For the first page of results, this parameter can be left out.
For additional pages, use the value returned by the API in
the next_cursor field. Similarly the previous_cursor can be used to
reverse backwards in the list.
A list of stored payment methods.
A list of stored payment methods.
Available options:
payment-method
The unique ID of the payment method.
Additional schemes of the card. Only applies to card payment methods.
Available options:
accel,
amex,
bancontact,
carte-bancaire,
cirrus,
culiance,
dankort,
diners-club,
discover,
eftpos-australia,
elo,
hipercard,
jcb,
maestro,
mastercard,
mir,
nyce,
other,
pulse,
rupay,
star,
uatp,
unionpay,
visa
The browser target that an approval URL must be opened in. If any or null, then there is no specific requirement.
Available options:
any,
new_window
The optional URL that the buyer needs to be redirected to to further authorize their payment.
The optional buyer for which this payment method has been stored.
The type of this resource. Is always buyer.
The unique Gr4vy ID for this buyer.
items.buyer. billing_details
The billing details associated with a buyer.
items.buyer.billing_details. type
The type of this resource. Is always billing-details.
Available options:
billing-details
items.buyer.billing_details. first_name
The first name(s) or given name of the buyer.
Required string length: 1 - 255
items.buyer.billing_details. last_name
The last name, or family name, of the buyer.
Required string length: 1 - 255
items.buyer.billing_details. email_address
The email address of the buyer.
Required string length: 1 - 320
items.buyer.billing_details. phone_number
Required string length: 1 - 50
items.buyer.billing_details. address
The billing address of the buyer.
items.buyer.billing_details.address. city
The city for the address.
Required string length: 1 - 100
items.buyer.billing_details.address. country
The country for the address in ISO 3166 format.
Required string length: 2
items.buyer.billing_details.address. postal_code
The postal code or zip code for the address.
Required string length: 1 - 50
items.buyer.billing_details.address. state
The state, county, or province for the address.
Required string length: 1 - 255
items.buyer.billing_details.address. state_code
The code of state, county, or province for the address in
ISO 3166-2 format.
Required string length: 4 - 6
items.buyer.billing_details.address. house_number_or_name
The house number or name for the address. Not all payment
services use this field but some do.
Required string length: 1 - 255
items.buyer.billing_details.address. line1
The first line of the address.
Required string length: 1 - 255
items.buyer.billing_details.address. line2
The second line of the address.
Required string length: 1 - 255
items.buyer.billing_details.address. organization
The optional name of the company or organisation to add
to the address.
Required string length: 1 - 255
items.buyer.billing_details. tax_id
The tax information associated with the billing details.
items.buyer.billing_details.tax_id. value
The tax ID for the buyer.
Required string length: 1 - 50
items.buyer.billing_details.tax_id. kind
Available options:
ae.trn,
au.abn,
ar.dni,
ar.cuil,
ar.cuit,
br.cnpj,
br.cpf,
ca.bn,
ca.gst_hst,
ca.pst_bc,
ca.pst_mb,
ca.pst_sk,
ca.qst,
ch.vat,
cl.tin,
es.cif,
eu.vat,
gb.vat,
hk.br,
id.nik,
id.npwp,
in.gst,
jp.cn,
jp.rn,
kr.brn,
li.uid,
mx.curp,
my.frp,
my.itn,
my.nric,
my.sst,
no.vat,
nz.gst,
ph.tin,
ru.inn,
ru.kpp,
sa.vat,
sg.gst,
sg.uen,
th.id,
th.vat,
tw.vat,
us.ein,
za.vat
The date and time
when this buyer was created in our system.
A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
Required string length: 1 - 200
items.buyer. external_identifier
An external identifier that can be used to match the buyer against your own records.
Required string length: 1 - 200
items.buyer. merchant_account_id
The unique ID for a merchant account.
The date and time
when this buyer was last updated in our system.
The 2-letter ISO code of the country this payment method can
be used for. If this value is null the payment method may be
used in multiple countries.
The date and time when this payment method was first created in our
system.
The ISO-4217 currency code that this payment method can be
used for. If this value is null the payment method may be
used for multiple currencies.
A credit or debit card payment method.
The type of card, one of credit, debit or prepaid.
Available options:
credit,
debit,
prepaid
The first 6 digits of the full card number (the BIN).
The expiration date for the payment method.
Required string length: 5
items. external_identifier
An external identifier that can be used to match the payment method
against your own records.
Whether this card has a pending replacement that hasn't been applied yet.
When the Account Updater determines that new card details are available, existing details are not
changed immediately, but this field is set to true. There are three scenarios in which the actual
replacement occurs:
When this card has expired.
When only the expiration date changed.
When a transaction using this card is declined with any of the following codes:
canceled_payment_methodexpired_payment_methodunavailable_payment_methodunknown_payment_method
When the replacement is applied, this field is set to false.
For non-card payment methods, the value of this field is always set to false.
A label for the card or the account. For a paypal payment method this
is the user's email address. For a card it is the last 4 digits of the
card.
The date and time when this card was last replaced.
When the Account Updater determines that new card details are available, existing details are not
changed immediately. There are three scenarios in which the actual replacement occurs:
When this card has expired.
When only the expiration date changed.
When a transaction using this card is declined with any of the following codes:
canceled_payment_methodexpired_payment_methodunavailable_payment_methodunknown_payment_method
When the replacement is applied, this field is updated.
For non-card payment methods, the value of this field is always set to null.
items. merchant_account_id
The unique ID for a merchant account.
The type of this payment method.
Available options:
afterpay,
alipay,
alipayhk,
applepay,
bacs,
bancontact,
banked,
becs,
bitpay,
boleto,
boost,
card,
cashapp,
chaseorbital,
checkout-session,
clearpay,
click-to-pay,
dana,
dcb,
dlocal,
ebanx,
eps,
everydaypay,
gcash,
giropay,
givingblock,
gocardless,
googlepay,
googlepay_pan_only,
gopay,
grabpay,
id,
ideal,
kakaopay,
kcp,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
multipago,
network-token,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
payid,
paymaya,
paypal,
paypalpaylater,
payto,
venmo,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
smartpay,
sofort,
spei,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
trustlyeurope,
vipps,
waave,
wechat,
zippay
The mode to use with this payment method.
Available options:
card,
redirect,
applepay,
googlepay,
click-to-pay,
checkout-session
The scheme of the card. Only applies to card payments.
Available options:
accel,
amex,
bancontact,
carte-bancaire,
cirrus,
culiance,
dankort,
diners-club,
discover,
eftpos-australia,
elo,
hipercard,
jcb,
maestro,
mastercard,
mir,
nyce,
other,
pulse,
rupay,
star,
uatp,
unionpay,
visa
The state of the payment method.
processing - The payment method is stored but is not ready to be
used yet, as we may be waiting for a notification from a connector
to complete the setup.buyer_approval_required - Storing the payment method requires
the buyer to provide approval. Follow the approval_url for next steps.succeeded - The payment method is stored and can be used.failed - The payment method could not be stored, or failed verification. Available options:
processing,
buyer_approval_required,
succeeded,
failed
The date and time when this payment method was last updated in our system.
The unique hash derived from the payment method identifier (e.g. card number).
The timestamp when this payment method was last used in a transaction.
The number of times this payment method has been used in transactions.
The timestamp when this payment method was last used in a transaction
for client initiated transactions.
The number of times this payment method has been used in transactions
for client initiated transactions.
The limit applied to request. This represents the number of items that are at
maximum returned by this request.
Required range: 1 < x < 100
The cursor that represents the next page of results. Use the cursor query
parameter to fetch this page of items.
Required string length: 1 - 1000
The cursor that represents the next page of results. Use the cursor query
parameter to fetch this page of items.
Required string length: 1 - 1000
