{"openapi":"3.1.0","info":{"title":"Products and Customers","version":"1.0.0","description":"API reference for storing a seller's product catalogue and customer records: create, list, update and delete products and customers, authenticated with a JWT from `POST /auth/token`."},"servers":[{"url":"https://payme-store-staging.payme.io/api","description":"Sandbox"},{"url":"https://payme-store.payme.io/api","description":"Production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"partnerKey":{"type":"apiKey","in":"header","name":"PayMe-Partner-Key"},"merchantKey":{"type":"apiKey","in":"header","name":"PayMe-Merchant-Key"}}},"tags":[{"name":"Authentication"}],"paths":{"/auth-tokens":{"post":{"operationId":"post-auth-token","summary":"Get an access token","tags":["Authentication"],"description":"Exchanges a seller's MPL and its partner's `payme_client_key` for an access token and a refresh token. Send the access token as `Authorization: Bearer <auth_token>` on every product and customer call.\n\nOnly partners can get a token: the seller in `mpl` must belong to the partner whose key you send in `key`. When the access token expires, get a new pair with [`POST /refresh-exchanges`](/products-and-customers/authentication/post-auth-refresh).\n\nWrong or mismatched credentials return an error; read `status_error_details`. The HTTP status can be `400`, `401` or `500`, depending on how PayMe's core rejects the credentials.\n\nHosts and the error format: [Hosts, authentication and errors](/products-and-customers/authentication).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mpl":{"type":"string","description":"The seller's MPL (`seller_payme_id`), e.g. `MPLDEMO-MPLDEMO-MPLDEMO-1234567`. The token acts for this seller."},"key":{"type":"string","description":"The partner's `payme_client_key`. The seller in `mpl` must belong to this partner."}},"required":["mpl","key"]},"example":{"mpl":"MPLDEMO-MPLDEMO-MPLDEMO-1234567","key":"your_payme_client_key"}}},"description":"The seller and partner credentials."},"responses":{"201":{"description":"Tokens issued.","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"auth_token":{"type":"string","description":"The access token, a JWT. Send it as `Authorization: Bearer <auth_token>` on product and customer calls."},"refresh_token":{"type":"string","description":"A single-use token for `POST /refresh-exchanges`, which returns a new pair of tokens."}}},"example":{"auth_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3YzFlNGQ5YSJ9.c2lnbmF0dXJl","refresh_token":"b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53"}}}},"400":{"description":"`mpl` or `key` is missing or not a string, or the body isn't valid JSON. Wrong credentials can also return `400`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_error_details":{"type":"string","description":"What went wrong. Validation messages are in Hebrew unless you send `Accept-Language: en`."},"status_error_code":{"type":"integer","description":"`501` for a validation error or a body that isn't valid JSON, `999` for any other error."},"validation_errors":{"type":"object","description":"The fields that failed validation. Each key is a field name; its value maps each failed rule to a message."},"session":{"type":"string","description":"Trace id of the request. Quote it when you contact PayMe support."}}},"example":{"status_error_details":"Field validation failed.","validation_errors":{"key":{"is_not_empty":"The field is required.","is_string":"The value must be a string."}},"status_error_code":501,"session":"f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"}}}},"401":{"description":"The credentials don't identify a seller of this partner.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_error_details":{"type":"string","description":"What went wrong."},"status_error_code":{"type":"integer","description":"`999`."},"session":{"type":"string","description":"Trace id of the request. Quote it when you contact PayMe support."}}},"example":{"status_error_details":"No Genesis identity found for the credentials","status_error_code":999,"session":"f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"}}}},"500":{"description":"Server error. Wrong credentials can also return `500`. Contact PayMe support and quote the `session`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_error_details":{"type":"string","description":"What went wrong."},"status_error_code":{"type":"integer","description":"`999`."},"session":{"type":"string","description":"Trace id of the request. Quote it when you contact PayMe support."}}}}}}}}},"/refresh-exchanges":{"post":{"security":[{"partnerKey":[],"merchantKey":[]}],"operationId":"post-auth-refresh","summary":"Refresh an access token","tags":["Authentication"],"description":"Exchanges a refresh token for a new access token and a new refresh token. The refresh token you send stops working, so store the new one.\n\nThe refresh token identifies the seller, so the call needs no `Authorization`, `PayMe-Partner-Key` or `PayMe-Merchant-Key` header. If the refresh token is unknown, already used or expired, start again with [`POST /auth-tokens`](/products-and-customers/authentication/post-auth-token).\n\nHosts and the error format: [Hosts, authentication and errors](/products-and-customers/authentication).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refresh_token":{"type":"string","description":"The `refresh_token` from your last `POST /auth-tokens` or `POST /refresh-exchanges` call. Each refresh token works once."}},"required":["refresh_token"]},"example":{"refresh_token":"b6f0d3a2-8c41-4e5f-9a7d-2e1c0b9f4a53"}}},"description":"The refresh token to exchange."},"responses":{"201":{"description":"New tokens issued. The refresh token you sent no longer works.","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"auth_token":{"type":"string","description":"The access token, a JWT. Send it as `Authorization: Bearer <auth_token>` on product and customer calls."},"refresh_token":{"type":"string","description":"A single-use token for `POST /refresh-exchanges`, which returns a new pair of tokens."}}},"example":{"auth_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5ZDJiNmYxMCJ9.c2lnbmF0dXJl","refresh_token":"0e7c4b19-2d6a-4f83-b5e1-7a9c3d2f8b64"}}}},"400":{"description":"`refresh_token` is missing or not a string, or the body isn't valid JSON.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_error_details":{"type":"string","description":"What went wrong. Validation messages are in Hebrew unless you send `Accept-Language: en`."},"status_error_code":{"type":"integer","description":"`501` for a validation error or a body that isn't valid JSON, `999` for any other error."},"validation_errors":{"type":"object","description":"The fields that failed validation. Each key is a field name; its value maps each failed rule to a message."},"session":{"type":"string","description":"Trace id of the request. Quote it when you contact PayMe support."}}},"example":{"status_error_details":"Field validation failed.","validation_errors":{"refresh_token":{"is_not_empty":"The field is required.","is_string":"The value must be a string."}},"status_error_code":501,"session":"f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"}}}},"401":{"description":"The refresh token is unknown, already used or expired. Get a new pair with `POST /auth-tokens`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_error_details":{"type":"string","description":"What went wrong."},"status_error_code":{"type":"integer","description":"`999`."},"session":{"type":"string","description":"Trace id of the request. Quote it when you contact PayMe support."}}},"example":{"status_error_details":"Unauthorized","status_error_code":999,"session":"f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"}}}},"500":{"description":"Server error. Contact PayMe support and quote the `session`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_error_details":{"type":"string","description":"What went wrong."},"status_error_code":{"type":"integer","description":"`999`."},"session":{"type":"string","description":"Trace id of the request. Quote it when you contact PayMe support."}}}}}}}}}}}