Skip to main content
POST
C#
This endpoint requires the payment-methods.write scope.

Authorizations

Authorization
string
header
required

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

Headers

x-gr4vy-merchant-account-id
string

The ID of the merchant account to use for this request.

Example:

"default"

Body

application/json
expiration_date
string
required

The expiration date of the card, formatted MM/YY.

Required string length: 5
Pattern: ^\d{2}/\d{2}$
Example:

"12/30"

number
string
required

The 13-19 digit number for this card.

Required string length: 13 - 19
Pattern: ^\d+$
Example:

"4111111111111111"

buyer_external_identifier
string | null

The external identifier of the buyer to attach the method to.

Required string length: 1 - 200
Example:

"buyer-12345"

buyer_id
string<uuid> | null

The ID of the buyer to attach the method to.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

external_identifier
string | null

The merchant reference for this payment method.

Required string length: 1 - 200
Example:

"payment-method-12345"

card_type
string | null

The type of the card used

Example:

"credit"

method
string
default:card

Always card

Allowed value: "card"
Example:

"card"

security_code
string | null

The 3 or 4 digit security code often found on the card. This often referred to as the CVV or CVD.

Required string length: 3 - 4
Pattern: ^\d+$
Example:

"123"

Response

Successful Response

Payment Method

A stored payment method.

method
string
required

The type of this payment method.

Example:

"card"

id
string<uuid>
required

The ID for the payment method.

Example:

"ef9496d8-53a5-4aad-8ca2-00eb68334389"

merchant_account_id
string
required

The ID of the merchant account this buyer belongs to.

Example:

"default"

cit_usage_count
integer
required

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

Example:

50

has_replacement
boolean
required

Whether this card has a pending replacement that hasn't been applied yet.

Example:

false

usage_count
integer
required

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

Example:

100

scheme_transaction_id
string | null
required

The scheme transaction identifier stored against this payment method.

Example:

"123456789012345"

scheme_transaction_id_scheme
string | null
required

The scheme associated with scheme_transaction_id. Only applies to card payments.

Example:

"visa"

status
string
required

The state of the payment method.

Example:

"succeeded"

created_at
string<date-time>
required

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

Example:

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

updated_at
string<date-time>
required

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

Example:

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

type
string
default:payment-method

Always payment-method.

Allowed value: "payment-method"
Example:

"payment-method"

approval_url
string | null

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

Example:

"https://gr4vy.app/redirect/12345"

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.

Pattern: ^[A-Z]{2}$
Example:

"US"

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.

Pattern: ^[A-Z]{3}$
Example:

"USD"

details
PaymentMethodDetailsCard · object | null

Details for credit or debit card payment method.

expiration_date
string | null

The expiration date for the payment method.

Required string length: 5
Pattern: ^\d{2}/\d{2}$
Example:

"12/30"

fingerprint
string | null

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

Example:

"a50b85c200ee0795d6fd33a5c66f37a4564f554355c5b46a756aac485dd168a4"

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.

Maximum string length: 320
Example:

"1234"

last_replaced_at
string<date-time> | null

The date and time when this card was last replaced by the account updater.

Example:

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

mode
string | null

The mode to use with this payment method.

Example:

"card"

scheme
string | null

The scheme of the card. Only applies to card payments.

Example:

"visa"

additional_schemes
string[] | null

Additional schemes of the card besides the primary scheme. Only applies to card payment methods.

Example:
cit_last_used_at
string<date-time> | 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"

last_used_at
string<date-time> | null

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

Example:

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

The transaction link identifier stored against this payment method.

Example:

"123456789012345"

buyer
Buyer · object | null

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

external_identifier
string | null

The merchant reference that can be used to match the payment method against your own records.

Required string length: 1 - 200
Example:

"card-12345"