GET
/
payment-methods
/
{payment_method_id}
curl --request GET \
  --url https://api.{gr4vy_id}.gr4vy.app/payment-methods/{payment_method_id} \
  --header 'Authorization: Bearer <token>'
{
  "type": "payment-method",
  "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
  "additional_schemes": [
    "visa"
  ],
  "approval_target": "any",
  "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
  "buyer": {
    "type": "buyer",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "billing_details": {
      "type": "billing-details",
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "12345678931",
        "kind": "gb.vat"
      }
    },
    "created_at": "2013-07-16T19:23:00.000+00:00",
    "display_name": "John L.",
    "external_identifier": "user-789123",
    "merchant_account_id": "default",
    "updated_at": "2013-07-16T19:23:00.000+00:00",
    "account_number": "1234567"
  },
  "country": "US",
  "created_at": "2013-07-16T19:23:00.000+00:00",
  "currency": "USD",
  "details": {
    "bin": "412345",
    "card_type": "credit",
    "card_issuer_name": "Bank"
  },
  "expiration_date": "07/24",
  "external_identifier": "user-789123",
  "has_replacement": false,
  "label": "john@example.com",
  "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
  "merchant_account_id": "default",
  "method": "card",
  "mode": "card",
  "scheme": "visa",
  "status": "succeeded",
  "updated_at": "2013-07-16T19:23:00.000+00:00",
  "fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17",
  "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 scope.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
payment_method_id
string
required

The ID of the payment method.

Example:

"46973e9d-88a7-44a6-abfe-be4ff0134ff4"

Response

200
application/json

Returns a payment method.

A generic payment method.

​
type
enum<string>

payment-method.

Available options:
payment-method
Example:

"payment-method"

​
id
string

The unique ID of the payment method.

Example:

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

​
additional_schemes
enum<string>[] | null

Additional schemes of the card. Only applies to card payment methods.

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

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

​
buyer
object

The optional buyer for which this payment method has been stored.

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

​
created_at
string

The date and time when this payment method was first created in our system.

Example:

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

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

​
details
object

A credit or debit card payment method.

​
expiration_date
string | null

The expiration date for the payment method.

Required string length: 5
Example:

"07/24"

​
external_identifier
string | null

An external identifier that can be used to match the payment method against your own records.

Example:

"user-789123"

​
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:

  1. When this card has expired.
  2. When only the expiration date changed.
  3. 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

​
label
string | null

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.

Example:

"john@example.com"

​
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:

  1. When this card has expired.
  2. When only the expiration date changed.
  3. 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"

​
merchant_account_id
string

The unique ID for a merchant account.

Example:

"default"

​
method
enum<string>

The type of this payment method.

Available options:
affirm,
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"

​
mode
enum<string>

The mode to use with this payment method.

Available options:
card,
redirect,
applepay,
googlepay,
click-to-pay,
checkout-session
Example:

"card"

​
scheme
enum<string> | null

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
Example:

"visa"

​
status
enum<string>

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
Example:

"succeeded"

​
updated_at
string

The date and time when this payment method was last updated in our system.

Example:

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

​
fingerprint
string | null

The unique hash derived from the payment method identifier (e.g. card number).

Example:

"20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"

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

​
usage_count
integer

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

Example:

5

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

​
cit_usage_count
integer

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

Example:

2