New payment method
Stores and vaults a new payment method.
Vaulting a card only stores its information but doesn’t validate it against any PSP, so ephemeral data like the security code, often referred to as the CVV or CVD, won’t be used. In order to validate the card data, a CIT (Customer Initiated Transaction) must be done, even if it’s a zero-value one.
This endpoint requires the payment-methods.write scope.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
card.
card The 13-19 digit number for this card as it can be found on the front of the card.
The expiration date of the card, formatted MM/YY.
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.
An external identifier that can be used to match the card against your own records.
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.
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.
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
payment-method.
payment-method The unique ID of the payment method.
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, mir, nyce, other, pulse, rupay, star, uatp, 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 The optional URL that the buyer needs to be redirected to to further authorize their payment.
The optional buyer for which this payment method has been stored.
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.
The date and time when this payment method was first created in our system.
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.
A credit or debit card payment method.
The expiration date for the payment method.
An external identifier that can be used to match the payment method against your own records.
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_methodexpired_payment_methodunavailable_payment_methodunknown_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.
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.
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_methodexpired_payment_methodunavailable_payment_methodunknown_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.
The unique ID for a merchant account.
The type of this payment method.
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 The mode to use with this payment method.
card, redirect, applepay, googlepay 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, mir, nyce, other, pulse, rupay, star, uatp, unionpay, 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_urlfor 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 The date and time when this payment method was last updated in our system.
The unique hash derived from the payment method identifier (e.g. card number).
Was this page helpful?