List payment methods for buyer

GET

buyers

payment-methods

curl --request GET \
  --url https://api.mattildapayments.com/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": "MXN",
      "country": "US",
      "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
      "has_replacement": false
    }
  ]
}

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:

"MXN"

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,

checkout-session,

click-to-pay,

clearpay,

dana,

dcb,

eps,

fortumo,

gcash,

giropay,

gocardless,

googlepay,

gopay,

grabpay,

ideal,

id,

kakaopay,

klarna,

laybuy,

linepay,

linkaja,

maybankqrpay,

multibanco,

oney_3x,

oney_4x,

oney_6x,

oney_10x,

oney_12x,

ovo,

oxxo,

paymaya,

paypal,

paypalpaylater,

pix,

rabbitlinepay,

razorpay,

scalapay,

sepa,

shopeepay,

singteldash,

sofort,

stripedd,

thaiqr,

touchngo,

truemoney,

trustly,

venmo,

waave,

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,

nyce,

other,

pulse,

rupay,

star,

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,

nyce,

other,

pulse,

rupay,

star,

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:

"MXN"

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

Was this page helpful?

Suggest edits

List card scheme definitions List payment methods

curl --request GET \
  --url https://api.mattildapayments.com/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": "MXN",
      "country": "US",
      "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
      "has_replacement": false
    }
  ]
}

Payments

Instruments

Vault

Dashboard

Errors

List payment methods for buyer

Authorizations

Query Parameters

Response