Saved Cards

Reference pages: Save a card and charge it later, Capture Buyer Token, Generate Sale with Token, Get Buyer Key, Create Marketplace Token.

A token stands in for a card (TOK-01). Before you save one, you need a first Checkout to capture the card.

Getting one

Way	Who	You get	Notes
`capture_buyer: "1"` on `generate-sale`	Both	`buyer_key`	Captured as part of the payment. Can't be combined with `buyer_key` on one request. A direct seller also sends `buyer_is_private: true`: see below
Hosted Fields `tokenize()`	Both	`token`, used as `buyer_key`	`tokenIsPermanent: false` makes it single-use
`sale_type: "token"` on `generate-sale`	Both	`buyer_key`	The buyer enters a card and nothing is charged
`capture-buyer-token`	PCI DSS certified only	`buyer_key`	Takes a raw card (TOK-03)
`sale_type: "seller-token"` on `generate-sale`	Partner	`uuid`	A hosted page that captures a marketplace token
`POST /sellers/{mpl}/tokens`	Partner, PCI DSS certified	`uuid`	Takes a raw card

Getting it safely after a sale

A direct seller can't verify a callback, so it never stores a token from one (TOK-02). Once the sale is confirmed, it calls get-buyer-key with its MPL.
A partner treats a callback's buyer_key as unconfirmed too, until the sale is confirmed.

Which credential get-buyer-key takes depends on how the token was captured:

Token	`get-buyer-key` with	Seen in the sandbox
Sale sent `buyer_is_private: true`	The seller's MPL	`status_code: 0`
Sale sent no `buyer_is_private`, or a marketplace token	`payme_client_key` and no `seller_payme_id`	`status_code: 0`. With the MPL, alone or with the partner key, it fails with error 603

So a direct seller, which has no partner key, must send buyer_is_private: true on generate-sale, or it can't read the token back.

Scope and lifetime

Reuse: without buyer_is_permanent: true, a capture-buyer-token token was charged once and the next charge failed with error 604 in the sandbox. With it, the same token paid repeatedly. Subscriptions need a permanent token too.
A capture_buyer token: in the sandbox one was charged three times and then started a subscription, with buyer_is_private: true on the sale. buyer_is_permanent isn't a generate-sale field, and PayMe publishes no lifetime for these tokens, so handle error 604 on any token anyway.
Seller or account level: buyer_is_private: true ties a token to one seller. Without it, the token is account-level, and a charge sending seller_payme_id can fail: see Errors.
Marketplace-wide: a token from POST /sellers/{mpl}/tokens was charged on another seller of the same partner in the sandbox. Against a seller of a different partner, it failed with error 605.

Charging one

You hold	Send on `generate-sale`
A `buyer_key`	`buyer_key`
A marketplace `uuid`	`token`. Sent as `buyer_key`, it failed with error `600` in the sandbox

A token charge returned the final sale_status in one call in the sandbox, with no sale_url. Confirm it as usual before fulfilling.
pay-sale with buyer_key is the other route. It is how a Hosted Fields sale finishes.
Charge only for the buyer the card belongs to: tie every saved token to your own buyer record and check it.

Removing one

These docs list no call to revoke a token. Delete it from your store, and that is what "remove this card" means. Let the buyer see the saved card (buyer_card_mask) and delete it.

Test the failure

To test "the saved card stopped working", use 4000000000000036 (Test Cards and Payment Methods). It only reaches the charge if the token comes from Hosted Fields:

Way in	What happened in the sandbox
Hosted Fields `tokenize()`, then `pay-sale` with the token	Token created, then the charge failed with `20004` and the sale became `failed`. Use this one
Hosted page, with `capture_buyer` or `sale_type: "token"`	Declined at once with `20004`, and no token exists

If you didn't build Hosted Fields, there's no way to run this without raw card data (TOK-03). Test your handling of a refused charge with a fake PayMe, and report the real decline as not proven.