List payment methods for buyer

Payments

Transactions
Buyers
Checkout Sessions
Payment links
Payment options
Payouts
Refunds
Sessions
Settlement records

Instruments

Card schemes
Card details
Digital wallets
Gift cards
Payment methods
Payment method definitions

Vault

Account updater
Network tokens
Payment service tokens
Vault Forward
Vault Forward endpoints
Vault Forward authentication

Connections

All services
Payment services
Digital wallets
Anti-fraud services
Gift-card services

Other

Flow
Merchant accounts
Reports
Report executions
Webhook subscriptions

Errors

GET

buyers

payment-methods

curl --request GET \
  --url https://api.{gr4vy_id}.gr4vy.app/buyers/payment-methods \
  --header 'Authorization: Bearer <token>'

{
  "items": [
    {
      "type": "payment-method",
      "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
      "merchant_account_id": "default",
      "method": "card",
      "label": "1111",
      "scheme": "visa",
      "additional_schemes": [
        "visa"
      ],
      "expiration_date": "11/25",
      "approval_target": "any",
      "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
      "currency": "USD",
      "country": "US",
      "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
      "has_replacement": false,
      "last_used_at": "2013-07-16T19:23:00.000+00:00",
      "usage_count": 5,
      "cit_last_used_at": "2013-07-16T19:23:00.000+00:00",
      "cit_usage_count": 2
    }
  ]
}

This endpoint requires the payment-methods.read or embed scope.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

buyer_id

string

Filters the results to only the items for which the buyer has an id that matches this value.

Example:

"8724fd24-5489-4a5d-90fd-0604df7d3b83"

buyer_external_identifier

string

Filters the results to only the items for which the buyer has an external_identifier that matches this value.

Example:

"user-12345"

country

string

Filters the results to only the items which support this country code. A country is formatted as 2-letter ISO country code.

Example:

"US"

currency

string

Filters the results to only the items which support this currency code. A currency is formatted as 3-letter ISO currency code.

Example:

"USD"

sort_by

enum<string>

Used by the payment method filter to sort the results by an specific usage field.

Available options:

last_used_at,

usage_count,

cit_last_used_at,

cit_usage_count

Example:

"last_used_at"

order_by

enum<string>

default:desc

Used to show the results ascending or descending order.

Available options:

asc,

desc

Example:

"desc"

Response

200

application/json

Returns a list of available payment methods for a buyer, filtered by the given currency and country code.

A list of stored payment methods in summarized format.

items

object[]

A list of stored payment methods in summarized format.

A mini format version of a payment method.

items.type

enum<string>

payment-method.

Available options:

payment-method

Example:

"payment-method"

items.id

string

The unique ID of the payment method.

Example:

"77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5"

items.merchant_account_id

string

The unique ID for a merchant account.

Example:

"default"

items.method

enum<string>

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,

efecty,

eps,

everydaypay,

gcash,

gem,

gemds,

gift-card,

giropay,

givingblock,

gocardless,

googlepay,

googlepay_pan_only,

gopay,

grabpay,

id,

ideal,

kakaopay,

kcp,

klarna,

latitude,

latitudeds,

laybuy,

linepay,

linkaja,

maybankqrpay,

mercadopago,

multibanco,

multipago,

netbanking,

network-token,

oney_3x,

oney_4x,

oney_6x,

oney_10x,

oney_12x,

ovo,

oxxo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

venmo,

pix,

pse,

rabbitlinepay,

razorpay,

scalapay,

sepa,

shopeepay,

singteldash,

smartpay,

sofort,

spei,

stripedd,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

upi,

vipps,

waave,

webpay,

wechat,

zippay

Example:

"card"

items.label

string

A label for the payment method. For a card payment method this is the last 4 digits on the card. For others it would be the email address.

Example:

"1111"

items.scheme

enum<string> | null

The type of the card, if the payment method is a card.

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

Example:

"visa"

items.additional_schemes

enum<string>[] | null

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

items.expiration_date

string | null

The expiration date for the payment method.

Required string length: 5

Example:

"11/25"

items.approval_target

enum<string> | null

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

Example:

"any"

items.approval_url

string | null

The optional URL that the buyer needs to be redirected to to further authorize their payment.

Example:

"https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve"

items.currency

string | null

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.

Example:

"USD"

items.country

string | null

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.

Example:

"US"

items.last_replaced_at

string | null

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_method
- expired_payment_method
- unavailable_payment_method
- unknown_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.

Example:

"2023-07-26T19:23:00.000+00:00"

items.has_replacement

boolean

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_method
- expired_payment_method
- unavailable_payment_method
- unknown_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.

Example:

false

items.last_used_at

string | null

The timestamp when this payment method was last used in a transaction.

Example:

"2013-07-16T19:23:00.000+00:00"

items.usage_count

integer

The number of times this payment method has been used in transactions.

Example:

5

items.cit_last_used_at

string | null

The timestamp when this payment method was last used in a transaction for client initiated transactions.

Example:

"2013-07-16T19:23:00.000+00:00"

items.cit_usage_count

integer

The number of times this payment method has been used in transactions for client initiated transactions.

Example:

2

Was this page helpful?

Delete gift card List payment methods

curl --request GET \
  --url https://api.{gr4vy_id}.gr4vy.app/buyers/payment-methods \
  --header 'Authorization: Bearer <token>'

{
  "items": [
    {
      "type": "payment-method",
      "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
      "merchant_account_id": "default",
      "method": "card",
      "label": "1111",
      "scheme": "visa",
      "additional_schemes": [
        "visa"
      ],
      "expiration_date": "11/25",
      "approval_target": "any",
      "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
      "currency": "USD",
      "country": "US",
      "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
      "has_replacement": false,
      "last_used_at": "2013-07-16T19:23:00.000+00:00",
      "usage_count": 5,
      "cit_last_used_at": "2013-07-16T19:23:00.000+00:00",
      "cit_usage_count": 2
    }
  ]
}