{"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":"Standalone 3D Secure service"}],"paths":{"/sales/{payme_sale_id}/3ds":{"post":{"security":[{"publicKey":[]}],"operationId":"post-initialize-3dsecure-request","summary":"Start 3D Secure authentication","tags":["Standalone 3D Secure service"],"description":"## Overview\n\nStarts 3D Secure 2 authentication for a card on an existing sale, without charging it. Use it when another gateway processes the payment and you need the 3DS values (`eci`, `cavv`, `xid`) from PayMe's MPI. The whole flow: [Standalone 3D Secure: process flow](/payments/standalone-3d-secure-service).\n\nCall it from the buyer's browser with the seller's public key in the `PayMe-Public-Key` header. The sale must belong to that seller. Send the browser data that PayMe's JS library collected (`meta_data_jwt`); see [3DS integration using JS API](/accepting-payments/3d-secure/3ds-with-hosted-fields).\n\nThe response has one of two outcomes:\n\n- `status_code` `0`: frictionless approval. Pass `hash_3dsecure` to your server and resolve it with [Resolve a 3D Secure hash](/payments/standalone-3d-secure-service/get-sales-payme-sale-id-3ds-hash).\n- `status_code` `5`: the issuer wants a challenge. Send the buyer to `redirect_url` (a GET request). After the challenge, the hash comes back to the page that opened it.\n\nThe seller must have the 3D Secure service active.\n\n## Errors\n\n| HTTP | Code | When |\n|---|---|---|\n| 400 | `670` | `meta_data_jwt` (or `meta_data`) is missing or can't be read. |\n| 400 | `4` | The sale uses another payment method. |\n| 400 | `720` | 3D Secure was blocked for this card. |\n| 500 | `720` | 3D Secure isn't available for this card, or the seller has no 3D Secure service. |\n| 500 | `350` | No sale has this ID. |\n| 500 | Card error code | The card number or expiry is invalid, for example `356` for the expiry. |\n| 401 | — | The `PayMe-Public-Key` header is missing or unknown. |\n| 403 | `163` | The seller isn't active. |","parameters":[{"name":"payme_sale_id","in":"path","required":true,"description":"The sale to authenticate (`payme_sale_id`). It must belong to the seller of the public key. ","schema":{"type":"string"}},{"name":"PayMe-Public-Key","in":"header","required":true,"description":"The seller's public key. Safe to use in the browser.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"type":"object","description":"The card to authenticate.","properties":{"method":{"type":"string","description":"`credit-card`."},"card_number":{"type":"string","description":"Card number. Required unless you send `buyer_key`."},"card_expiry":{"type":"string","description":"Card expiry, `MMYY`. Required unless you send `buyer_key`."},"buyer_key":{"type":"string","description":"A saved buyer token of this seller, instead of `card_number` and `card_expiry`. "}},"required":["method"]},"customer":{"type":"object","description":"Card holder details. Ignored when you send `payment.buyer_key`.","properties":{"name":{"type":"string","description":"Card holder's name."},"email":{"type":"string","description":"Card holder's email."},"phone":{"type":"string","description":"Card holder's mobile number."},"social_id":{"type":"string","description":"Card holder's national ID."},"zip_code":{"type":"string","description":"Zip code."},"country":{"type":"string","description":"Two-letter ISO country code."},"state":{"type":"string","description":"State or region."},"city":{"type":"string","description":"City."},"line1":{"type":"string","description":"Address line 1."},"line2":{"type":"string","description":"Address line 2."}}},"meta_data_jwt":{"type":"string","description":"The browser data from PayMe's JS library. Send this or `meta_data`; without either, the call fails with error `670`.  "},"meta_data":{"type":"object","description":"The browser data as a plain object, instead of `meta_data_jwt`. PayMe adds the buyer's IP and `Accept` header from the request, so send it from the buyer's browser.","properties":{"browser":{"type":"object","description":"Browser details: `userAgent`, `language`, `colorDepth`, `screen` (`height`, `width`), `timezone`, `javaEnabled` and `javaScriptEnabled`."}},"required":["browser"]},"language":{"type":"string","description":"Language of error messages: `he` (default), `en`, `es`, `ru` or `ar`."}},"required":["payment"]},"example":{"payment":{"method":"credit-card","card_number":"4111111111111111","card_expiry":"1230"},"customer":{"name":"Israel Israeli","email":"buyer@example.com","phone":"0500000000"},"meta_data_jwt":"META_DATA_JWT_FROM_THE_LIBRARY"}}}},"responses":{"200":{"description":"Frictionless approval (`0`) or a challenge (`5`).","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`0` frictionless approval: `hash_3dsecure` is returned. `5` challenge: send the buyer to `redirect_url`. "},"hash_3dsecure":{"type":"string","description":"The encrypted 3DS result, when `status_code` is `0`. Resolve it with [Resolve a 3D Secure hash](/payments/standalone-3d-secure-service/get-sales-payme-sale-id-3ds-hash). "},"status_message":{"type":"string","description":"A message you can show the buyer while redirecting, when `status_code` is `5`."},"redirect_url":{"type":"string","description":"The issuer's challenge page, when `status_code` is `5`. Open it with GET in the buyer's browser."}}},"example":{"status_code":5,"status_message":"Generating validation page, please wait","redirect_url":"https://sandbox.payme.io/3ds/redirect/SALE1700-000000AA-EXAMPLE1-SALE0001?pa=REDACTED"}}}},"400":{"description":"Browser data is missing, the sale uses another payment method, or 3D Secure was blocked. Codes: `4`, `670`, `720`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1` on failure."},"status_error_details":{"type":"string","description":"What went wrong, in the language you asked for (Hebrew by default)."},"status_additional_info":{"type":"string","description":"The field or value concerned. Can be `null`."},"status_error_code":{"type":"integer","description":"PayMe error code. See the error table above and [Errors](/payments/getting-started/errors)."},"session":{"type":"string","description":"PayMe session ID. Quote it when you contact support."}}},"example":{"status_code":1,"status_error_details":"Meta data details are missing","status_additional_info":null,"status_error_code":670,"session":"a1B2c3D4"}}}},"500":{"description":"3D Secure isn't available, the sale wasn't found, or the card data is invalid. See the error table.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1` on failure."},"status_error_details":{"type":"string","description":"What went wrong, in the language you asked for (Hebrew by default)."},"status_additional_info":{"type":"string","description":"The field or value concerned. Can be `null`."},"status_error_code":{"type":"integer","description":"PayMe error code. See the error table above and [Errors](/payments/getting-started/errors)."},"session":{"type":"string","description":"PayMe session ID. Quote it when you contact support."}}},"example":{"status_code":1,"status_error_details":"Invalid credit card expiry","status_additional_info":"1221f","status_error_code":356,"session":"a1B2c3D4"}}}}}}},"/sales/{payme_sale_id}/3ds/{hash_3dsecure}":{"get":{"security":[{"merchantKey":[]}],"operationId":"get-sales-payme-sale-id-3ds-hash","summary":"Resolve a 3D Secure hash","tags":["Standalone 3D Secure service"],"description":"## Overview\n\nDecodes the `hash_3dsecure` from [Start 3D Secure authentication](/payments/standalone-3d-secure-service/post-initialize-3dsecure-request), or from the challenge page, into the 3DS values to send to your gateway: `eci`, `cavv` and `xid`. Call it from your server: the `PayMe-Merchant-Key` header carries the seller's MPL, which must stay secret. The whole flow: [Standalone 3D Secure: process flow](/payments/standalone-3d-secure-service).\n\nIf authentication failed, the result has a non-null `status`, no `cavv`, and `status_code` `1`.\n\n","parameters":[{"name":"payme_sale_id","in":"path","required":true,"description":"Our unique sale ID. ","schema":{"type":"string"}},{"name":"hash_3dsecure","in":"path","required":true,"description":"The secured hash sent from PayMe (`hash_3dsecure`).  ","schema":{"type":"string"}},{"name":"PayMe-Merchant-Key","in":"header","required":true,"description":"The MPL of the seller. ","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"xid":{"type":"string","description":"The XID generated by the credit card issuer."},"eci":{"type":"string","description":"The ECI generated by the credit card issuer."},"cavv":{"type":"string","description":"The CAVV generated by the credit card issuer."},"version":{"type":"string","description":"The 3D Secure version used."},"mid":{"type":"string","description":"The MID, when there is one."},"status":{"type":"string","description":"`null` when authentication succeeded. Otherwise the failure status."},"payParameters":{"type":"object","description":"Payment parameters stored with the authentication, such as `installments`. An empty array (`[]`) when there are none."},"status_code":{"type":"integer","description":"`0` when `status` is `null`, otherwise `1`."}}},"example":{"xid":"XXXXXXXXXXXXXXXXXXXXXXXXXXXX","eci":"05","cavv":"XXXXXXXXXXXXXXXXXXXXXXXXXXXX","version":"2.2.0","mid":null,"status":null,"payParameters":[],"status_code":0}}}},"400":{"description":"The hash could not be read. Codes: 1, 20.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1` on failure."},"status_error_details":{"type":"string","description":"What went wrong."},"status_additional_info":{"type":"string","description":"The field or value concerned; can be `null`."},"status_error_code":{"type":"integer","description":"PayMe error code."},"session":{"type":"string","description":"PayMe session ID."}}},"example":{"status_code":1,"status_error_details":"Validation error","status_additional_info":"eyJpdiI6Ilp...","status_error_code":20,"session":"a1B2c3D4"}}}},"401":{"description":"The `PayMe-Merchant-Key` header is missing (the body is then only `{\"error\": \"Unauthenticated.\"}`), or the seller or its partner is unknown or inactive. Codes: 163, 200, 201, 251.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1` on failure."},"status_error_details":{"type":"string","description":"What went wrong."},"status_additional_info":{"type":"string","description":"The field or value concerned; can be `null`."},"status_error_code":{"type":"integer","description":"PayMe error code."},"session":{"type":"string","description":"PayMe session ID."}}},"example":{"status_code":1,"status_error_details":"Seller was not found","status_additional_info":"seller_payme_id","status_error_code":251,"session":"a1B2c3D4"}}}},"403":{"description":"The sale does not belong to this seller, or the hash belongs to another sale. Code: 303.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1` on failure."},"status_error_details":{"type":"string","description":"What went wrong."},"status_additional_info":{"type":"string","description":"The field or value concerned; can be `null`."},"status_error_code":{"type":"integer","description":"PayMe error code."},"session":{"type":"string","description":"PayMe session ID."}}},"example":{"status_code":1,"status_error_details":"Could not access sale","status_additional_info":null,"status_error_code":303,"session":"a1B2c3D4"}}}},"404":{"description":"No sale has this ID. Code: 350.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"status_code":{"type":"integer","description":"`1` on failure."},"status_error_details":{"type":"string","description":"What went wrong."},"status_additional_info":{"type":"string","description":"The field or value concerned; can be `null`."},"status_error_code":{"type":"integer","description":"PayMe error code."},"session":{"type":"string","description":"PayMe session ID."}}},"example":{"status_code":1,"status_error_details":"Sale was not found","status_additional_info":"SALEDEMO-SALEDEMO-SALEDEMO-1234567","status_error_code":350,"session":"a1B2c3D4"}}}}}}}}}