List payment methods

GET

payment-methods

curl --request GET \
  --url https://api.mattildapayments.com/payment-methods \
  --header 'Authorization: Bearer <token>'

{
  "items": [
    {
      "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"
      },
      "country": "US",
      "created_at": "2013-07-16T19:23:00.000+00:00",
      "currency": "MXN",
      "details": {
        "card_type": "credit",
        "bin": "412345"
      },
      "expiration_date": "07/24",
      "external_identifier": "user-789123",
      "has_replacement": false,
      "label": "4242",
      "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"
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}

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.

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"

status

enum<string>[]

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

Example:

["succeeded", "processing"]

limit

integer

default:20

Defines the maximum number of items to return for this request.

Required range: 1 <= x <= 100

Example:

1

cursor

string

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.

Example:

"ZXhhbXBsZTE"

Response

200

application/json

Returns a list of payment methods.

A list of stored payment methods.

items

object[]

A list of stored payment methods.

A generic 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.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.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.buyer

object

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

items.buyer.type

enum<string>

The type of this resource. Is always buyer.

Available options:

buyer

Example:

"buyer"

items.buyer.id

string

The unique Gr4vy ID for this buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

items.buyer.billing_details

object

The billing details associated with a buyer.

items.buyer.billing_details.type

enum<string>

The type of this resource. Is always billing-details.

Available options:

billing-details

Example:

"billing-details"

items.buyer.billing_details.first_name

string | null

The first name(s) or given name of the buyer.

Required string length: 1 - 255

Example:

"John"

items.buyer.billing_details.last_name

string | null

The last name, or family name, of the buyer.

Required string length: 1 - 255

Example:

"Lunn"

items.buyer.billing_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

items.buyer.billing_details.phone_number

string | null

The phone number of the buyer. This number is formatted according to the E164 number standard.

Required string length: 1 - 50

Example:

"+1234567890"

items.buyer.billing_details.address

object

The billing address of the buyer.

items.buyer.billing_details.tax_id

object

The tax information associated with the billing details.

items.buyer.created_at

string

The date and time when this buyer was created in our system.

Example:

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

items.buyer.display_name

string | null

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

Example:

"John L."

items.buyer.external_identifier

string | null

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

Required string length: 1 - 200

Example:

"user-789123"

items.buyer.merchant_account_id

string

The unique ID for a merchant account.

Example:

"default"

items.buyer.updated_at

string

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

Example:

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

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

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

object

A credit or debit card payment method.

items.expiration_date

string | null

The expiration date for the payment method.

Required string length: 5

Example:

"07/24"

items.external_identifier

string | null

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

Example:

"user-789123"

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

string | null

A label for the card or the account. For a card it is the last 4 digits of the card.

Example:

"4242"

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

enum<string>

The mode to use with this payment method.

Available options:

card,

redirect,

applepay,

googlepay

Example:

"card"

items.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,

nyce,

other,

pulse,

rupay,

star,

unionpay,

visa

Example:

"visa"

items.status

enum<string>

The state of the payment method.

processing - The payment method is stored but has not been used yet.
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 has been used.
failed - The payment method could not be stored, or failed first use.

Available options:

processing,

buyer_approval_required,

succeeded,

failed

Example:

"succeeded"

items.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"

limit

integer

default:20

The limit applied to request. This represents the number of items that are at maximum returned by this request.

Required range: 1 <= x <= 100

Example:

1

next_cursor

string | null

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

Example:

"ZXhhbXBsZTE"

previous_cursor

string | null

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

Example:

null

Was this page helpful?

Suggest edits

List payment methods for buyer New payment method

curl --request GET \
  --url https://api.mattildapayments.com/payment-methods \
  --header 'Authorization: Bearer <token>'

{
  "items": [
    {
      "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"
      },
      "country": "US",
      "created_at": "2013-07-16T19:23:00.000+00:00",
      "currency": "MXN",
      "details": {
        "card_type": "credit",
        "bin": "412345"
      },
      "expiration_date": "07/24",
      "external_identifier": "user-789123",
      "has_replacement": false,
      "label": "4242",
      "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"
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}

Payments

Instruments

Vault

Dashboard

Errors

Authorizations

Query Parameters

Response