Payments
- Transactions
- Buyers
- Checkout Sessions
- Payment options
- Refunds
Instruments
- Card schemes
- Payment methods
- Payment method definitions
Vault
- Account updater
- Network tokens
- Payment service tokens
- Vault Forwarding
Dashboard
- Reports
- Report executions
List payment methods
Returns a list of stored 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
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
Query Parameters
Filters the results to only the items for which the buyer
has an
id
that matches this value.
"8724fd24-5489-4a5d-90fd-0604df7d3b83"
Filters the results to only the items for which the buyer
has an
external_identifier
that matches this value.
"user-12345"
Filters the results to only the payment methods for which the status
matches with any of the provided status values.
processing
, buyer_approval_required
, succeeded
, failed
["succeeded", "processing"]
Defines the maximum number of items to return for this request.
1 <= x <= 100
1
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.
"ZXhhbXBsZTE"
Response
A list of stored payment methods.
A list of stored payment methods.
A generic payment method.
payment-method
.
payment-method
"payment-method"
The unique ID of the payment method.
"77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5"
Additional schemes of the card. Only applies to card payment methods.
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
The browser target that an approval URL must be opened in. If any
or null
, then there is no specific requirement.
any
, new_window
"any"
The optional URL that the buyer needs to be redirected to to further authorize their payment.
"https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve"
The optional buyer for which this payment method has been stored.
The type of this resource. Is always buyer
.
buyer
"buyer"
The unique Gr4vy ID for this buyer.
"fe26475d-ec3e-4884-9553-f7356683f7f9"
The billing details associated with a buyer.
The type of this resource. Is always billing-details
.
billing-details
"billing-details"
The first name(s) or given name of the buyer.
1 - 255
"John"
The last name, or family name, of the buyer.
1 - 255
"Lunn"
The email address of the buyer.
1 - 320
"john@example.com"
The phone number of the buyer. This number is formatted according to the E164 number standard.
1 - 50
"+1234567890"
The billing address of the buyer.
The city for the address.
1 - 100
"London"
The country for the address in ISO 3166 format.
2
"GB"
The postal code or zip code for the address.
1 - 50
"789123"
The state, county, or province for the address.
1 - 255
"Greater London"
The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6
"GB-LND"
The house number or name for the address. Not all payment services use this field but some do.
1 - 255
"10"
The first line of the address.
1 - 255
"10 Oxford Street"
The second line of the address.
1 - 255
"New Oxford Court"
The optional name of the company or organisation to add to the address.
1 - 255
"Gr4vy"
The tax information associated with the billing details.
The tax ID for the buyer.
1 - 50
"12345678931"
The kind of tax ID.
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
"gb.vat"
The date and time when this buyer was created in our system.
"2013-07-16T19:23:00.000+00:00"
A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
1 - 200
"John L."
An external identifier that can be used to match the buyer against your own records.
1 - 200
"user-789123"
The unique ID for a merchant account.
"default"
The date and time when this buyer was last updated in our system.
"2013-07-16T19:23:00.000+00:00"
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.
"US"
The date and time when this payment method was first created in our system.
"2013-07-16T19:23:00.000+00:00"
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.
"MXN"
The expiration date for the payment method.
5
"07/24"
An external identifier that can be used to match the payment method against your own records.
"user-789123"
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
.
false
A label for the card or the account. For a card it is the last 4 digits of the card.
"4242"
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
.
"2023-07-26T19:23:00.000+00:00"
The unique ID for a merchant account.
"default"
The type of this payment method.
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
"card"
The mode to use with this payment method.
card
, redirect
, applepay
, googlepay
"card"
The scheme of the card. Only applies to card payments.
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
"visa"
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 theapproval_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.
processing
, buyer_approval_required
, succeeded
, failed
"succeeded"
The date and time when this payment method was last updated in our system.
"2013-07-16T19:23:00.000+00:00"
The limit applied to request. This represents the number of items that are at maximum returned by this request.
1 <= x <= 100
1
The cursor that represents the next page of results. Use the cursor
query
parameter to fetch this page of items.
1 - 1000
"ZXhhbXBsZTE"
The cursor that represents the next page of results. Use the cursor
query
parameter to fetch this page of items.
1 - 1000
null
Was this page helpful?
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
}