POST

/payment-methods

curl --request POST \
  --url https://api.sandbox.{gr4vy_id}.gr4vy.app/payment-methods \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json'
{
  "approval_target": "any",
  "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
  "buyer": {
    "billing_details": {
      "address": {
        "city": "London",
        "country": "GB",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND"
      },
      "email_address": "john@example.com",
      "first_name": "John",
      "last_name": "Lunn",
      "phone_number": "+1234567890",
      "tax_id": {
        "kind": "gb.vat",
        "value": "12345678931"
      },
      "type": "billing-details"
    },
    "created_at": "2013-07-16T19:23:00.000+00:00",
    "display_name": "John L.",
    "external_identifier": "user-789123",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "merchant_account_id": "default",
    "type": "buyer",
    "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": {
    "bin": "412345",
    "card_type": "credit"
  },
  "expiration_date": "07/24",
  "external_identifier": "user-789123",
  "has_replacement": "boolean",
  "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
  "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",
  "type": "payment-method",
  "updated_at": "2013-07-16T19:23:00.000+00:00"
}

This endpoint requires the payment-methods.write scope.

Authorizations

Authorizationheaderrequired
string

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

Body

application/json

  • Card

  • Redirect

  • Checkout Session

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.

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.

expiration_daterequired
string

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

external_identifier
string | null

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

methodrequired
enum<string>

card.

Available options:
card
numberrequired
string

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

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
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 (e.g. when it's about to expire), existing details are not changed immediately, but this field is set to true. The actual replacement occurs when a transaction using this payment method 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.

id
string

The unique ID of the payment method.

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 (e.g. when it's about to expire), existing details are not changed immediately. The actual replacement occurs when a transaction using this payment method 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,
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
mode
enum<string>

The mode to use with this payment method.

Available options:
card,
redirect,
applepay,
googlepay
scheme
string | null

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

status
enum<string>

The state of the payment method.

  • processing - The payment method is still being stored.
  • 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 approved and stored with all relevant payment services.
  • failed - Storing the payment method did not succeed.
Available options:
processing,
buyer_approval_required,
succeeded,
failed
type
enum<string>

payment-method.

Available options:
payment-method
updated_at
string

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