# Create a partner-level token Building with an AI agent? Start at https://docs.payme.io/agents.md - Sandbox: `POST https://sandbox.payme.io/api/sellers/{mpl}/tokens` - Production: `POST https://live.payme.io/api/sellers/{mpl}/tokens` ## Credentials - Request body field `options.validate_token` (optional): Check the card with the issuer before saving it. Default `true`. ## Overview **For PayMe partners only.** Saves a card as a token that belongs to your partner account, so you can charge it later for any of your sellers. A buyer saves a card while buying from one seller and can then pay another seller without typing it again. A seller-level token can't do that. The MPL in the path (the `seller_payme_id` of one of your sellers) identifies your account; the call takes no other key. Treat the MPL as a secret: call this endpoint from your server only, never from a browser. **This endpoint takes raw card details, so call it only if you are PCI DSS certified.** Without that certification, capture the same kind of token on a page PayMe hosts: send [`generate-sale`](/payments/hosted-payment-page/post-generate-sale) with `sale_type: "seller-token"` and show the buyer its `sale_url`. PayMe sets the price of such a sale itself. ## Using the token The token is the `uuid` in the response. Send it as `token` on `generate-sale`, with the `seller_payme_id` of the seller you are charging for. It is not a `buyer_key`: sent as `buyer_key`, it fails with error `600`. Against a seller of a different partner it fails with error `605`. The token is permanent: it doesn't expire in PayMe, and each charge with it runs at once, with no CVV and no 3D Secure. A charge can still fail if the card has expired or the issuer declines it. The response isn't PayMe's usual envelope. A success has no `status_code`, so check for HTTP 201 and a `uuid`. A failure has the usual `status_code: 1` and `status_error_code`; decide from those, not from the HTTP status. A token is a bearer credential: store it encrypted, and never log it or send it to a browser. See [Saved Cards](/agents/steps/saved-cards) for the rules. This page covers `credit-card`, the method checked in the sandbox. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `mpl` | path | string | yes | The `seller_payme_id` (MPL) of one of your sellers. It identifies your partner account, so keep it secret and send it from your server only. The token is stored under this seller and can be charged for your other sellers too. | ## Request body Content type: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `payment` | object | yes | The card to save. | | `payment.method` | string | yes | `credit-card`. | | `payment.card_number` | string | yes | Card number, digits only. | | `payment.card_expiry` | string | yes | Card expiry, `MMYY`. | | `payment.card_cvv` | string | no | CVV, 3 or 4 digits. Required unless `options.use_token_terminal` is `true`; missing, it returns error `1`. | | `customer` | object | yes | The buyer. | | `customer.name` | string | yes | Buyer's full name. Missing: error `1`. | | `customer.email` | string | yes | Buyer's email address. Missing or invalid: error `13`. | | `customer.phone` | string | yes | Buyer's phone number. Missing: error `1`. | | `customer.social_id` | string | no | Buyer's Israeli ID number. When sent, it must be a valid Israeli ID. | | `customer.zip_code` | string | no | Buyer's zip code. | | `customer.country` | string | no | Buyer's country, a two-letter code such as `IL`. | | `customer.state` | string | no | Buyer's state or region. | | `customer.city` | string | no | Buyer's city. | | `customer.line1` | string | no | Buyer's street address. | | `customer.line2` | string | no | Buyer's address, second line. | | `customer.business_code` | string | no | For a business buyer: its registration number. Send it with `customer.business_name`, or neither. | | `customer.business_name` | string | no | For a business buyer: its name. Send it with `customer.business_code`, or neither. | | `options` | object | no | Token options. | | `options.validate_token` | boolean | no | Check the card with the issuer before saving it. Default `true`. | | `options.use_token_terminal` | boolean | no | `true` to save the card without a CVV, on a token terminal. Then `payment.card_cvv` is optional. Default `false`. | ### Request example ```json { "payment": { "method": "credit-card", "card_number": "4557430402053431", "card_expiry": "1230", "card_cvv": "200" }, "customer": { "name": "First Last", "email": "buyer@example.com", "phone": "+972501234567", "social_id": "008336174" } } ``` ## Code samples ### curl ```bash curl -X POST 'https://sandbox.payme.io/api/sellers//tokens' \ -H 'Content-Type: application/json' \ --data-raw '{ "payment": { "method": "credit-card", "card_number": "4557430402053431", "card_expiry": "1230", "card_cvv": "200" }, "customer": { "name": "First Last", "email": "buyer@example.com", "phone": "+972501234567", "social_id": "008336174" } }' ``` ### Node.js ```javascript const response = await fetch("https://sandbox.payme.io/api/sellers//tokens", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "payment": { "method": "credit-card", "card_number": "4557430402053431", "card_expiry": "1230", "card_cvv": "200" }, "customer": { "name": "First Last", "email": "buyer@example.com", "phone": "+972501234567", "social_id": "008336174" } }), }); console.log(await response.text()); ``` ### Python ```python import requests response = requests.post( "https://sandbox.payme.io/api/sellers//tokens", json={ "payment": { "method": "credit-card", "card_number": "4557430402053431", "card_expiry": "1230", "card_cvv": "200", }, "customer": { "name": "First Last", "email": "buyer@example.com", "phone": "+972501234567", "social_id": "008336174", }, }, ) print(response.text) ``` ### PHP ```php /tokens'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => $body, ]); $response = curl_exec($ch); curl_close($ch); echo $response; ``` ## Responses ### 201 — The token was created (success) | Field | Type | Description | | --- | --- | --- | | `uuid` | string | The token. Send it as token on generate-sale. | | `customer` | object | name, email, phone and social_id | | `payment` | object | display (the masked card number), expiry, brand, club, type, organization, origin_country and is_foreign | ```json { "uuid": "00000000-0000-0000-0000-000000000000", "customer": { "name": "First Last", "email": "buyer@example.com", "phone": "+972501234567", "social_id": "008336174" }, "payment": { "display": "455743******3431", "expiry": "1230", "brand": "Visa" } } ``` ### 400 — The card was declined or failed validation. Read `status_code` and `status_error_code`. (error) | Field | Type | Description | | --- | --- | --- | | `status_code` | integer | `1`: the request failed. | | `status_error_code` | integer | PayMe's error code, such as `20004` for a declined card. | | `status_error_details` | string | The error message. | | `status_additional_info` | string | More detail, such as the masked card number. | ```json { "status_code": 1, "status_error_code": 20004, "status_error_details": "Refusal by credit company. Please try a different card", "status_additional_info": "400000******0002" } ``` ### 500 — A required field is missing or invalid (error) | Field | Type | Description | | --- | --- | --- | | `status_code` | integer | 1 | | `status_error_code` | integer | `1` for a missing field (`customer.name`, `customer.phone`, `payment.card_cvv` and so on), named in `status_additional_info`. `13` for a missing or invalid email. | | `status_error_details` | string | The error message | | `status_additional_info` | string | The field at fault, when there is one | ```json { "status_code": 1, "status_error_code": 1, "status_error_details": "Required parameter is missing", "status_additional_info": "payment.card_cvv" } ```