{"openapi":"3.1.0","info":{"title":"Payments","version":"1.0.0","description":"API reference for accepting payments with PayMe — sales via hosted payment page, hosted fields or direct API, tokens, subscriptions, refunds and captures, 3D Secure, invoices and point-of-sale. Start with Getting Started for credentials, environments and a first sale."},"servers":[{"url":"https://sandbox.payme.io/api","description":"Sandbox"},{"url":"https://live.payme.io/api","description":"Production"}],"components":{"securitySchemes":{"merchantKey":{"type":"apiKey","in":"header","name":"PayMe-Merchant-Key"},"partnerKey":{"type":"apiKey","in":"header","name":"PayMe-Partner-Key"},"publicKey":{"type":"apiKey","in":"header","name":"PayMe-Public-Key"},"signature":{"type":"apiKey","in":"header","name":"PayMe-Signature"}}},"tags":[{"name":"Direct API"}],"paths":{"/pay-sale":{"post":{"operationId":"post-pay-sale","summary":"Pay a sale","tags":["Direct API"],"description":"## Overview\n\nCharges a card, or a saved card, on a sale you created with [`generate-sale`](/payments/hosted-payment-page/post-generate-sale). Use it in the [Direct API](/payments/direct-api) (PCI DSS Level 1 partners only) and to finish a [Hosted Fields](/payments/hosted-fields-jsapi) payment.\n\nThis call takes no credentials: PayMe finds the sale by `payme_sale_id`, and the price, currency and callback URLs come from the sale. Treat `payme_sale_id` like the payment link: share it only with the buyer who pays it. \n\nSend either the card fields (`credit_card_number`, `credit_card_exp`, `credit_card_cvv`) with `buyer_name` and `buyer_email`, or a saved card in `buyer_key` (or a partner-level `token`). With `buyer_key` or `token`, PayMe uses the saved card's details and needs no CVV. \n\n### Reading the result\n\nThe response is synchronous. PayMe also sends the sale [callbacks](/payments/getting-started/callbacks). Read `status_code`:\n\n| `status_code` | Meaning | What to do |\n|---|---|---|\n| `0` | Paid. On a sale created with `sale_type: \"authorize\"`, authorized: charge it later with [`capture-sale`](/payments/post-sale-actions/post-capture-sale). On a `token` sale, the card is saved and not charged. | Read `sale_status`. |\n| `1` | Declined, with HTTP 200. `status_error_code` and `status_error_details` give the reason. The sale becomes `failed` and can be paid again. | Ask the buyer for another card. |\n| `5` | The card issuer asks for a 3D Secure challenge. | Send the buyer's browser to `redirect_url`. The result arrives in the sale callback. |\n\n\n\n### Before you call\n\n- The sale must be `initial` or `failed`; otherwise the call returns error `305` with the sale's status in `status_additional_info`. An expired sale returns `367`.\n- Only card sales can be paid here: a sale created for another payment method returns error `2`.\n- A value that looks like a card number in any field other than `credit_card_number` is rejected with HTTP 400, error `20`.\n- Send one call per sale at a time. A second call while the first is still running returns HTTP 429, error `998`.\n\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payme_sale_id":{"type":"string","description":"The sale to pay: the `payme_sale_id` that `generate-sale` returned."},"credit_card_number":{"type":"string","description":"Card number, digits only. Required unless you send `buyer_key` or `token`."},"credit_card_exp":{"type":"string","description":"Card expiry as `MMYY` (`MM/YY` and `MMYYYY` are also accepted). Required unless you send `buyer_key` or `token`."},"credit_card_cvv":{"type":"string","description":"CVV, 3 or 4 digits. Required with the card fields unless `token_terminal` is `true`. On a sale whose `layout` is `token-capture` or `dynamic-loose`, leaving it out sends the payment to a token terminal."},"token_terminal":{"type":"boolean","description":"`true` to charge the card fields without a CVV, on a token terminal. Default `false`."},"buyer_key":{"type":"string","description":"A saved card to pay with instead of the card fields. See [Save a card as a token](/payments/tokenization/post-capture-buyer-token)."},"token":{"type":"string","description":"A partner-level token to pay with instead of the card fields: the `uuid` from [Create a partner-level token](/payments/tokenization/post-sellers-mpl-tokens)."},"buyer_name":{"type":"string","description":"Buyer's full name. Required, with `buyer_email`, when you pay with the card fields, unless the sale's `layout` is `token-capture` or `dynamic-loose`."},"buyer_email":{"type":"string","description":"Buyer's email address. Same rule as `buyer_name`."},"buyer_phone":{"type":"string","description":"Buyer's phone number."},"buyer_social_id":{"type":"string","description":"Buyer's national ID number, digits only. Ignored when you pay with `buyer_key` or `token`."},"buyer_zip_code":{"type":"string","description":"Buyer's zip code, letters and digits only; anything else returns error `37`."},"buyer_business_code":{"type":"string","description":"For a business buyer: its registration number. Send it with `buyer_business_name`, or neither."},"buyer_business_name":{"type":"string","description":"For a business buyer: its name. Send it with `buyer_business_code`, or neither."},"installments":{"type":"integer","description":"Number of installments the buyer chose. Required only when the sale lets the buyer choose (a sale created with `installments` above `100`, such as `106`); otherwise the sale's own value is used."},"payment_method":{"type":"string","description":"On a sale that offers several payment methods: the method being paid. Default `credit-card`."},"manual_auth_number":{"type":"string","description":"An authorization code from the card issuer (voice authorization), to re-run a `failed` sale. Send it with `buyer_key` or `token`."},"xid":{"type":"string","description":"If you ran 3D Secure yourself: its transaction ID. With `xid`, PayMe doesn't run its own 3D Secure."},"eci":{"type":"string","description":"If you ran 3D Secure yourself: the ECI value. Send it with `xid`."},"cavv":{"type":"string","description":"If you ran 3D Secure yourself: the CAVV value. Send it with `xid`."},"3ds_version":{"type":"string","description":"If you ran 3D Secure yourself: the protocol version. Send it with `xid`."},"meta_data":{"type":"object","description":"Browser data for 3D Secure, as an object. Send this or `meta_data_jwt`. See [3DS with Hosted Fields](/accepting-payments/3d-secure/3ds-with-hosted-fields)."},"meta_data_jwt":{"type":"string","description":"Browser data for 3D Secure, as the JWT Hosted Fields gives you. Send this or `meta_data`. See [3DS with Hosted Fields](/accepting-payments/3d-secure/3ds-with-hosted-fields)."},"sale_additional_data":{"type":"object","description":"Extra data to store on the sale."},"language":{"type":"string","description":"Language of error messages: `en`, or `he` (the default). `es`, `ru` and `ar` are accepted, but messages then come back mostly in English. Any other value returns error `51`."}},"required":["payme_sale_id"]},"example":{"payme_sale_id":"SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX","credit_card_number":"5326105300985846","credit_card_exp":"1230","credit_card_cvv":"658","buyer_name":"Israel Israeli","buyer_email":"buyer@example.com","buyer_social_id":"008336174","language":"en"}}}},"responses":{"200":{"description":"The payment result: paid (`status_code` `0`), declined (`1`) or a 3D Secure challenge (`5`). A decline also returns HTTP 200.","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`0`: paid (or authorized, or the card saved on a `token` sale). `1`: declined. `5`: 3D Secure challenge; send the buyer to `redirect_url`."},"status_error_code":{"type":"integer","description":"`0` on success; the decline code when `status_code` is `1`."},"status_error_details":{"type":"string","description":"The decline reason, when `status_code` is `1`."},"redirect_url":{"type":"string","description":"With `status_code` `5`: the 3D Secure page to send the buyer to. On a paid sale: the sale's return URL, or `null`."},"status_message":{"type":"string","description":"With `status_code` `5`: a message you can show the buyer."},"cancel_url":{"type":"string","description":"The sale's cancel URL, or `null`."},"payme_status":{"type":"string","description":"Legacy field. Read `status_code` instead."},"payme_sale_id":{"type":"string","description":"The sale's ID."},"payme_sale_code":{"type":"integer","description":"The sale's numeric code."},"sale_created":{"type":"string","description":"When the sale was created, `YYYY-MM-DD HH:MM:SS` (Israel time)."},"sale_status":{"type":"string","description":"The sale's status, for example `completed`, `authorized` or `failed`. See [Sale Statuses](/payments/codes-statuses/sale-statuses)."},"payme_sale_status":{"type":"string","description":"Same as `sale_status`."},"sale_type":{"type":"string","description":"The sale type as responses name it, for example `Sale` (also for an authorization) or `Token`."},"sale_payment_method":{"type":"string","description":"Payment method, for example `credit-card`."},"currency":{"type":"string","description":"Sale currency, an ISO 4217 code such as `ILS`."},"price":{"type":"integer","description":"Sale price in minor units (`10000` = 100.00)."},"transaction_id":{"type":"string","description":"Your own reference for the sale."},"sale_description":{"type":"string","description":"The sale's description."},"sale_deferred_months":{"type":"integer","description":"Deferred months on the sale, or `null`."},"is_token_sale":{"type":"boolean","description":"`true` for a `token` sale, which saves the card without charging it."},"payme_signature":{"type":"string","description":"PayMe's signature for this payment."},"payme_transaction_id":{"type":"string","description":"PayMe's ID of the payment transaction."},"payme_transaction_total":{"type":"string","description":"Amount of the transaction, in minor units."},"payme_transaction_card_brand":{"type":"string","description":"Card brand, for example `Mastercard`."},"payme_transaction_auth_number":{"type":"string","description":"Authorization number from the card issuer."},"payme_transaction_voucher":{"type":"string","description":"Voucher number of the transaction."},"payme_transaction_emv_uid":{"type":"string","description":"EMV UID of the transaction, when the acquirer returns one; usually `null`."},"payme_transaction_acquirer":{"type":"string","description":"The acquirer, for example `PayMe`."},"payme_transaction_auth_source":{"type":"string","description":"Authorization source reported for the transaction."},"payme_transaction_card_issuer":{"type":"string","description":"Card issuer, for example `Isracard`."},"payme_transaction_credit_type":{"type":"string","description":"Credit type, for example `RegularCredit`."},"buyer_name":{"type":"string","description":"Buyer's full name."},"buyer_email":{"type":"string","description":"Buyer's email address."},"buyer_phone":{"type":"string","description":"Buyer's phone number, or `null`."},"buyer_card_mask":{"type":"string","description":"Masked card number, for example `532610******5846`."},"buyer_card_exp":{"type":"string","description":"Card expiry, `MMYY`."},"buyer_card_is_foreign":{"type":"boolean","description":"`true` for a card issued outside Israel."},"buyer_social_id":{"type":"string","description":"Buyer's national ID number, or `null`."},"installments":{"type":"integer","description":"Number of installments."},"transaction_first_payment":{"type":"integer","description":"First installment, in minor units."},"transaction_periodical_payment":{"type":"integer","description":"Each later installment, in minor units; `0` for a single payment."},"transaction_arn":{"type":"string","description":"Acquirer reference (EMV UID) when the acquirer returns one; usually `null`."},"sale_paid_date":{"type":"string","description":"When the payment was made, `YYYY-MM-DD HH:MM:SS` (Israel time)."},"sale_release_date":{"type":"string","description":"Date the funds are released to the seller, `YYYY-MM-DD`, or `null`."},"sale_3ds":{"type":"boolean","description":"`true` when the payment passed 3D Secure."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":0,"status_error_code":0,"payme_status":"success","payme_sale_id":"SALEDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX","payme_sale_code":1111111,"sale_created":"2026-11-09 10:15:02","sale_status":"completed","payme_sale_status":"completed","sale_type":"Sale","sale_payment_method":"credit-card","currency":"ILS","price":10000,"transaction_id":"order-1234","sale_description":"Shirt","sale_deferred_months":null,"is_token_sale":false,"payme_signature":"b71e**************ca5a","payme_transaction_id":"TRANDEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX","payme_transaction_total":"10000","payme_transaction_card_brand":"Mastercard","payme_transaction_auth_number":"0123456","payme_transaction_voucher":"111111","payme_transaction_emv_uid":null,"payme_transaction_acquirer":"PayMe","payme_transaction_auth_source":"VoiceMail","payme_transaction_card_issuer":"Isracard","payme_transaction_credit_type":"RegularCredit","buyer_name":"Israel Israeli","buyer_email":"buyer@example.com","buyer_phone":null,"buyer_card_mask":"532610******5846","buyer_card_exp":"1230","buyer_card_is_foreign":false,"buyer_social_id":"008336174","installments":1,"transaction_first_payment":10000,"transaction_periodical_payment":0,"transaction_arn":null,"sale_paid_date":"2026-11-09 10:16:40","sale_release_date":null,"sale_3ds":false,"session":"Ab12Cd34","redirect_url":null,"cancel_url":null}}}},"400":{"description":"Error `20`: a card-like number in a field other than `credit_card_number`. Error `367`: the sale has expired.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"The sale has expired","status_additional_info":"","status_error_code":367,"session":"Ab12Cd34"}}}},"429":{"description":"Error `998`: another call for this sale is still running, or too many requests. Wait, then check the sale before retrying.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Operation is not permitted","status_additional_info":"Duplicated action detected, please retry later","status_error_code":998,"session":"Ab12Cd34"}}}},"500":{"description":"Request errors. `1`: a required field is missing (named in `status_additional_info`). `350`: no sale has this `payme_sale_id`. `305`: the sale isn't `initial` or `failed`. `354`, `355`, `356`: invalid CVV, card number or expiry. `37`: invalid `buyer_zip_code`. `351`: invalid `installments`. `2`: the sale isn't a card sale. `357`: `buyer_key` or `token` sent on a `token` sale. `600`, `604`, `605`: the saved card doesn't exist, is no longer active, or belongs to another seller.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1`: the request failed."},"status_error_code":{"type":"integer","description":"PayMe's error code. See [Errors](/payments/getting-started/errors)."},"status_error_details":{"type":"string","description":"The error message, in the language you asked for."},"status_additional_info":{"type":"string","description":"Extra detail: usually the field at fault, the sale's current status, or the masked card number."},"session":{"type":"string","description":"PayMe's ID for this request. Quote it when you contact PayMe."}}},"example":{"status_code":1,"status_error_details":"Cannot perform action due to an incorrect status","status_additional_info":"completed","status_error_code":305,"session":"Ab12Cd34"}}}}}}}}}