POST
/
payment-methods
curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/payment-methods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "method": "card",
  "number": "4111111111111111",
  "expiration_date": "11/25",
  "security_code": "123",
  "external_identifier": "card-323444",
  "buyer_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "buyer_external_identifier": "user-789123",
  "redirect_url": "https://example.com/callback"
}'
{
  "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": "USD",
  "details": {
    "card_type": "credit",
    "bin": "412345"
  },
  "expiration_date": "07/24",
  "external_identifier": "user-789123",
  "has_replacement": true,
  "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"
}

This endpoint requires the payment-methods.write scope.

Authorizations

Authorization
string
headerrequired

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

Body

application/json
method
enum<string>
required

card.

Available options:
card
number
string
required

The 13-19 digit number for this card as it can be found on the front of the card.

expiration_date
string
required

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

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.

The security code can only be set if the stored payment method represents a card.

external_identifier
string | null

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

buyer_id
string

The ID of the buyer to associate this payment method to. If this field is provided then the buyer_external_identifier field needs to be unset.

buyer_external_identifier
string

The external_identifier of the buyer to associate this payment method to. If this field is provided then the buyer_id field needs to be unset.

redirect_url
string | null

The redirect URL to redirect a buyer to after they have authorized their transaction or payment method. This only applies to payment methods that require buyer approval.

Response

201 - application/json
type
enum<string>

payment-method.

Available options:
payment-method
id
string

The unique ID of the payment method.

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,
mir,
nyce,
other,
pulse,
rupay,
star,
uatp,
unionpay,
visa
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
approval_url
string | null

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

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.

created_at
string

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

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.

details
object

A credit or debit card payment method.

expiration_date
string | null

The expiration date for the payment method.

external_identifier
string | null

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

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.

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.

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.

merchant_account_id
string

The unique ID for a merchant account.

method
enum<string>

The type of this payment method.

Available options:
afterpay,
alipay,
alipayhk,
applepay,
bacs,
bancontact,
banked,
becs,
bitpay,
boleto,
boost,
card,
cashapp,
chaseorbital,
checkout-session,
clearpay,
click-to-pay,
dana,
dcb,
dlocal,
ebanx,
eps,
everydaypay,
gcash,
giropay,
givingblock,
gocardless,
googlepay,
gopay,
grabpay,
ideal,
kakaopay,
klarna,
laybuy,
linepay,
linkaja,
maybankqrpay,
multibanco,
multipago,
network-token,
oney_3x,
oney_4x,
oney_6x,
oney_10x,
oney_12x,
ovo,
oxxo,
payid,
paymaya,
paypal,
paypalpaylater,
payto,
venmo,
pix,
rabbitlinepay,
razorpay,
scalapay,
sepa,
shopeepay,
singteldash,
smartpay,
sofort,
stripedd,
thaiqr,
touchngo,
truemoney,
trustly,
trustlyeurope,
vipps,
waave,
wechat,
zippay
mode
enum<string>

The mode to use with this payment method.

Available options:
card,
redirect,
applepay,
googlepay
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
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
updated_at
string

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

fingerprint
string | null

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

Was this page helpful?

List payment methodsGet payment method