# Get API access and go live: from sandbox to production

Building with an AI agent? Start at https://docs.payme.io/agents.md

## Prerequisites

- A PayMe account, or a registration at paid.co.il

## Related

- [Authentication](/payments/getting-started/authentication)
- [Environments](/payments/getting-started/environments)
- [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods)
- [Quickstart](/payments/getting-started/quickstart)
- [Callbacks](/payments/getting-started/callbacks)
- [Errors](/payments/getting-started/errors)
- [Idempotency and Retries](/payments/getting-started/idempotency-and-retries)
- [Hosted Fields JSAPI guide](/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide)
- [Accept Apple Pay](/accepting-payments/payment-methods/apple-pay)
- [Accept Google Pay](/accepting-payments/payment-methods/google-pay)

This guide puts the launch steps in order: get the right credentials, open your sandbox account, test what you built, then switch to production with the checklist below. Each step links to the reference page with the details.

## Step 1: Know which credentials you need

| Credential | Who has it | What it's for | Where to find it |
|---|---|---|---|
| `seller_payme_id` (the MPL) | Every seller | Identifies and authenticates the seller on server calls such as `generate-sale` and `refund-sale`. Keep it on your server. | Dashboard: **Admin → API & Integration** (API ואינטגרציה) |
| Public key | Every seller, one per environment | Browser code: `PayMe.create(publicKey, …)` for Hosted Fields, Apple Pay and Google Pay | The same page, section **Hosted Fields JSAPI Credentials** |
| `payme_client_key` | Partners (platforms and marketplaces) only | Partner calls such as `create-seller`, and queries across your sellers | Issued by PayMe Partners (<partners@payme.io>) |
| Client password | Partners only | Verifying `payme_signature` on callbacks | Issued together with `payme_client_key` |

- A seller account has no `merchant_key`, `merchant_password` or `payme_client_key`. A seller that puts its own MPL in `payme_client_key` gets error `200`: remove the field and send `seller_payme_id` alone.
- Every credential belongs to one environment. The sandbox and production are separate accounts, and a sandbox key is rejected in production, and the reverse.
- Only the public key may appear in browser or mobile code.

Where each credential goes in a request: [Authentication](/payments/getting-started/authentication).

### If the API & Integration page is missing

The page appears once the API service is installed on the account. Install it from the dashboard app store (חנות אפליקציות). Depending on your account, it may carry a charge.

## Step 2: Open your sandbox account

The sandbox is free and asks for no signatures.

- **You already have a PayMe account:** in the dashboard, click your name at the top, then **Switch to test account** → **Create test account**.
- **You have no account yet:** register at <https://paid.co.il> → "הרשמה" (Register), then open the test account from the dashboard as above. The "התנסות" (Try it out) button opens a shared demo, not your own sandbox: it has no keys of your own.

The test account shows a white top bar, and production a green one. To switch back, click your name → **Switch to live account**. While the test account is open, **Admin → API & Integration** shows your sandbox MPL and public key.

A test account can't be converted into a live account. Sandbox tokens (`buyer_key`) and sandbox MPLs don't work in production.

If you can't open the test account, contact PayMe: <https://help.payme.io> for dashboard and account questions, <partners@payme.io> for integration questions.

## Step 3: Build and test in the sandbox

Send every sandbox call to `https://sandbox.payme.io/api/` with your sandbox credentials. Send `"language": "en"` to get error messages in English. The [Quickstart](/payments/getting-started/quickstart) runs the first checks below with `curl`.

```bash
curl -X POST https://sandbox.payme.io/api/generate-sale \
  -H 'Content-Type: application/json' \
  -d '{
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "sale_price": 1000,
    "currency": "ILS",
    "product_name": "Test order",
    "transaction_id": "order-1001",
    "sale_callback_url": "https://your-server.example.com/payme/callback",
    "sale_return_url": "https://your-site.example.com/payment/success",
    "language": "en"
  }'
```

