# Accepting Payments

> How-to guides for accepting payments with PayMe: checkout and in-person payments, Apple Pay, Google Pay, Israeli direct debit, capture, saved cards, 3D Secure and reporting.

## Machine-readable

- [Accepting Payments full text](https://docs.payme.io/accepting-payments/llms-full.txt): every Accepting Payments page in one file
- Markdown: append `.md` to any page URL for that page as Markdown, or request the page URL with `Accept: text/markdown`
- Source: append `.yaml` to an endpoint page URL (a line that reads `METHOD path — summary`) for its source YAML; guide pages have no YAML

## Checkout and In-Person

- [Hosted Payment Page options](https://docs.payme.io/accepting-payments/checkout-and-in-person/hosted-payment-page-options): Pre-fill PayMe's hosted payment page with the buyer's details, read the parameters of the success redirect to sale_return_url, and show sale_url in an iframe.
- [Hosted Fields JSAPI guide](https://docs.payme.io/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide): Add PayMe Hosted Fields to your own checkout: how the flow works, a complete minimal page, five working examples, charging the token from your server, and the full JavaScript API reference with every error shape.
- [Template sales (one link, many payments)](https://docs.payme.io/accepting-payments/checkout-and-in-person/multi-payment-page): A template sale is one payment link that many buyers can pay; each payment creates its own sale. Create it with generate-sale and sale_type template; close it with cancel-template or sale_expiry_seconds.
- [Take in-person payments with a POS device](https://docs.payme.io/accepting-payments/checkout-and-in-person/point-of-sale): For partners. Order POS devices with vas-enable (extend_items in vas_data adds devices). PayMe pairs new devices; to pair yourself call pos/pair (payme_client_key, seller_payme_id, pos_id, terminal_id, optional name), then pos/authenticate with the 6-digit verification_code. Callbacks: point-of-sale-action-pair-update, -authenticate-update. Pay: POST /sales with payment.method pos, pos_id, currency; a decline is HTTP 200 status_code 1; 26020 means still verifying, wait for the callback. Refund: PUT /sales/{id} with payment.action refund. pos/transmit returns acknowledge_number and report.
- [Let the buyer choose how to pay](https://docs.payme.io/accepting-payments/checkout-and-in-person/let-the-buyer-choose): Send sale_payment_method: multi to generate-sale (default is credit-card). The card form is always shown. Apple Pay, Google Pay and Bit appear only if the seller's service is active and installments is 1, 0 or 102-112; fixed 2-12 leaves card only. Wallet buttons need a browser that supports them; Bit is ILS only; capture_buyer keeps card and Apple Pay (if set up). Wallets and Bit pay in one payment. Callbacks carry the method used in sale_payment_method; get-sales keeps multi, get-transactions has transaction_payment_method. Not a template sale.
- [Accept payments in a mobile app](https://docs.payme.io/accepting-payments/checkout-and-in-person/mobile-apps): Mobile app checkout: the app calls your server; your server calls generate-sale with the MPL and returns sale_url; the app opens it in SFSafariViewController (iOS) or Chrome Custom Tabs (Android), not a WebView. sale_return_url must be a public http(s) URL (myapp:// fails with error 21): use an HTTPS page that hands back with Universal Links/App Links or a button. Handle a closed browser. Confirm with the sale-complete callback and get-sales (sale_status completed, sale_price). Test wallets in the in-app browser on real devices. The iOS and Android SDKs are legacy.

## Payment Methods

- [Accept Apple Pay](https://docs.payme.io/accepting-payments/payment-methods/apple-pay): Accept Apple Pay on PayMe's Hosted Payment Page, or show the Apple Pay button on your own page: host PayMe's domain file, register the domains with vas-enable, create the sale and call appleSale().
- [Accept Google Pay](https://docs.payme.io/accepting-payments/payment-methods/google-pay): Accept Google Pay on PayMe's Hosted Payment Page, or render the Google Pay button on your own page with googleSale(): setup, the payment result including 3D Secure, errors and testing.
- [Israeli Direct Debit](https://docs.payme.io/accepting-payments/payment-methods/israeli-direct-debit): Collect an Israeli direct debit authorization (mandate) with generate-sale and sale_type token, then charge the bank account with the returned token (buyer_key). Covers the callbacks and timing of each step.
- [Accept Bit payments](https://docs.payme.io/accepting-payments/payment-methods/bit): Bit runs on PayMe's payment page only. Enable it: the seller installs Bit from the dashboard app store, or a partner calls vas-enable (status_code 2 means PayMe completes it); without it generate-sale returns 720. Create the sale with sale_payment_method: bit (or multi), currency ILS, one payment (351), no capture_buyer (4). The buyer scans a QR code or opens the Bit app and approves. sale-complete on success; sale-failure with 23001 rejected, 23002 canceled, 23003 expired; the same sale_url stays payable. Refund with refund-sale.
- [Accept PayPal payments](https://docs.payme.io/accepting-payments/payment-methods/paypal): PayPal sales settle in the seller's own PayPal account, not the PayMe balance: no withdrawals, no market_fee, refunds paid from PayPal. Activation: contact PayMe Partners (partners@payme.io); without it generate-sale returns 720. Create the sale with generate-sale, sale_payment_method paypal, and send sale_callback_url, sale_return_url and cancel_url. Redirect the buyer to sale_url (not an iframe). One payment only (351), no capture_buyer (4), not on multi. Authorize: capture-sale or multi-capture; void the whole authorization only. PayPal disputes don't reach PayMe.

## Capture and Saved Cards

- [Authorize now, capture later](https://docs.payme.io/accepting-payments/capture-and-saved-cards/capture-sale): Place a hold on the buyer's card, then charge it within 7 days with capture-sale, or release it with refund-sale.
- [Capture an authorization in several parts](https://docs.payme.io/accepting-payments/capture-and-saved-cards/multi-capture): Multi-capture: charge an authorized card or PayPal sale in several parts, each a new sale linked to the authorization.
- [Save a card with a token sale](https://docs.payme.io/accepting-payments/capture-and-saved-cards/create-payment-with-buyer-key-token): Moved. Saving a buyer's card as a token (buyer_key) and charging it later is covered in the guide Save a card and charge it later: /accepting-payments/capture-and-saved-cards/save-a-card-and-charge-it-later
- [Build recurring billing with subscriptions](https://docs.payme.io/accepting-payments/capture-and-saved-cards/build-recurring-billing): generate-subscription: status 1 with sub_url, or status 2 with a permanent buyer_key. A job charges each iteration from sub_start_date; each attempt is a sale_type 3 sale; success sends sub-iteration-success with payme_sale_id. List a subscription's sales with get-sales sale_type 3 + sale_parent_code = sub_payme_code. Card check fails: status 4, no retry. Renewal fails: status 7, daily retry, 7 attempts, then 5 + sub-cancel. Pause skips iterations; a paused subscription can't be canceled (305). set-price changes future charges. No wallets.
- [Save a card and charge it later](https://docs.payme.io/accepting-payments/capture-and-saved-cards/save-a-card-and-charge-it-later): Save a card as a buyer_key: capture_buyer: 1 on generate-sale (charge and save), sale_type: token (save, no charge), Hosted Fields tokenize() or capture-buyer-token (PCI). capture-buyer-token is single-use unless buyer_is_permanent: true; a used token gives 604. buyer_is_private: true = one seller; default = any seller of the partner, and get-buyer-key then needs payme_client_key (603). Charge: generate-sale + buyer_key, at once, no CVV, no 3D Secure; a decline is HTTP 200 with status_code 1. Store buyer_key encrypted, server-side.

## 3D Secure

- [3D Secure as a service](https://docs.payme.io/accepting-payments/3d-secure/3d-secure-as-a-service): Run PayMe's 3D Secure 2 authentication as its own API call, without charging the card, and use the result with PayMe or another gateway.
- [3DS with Hosted Fields](https://docs.payme.io/accepting-payments/3d-secure/3ds-with-hosted-fields): Run 3D Secure on a Hosted Fields token: collect the browser data with PayMe.clientData, pay the sale with pay-sale and meta_data_jwt, and handle the challenge redirect and the result.
- [How 3D Secure works on PayMe](https://docs.payme.io/accepting-payments/3d-secure/how-3d-secure-works): PayMe runs 3D Secure 2 on a card payment when the seller has the 3D Secure service (PayMe enables it), the card brand is supported (not Discover, JCB or Isracard) and a rule selects it: a foreign card, 3+ installments, an amount at or above the account's threshold (minor units, no currency conversion), the account's own rules, or services 3DSecure active:true. active:false can't skip the system rules. Hosted Fields and the Direct API must send meta_data_jwt to pay-sale, or 3D Secure is skipped silently. A challenge returns status_code 5 and redirect_url. A failed check returns 21017.

## After the Sale

- [Handle chargebacks](https://docs.payme.io/accepting-payments/after-the-sale/handle-chargebacks): A chargeback is a payment the buyer's issuer takes back; the issuer decides. PayMe sends sale-chargeback (sale_status chargeback or partial-chargeback; inquiry_number, inquiry_code, card_last_four_digits, vas_3ds_exists) and emails the seller. The amount is taken from the PayMe balance; a handling fee may apply under the agreement and isn't returned automatically. Respond as the email describes, within its deadline; there is no chargeback API. A reversal sends sale-chargeback-refund. refund-sale on a charged-back sale returns 305. get-transactions lists chargeback rows.
- [Issue invoices and receipts for your sales](https://docs.payme.io/accepting-payments/after-the-sale/issue-invoices-and-receipts): Automatic documents: with invoicing set up, a paid or captured sale issues a document and each refund a credit document. sale_invoice_url is in sale-complete and refund; the number comes later in get-sales sale_invoices. Skip one sale with services [{name: invoice, settings: {active: false}}]. Documents API (deprecated, contact partners@payme.io first): needs its own activation (703); POST /documents with doc_type, buyer_name, items; asynchronous, so GET /documents/{doc_id} returns 1005 until ready; authority_redirect_url means Tax Authority approval first.

## Reporting

- [Find the right data](https://docs.payme.io/accepting-payments/reporting/find-the-right-data): Lookup table from business questions to the PayMe query API, filters and response fields that answer them (get-transactions for volume, refunds and chargebacks; get-sales for order status and release dates; get-subscriptions; get-sellers for balances; get-withdrawals and get-future-withdrawals for payouts), with paging (500 per page by default), Asia/Jerusalem time, rate limits and who can query what.
- [Reconcile sales and withdrawals](https://docs.payme.io/accepting-payments/reporting/reconcile-sales-and-withdrawals): Step-by-step reconciliation of a seller's withdrawals (get-withdrawals, with withdrawal_source and withdrawal_card_brand) against money movements (get-transactions grouped by transaction_release_date, net of fees via transaction_price_after_fees), how to catch missed callbacks with get-sales, the fee fields in sale_fees, and why the totals can differ.