The callback URL must be a public address even in the sandbox. `localhost`, private and loopback IP addresses and IPv6 addresses fail the whole call with error `21`. See [Callback URL rules](/payments/getting-started/callbacks#callback-url-rules).

Run these checks before you go live:

| Check | How | What you should see |
|---|---|---|
| Create a sale | [generate-sale](/payments/hosted-payment-page/post-generate-sale), as above | `status_code` `0`, a `sale_url` and a `payme_sale_id`. Store `payme_sale_id` with your order. |
| Pay it | Open `sale_url` and pay with `5326105300985846`, expiry `12/30`, CVV `658`, ID `008336174` | The buyer is redirected to `sale_return_url` |
| Receive the callback | Your `sale_callback_url` | A form-encoded `POST` with `notify_type` `sale-complete`. Reply `200` within 5 seconds. |
| Confirm the sale | [get-sales](/payments/query-apis/post-get-sales) with `sale_payme_id` | `sale_status` `completed` and the `sale_price` of your order |
| Handle a decline | Pay with `4000000000000002` | Error `20004`, and a `sale-failure` callback |
| Refund | [refund-sale](/payments/post-sale-actions/post-refund-sale) with `seller_payme_id` and `payme_sale_id` | `status_code` `0`, and a `refund` callback |

If your sales go through 3D Secure, test the challenge too: the cards and the rules that select a sale are on [3D Secure in the sandbox](/payments/getting-started/test-cards-and-payment-methods#3d-secure-in-the-sandbox). The challenge code is `555`.

All test data, including the other decline cards, Apple Pay cards and bank accounts, is on [Test Cards and Payment Methods](/payments/getting-started/test-cards-and-payment-methods).

### What the sandbox doesn't cover

- **Invoices and receipts:** the invoicing service doesn't run in the sandbox. Test documents on a small live sale that you refund straight away.
- **Apple Pay on your own page:** ask PayMe which environment to test it in. See [Accept Apple Pay](/accepting-payments/payment-methods/apple-pay).

## Step 4: Go-live checklist

Work through every item before your first live sale.

### Credentials and URLs

- [ ] Every server call goes to `https://live.payme.io/api/`.
- [ ] You use the production MPL and the production public key. Partners also use the production `payme_client_key` and client password.
- [ ] Credentials come from your server's configuration, not from code. The MPL, `payme_client_key` and client password never reach the browser or a mobile app.

A credential from the other environment fails: a sandbox MPL in production returns `163` or `251`, and a partner key from the other environment returns `200`. See [Errors](/payments/getting-started/errors).

### Browser code

- [ ] `PayMe.create(publicKey, { testMode: false })`, with the production public key. `testMode` is the only switch: load the same Hosted Fields script URL in both environments. See [Hosted Fields](/accepting-payments/checkout-and-in-person/hosted-fields-jsapi-guide).
- [ ] With 3D Secure on Hosted Fields: `PayMe.clientData(false)`, or no argument. See [3DS with Hosted Fields](/accepting-payments/3d-secure/3ds-with-hosted-fields).
- [ ] With Google Pay on your own page: `PayMe.isGooglePayAvailable(false)`.
- [ ] If your site sets a Content Security Policy, it allows the production hosts that the Hosted Fields, Apple Pay and Google Pay pages list, and the host of the 3D Secure `redirect_url` you receive (a `paymeservice.com` address). See [Environments](/payments/getting-started/environments).

### Test data

- [ ] Test card numbers, test bank accounts and test seller values (such as `9999999999` and `random@paymeservice.com`) are gone from production code, configuration and forms.
- [ ] Nothing from the sandbox, such as tokens or MPLs, is reused in production.

### Payment methods and services

- [ ] Every payment method you offer is active on the production account. A seller installs Apple Pay, Google Pay or Bit from the production dashboard's app store. A partner calls `vas-enable` against `live.payme.io`. A missing service fails with error `720`.
- [ ] 3D Secure, if you need it, is enabled on the production account. PayMe enables it, so confirm with PayMe before launch. Google Pay cards saved in the buyer's Google account always go through 3D Secure, and fail with error `21017` without the service.
- [ ] **Apple Pay on your own page:** every domain that shows the button serves the **production** domain file, downloaded from `https://live.payme.io/.well-known/apple-developer-merchantid-domain-association`, and the domains are registered in production. The sandbox file is different, and a mismatch fails the call with error `703`. See [Host PayMe's domain file](/accepting-payments/payment-methods/apple-pay#step-1-host-paymes-domain-file). Apple Pay on PayMe's Hosted Payment Page needs no file.
- [ ] **Google Pay on your own page:** your registration in the Google Pay & Wallet Console is complete, and PayMe Partners confirmed it. See [Accept Google Pay](/accepting-payments/payment-methods/google-pay).
- [ ] The production account allows each currency you charge (error `252`) and the number of installments you offer. More than 12 installments must be enabled by PayMe.

### Callbacks

- [ ] Every `generate-sale` sends `sale_callback_url`, and every subscription sends `sub_callback_url`, pointing at your production endpoint. A seller has no dashboard setting for a default.
- [ ] The endpoint is public, uses HTTPS and replies `200` within 5 seconds.
- [ ] Partners verify `payme_signature` with the production `payme_client_key` and client password.
- [ ] Your handler ignores repeats (`notify_type` + `payme_sale_id` + `payme_transaction_id`) and confirms the sale with `get-sales` before you fulfil an order.
- [ ] You don't allow-list callbacks by IP address: PayMe doesn't publish a fixed list.

Details: [Callbacks](/payments/getting-started/callbacks).

### Retries, limits and monitoring

- [ ] A timed-out call that moves money is checked with `get-sales` before it is retried. PayMe has no idempotency key.
- [ ] HTTP 429 with error `998` is handled with backoff. Payment calls share a per-seller rate limit: see [Rate limits](/payments/getting-started/idempotency-and-retries#rate-limits).
- [ ] A scheduled job reconciles your orders with `get-sales`, because a callback is dropped after 3 failed attempts.
- [ ] You log the `session` value of each response, so you can quote it to PayMe.

### First live payment

Run one real sale for a small amount with your own card, and refund it. Check that the callback arrived and that `get-sales` shows the sale. If PayMe issues invoices for your sales, check the document on this sale too.

## If a key leaks

There is no self-service key rotation. If you think a key has leaked, contact PayMe support at once.

If PayMe moves a partner to a new client key, your API calls can use the new key straight away. The callback signature stays on your primary client key until PayMe completes the switch.

## After launch

- **A callback didn't arrive:** look the sale up with `get-sales`. By default it leaves out unpaid sales (status `initial`), so add `initial` to `sale_status` to see them. If your endpoint keeps failing or timing out, PayMe pauses deliveries to your host for a while; see [Retries](/payments/getting-started/callbacks#retries).
- **An error you don't recognize:** look the code up on [Errors](/payments/getting-started/errors).
- **Need help:** write to <partners@payme.io> for integration questions and quote the `session` value. PayMe's [Status Page](https://status.payme.io/) shows incidents and maintenance.

## Partners

If you are a platform or marketplace:

- PayMe Partners issues your `payme_client_key` and client password.
- Each of your sellers has its own MPL and public key in each environment. Production sellers are created with `create-seller` on `live.payme.io`, which returns their production MPL and public key.
- Create test sellers in the sandbox with the values on [Creating test sellers](/payments/getting-started/test-cards-and-payment-methods#creating-test-sellers-partners).

The whole partner flow is on [Start here: build a platform or marketplace on PayMe](/marketplaces-and-platforms/start-here/how-platforms-work).