{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"fe253388-c1ee-42b1-ae44-5ab0bc8f7d1a","name":"Beta - Universal Token Transaction API","description":"Related documentation: [How to use TokenEx Universal Tokens](https://documentation.ixopay.com/docs/recipes/how-to/use-tokenex-universal-tokens)\n\nThis collection outlines and provides examples for utilizing Universal Tokens with IXOPAY's adapter catalog so that a merchant can seamlessly manage their payment orchestration without needing access to raw PCI card or sensitive data.\n\nThis functionality provides the merchant the following features\n\n- Complete access to IXOPAY's adapter catalog\n    \n- Ability to detokenize Universal Tokens and forward associated CVVs to the IXOPAY adapters.\n    \n\nPrerequisites for this functionality are\n\n- Existing Universal Token vault\n    \n    - An API Key that has the Payment Services All Access permission\n        \n- Existing IXOPAY Connector or Meta-Connector\n    \n    - At least one user\n        \n\n### Key Terms\n\n|  | **Definition** |\n| --- | --- |\n| Connector | A merchant-specific connection to an adapter - configured in the IXOPAY portal. |\n| Meta-Connector or Multi-Method-Connector | A merchant-specific connection to a series of adapters with transaction routing rules |\n| adapter | A pre-made technical integration to a Payment Service Provider (PSP). |\n| (Payment) Method | The type of transaction to be processed through the adapter. For example, Credit Cards, ACH, SEPA, Google Pay, etc. |\n\n# Getting Started\n\nTo use this Postman collection, please populate the collection-level variables (when viewed in Postman, indicated by a green dot) and the respective environment variables. Following the population of those variables, see the request examples and modify according to your use-case. See Postman Variables section below.\n\nThe _Universal Token Utility_ folder contains three requests that can be used for managing tokens within this collection. Running a _Tokenize_ or _Tokenize & Associate CVV_ request will populate the UniversalToken variable. The _Delete_ request will delete the token contained in the UniversalToken variable and reset the variable value.\n\n**Note**: by default, a Universal Token's associated CVV will be deleted after the first usage. See `tx-cache-cvv` and `tx-cvv-not-required` headers below for more information.\n\n# Postman Variables\n\nThe variables below are used throughout this collection. Understanding how they're used and/or generated will ease integration.\n\n| **Variable** | Location Used or Generated | Description |\n| --- | --- | --- |\n| PCI-ConnectorAPIKey | Endpoint path | Value obtained from connector settings in IXOPAY portal. This variable is used by requests in the PCI adapter methods folder. |\n| PCI-ConnectorSharedSecret | Request header | Value obtained from connector settings in IXOPAY portal. This variable is used by requests in the PCI adapter methods folder. |\n| Non-PCI-ConnectorAPIKey | Endpoint path | Value obtained from connector settings in IXOPAY portal. This variable is used by requests in the Non-PCI adapter methods folder. |\n| Non-PCI-ConnectorSharedSecret | Request header | Value obtained from connector settings in IXOPAY portal. This variable is used by requests in the Non-PCI adapter methods folder. |\n| MerchantUsername | Request Authorization header. Used in collection-level Authorization. | Value obtained from merchant users section of the IXOPAY protal. The user must be of type `api` rather than `web`. |\n| MerchantPassword | Request Authorization header. Used in collection-level Authorization. | Value obtained from merchant users section of the IXOPAY protal. The user must be of type `api` rather than `web`. |\n| tx-tokenex-id | Request header | Value obtained from TokenEx portal. This value is the numeric vault identifer. Can be assigned in the Environment variables. |\n| tx-apikey | Request header | Value obtained from the TokenEx portal, associated with the vault identifer. The API key must have the PaymentServices permission assigned and an IP or CIDR range defined. Can be assigned in the Environment variables. |\n| DateHeader | Request header. Generated by collection-level pre-request script. | Example: Mon, 10 Jun 2024 14:26:26 GMT.  <br>No interaction required. |\n| ReferenceUuidFromPreAuthorize | Request body. | This value is lifted from a Preauthorize response by a post-request script and made available for use by other requests.  <br>No interaction required. |\n| ReferenceUuidFromCaptureOrDebit | Request body | This value is lifted from a Capture or Debit response by a post-request script and made available for use by other requests.  <br>No interaction required. |\n| ReferenceUuidFromRegister | Request body | This value is lifted from a Register response by a post-request script and made available for use by other requests.  <br>No interaction required. |\n| AutoGeneratedUUID | Request body. | This auto-generated value is associated with the request body parameter merchantTransactionId, which must be unique for every request.  <br>No interaction required. |\n\n# Endpoints\n\nThere are two environments, one for Sandbox traffic and another for Production traffic. The Universal Token vaults are not shared between Sandbox and Production and the TokenExId and API key will change between environments.\n\nConnectors using an adapter that has a PCI payment method should use the endpoint for PCI transactions. All other other adapter payment methods should be routed through the Non-PCI transactions endpoint.\n\nWhen utilizing multiple payment methods via a meta-connector (multi-method connector), please note the following routing rules:\n\n- PCI Payment Methods\n    \n    - The meta-connector should be pointed at the PCI Transaction endpoint.\n        \n- Non-PCI Payment Methods\n    \n    - The meta-connector should be pointed at the Non-PCI Transaction endpoint.\n        \n- Mixed (PCI & Non-PCI) Payment Methods\n    \n    - The default connector of the meta-connector must be a PCI payment method\n        \n    - The meta-connector should be pointed at the PCI Transaction endpoint.\n        \n\nSandbox Environment: [https://test-paymentservices.tokenex.com/](https://test-paymentservices.tokenex.com/)\n\nProduction Environment: [https://paymentservices.tokenex.com/](https://paymentservices.tokenex.com/)\n\n| **PCI adapter Methods Endpoint** | **Non-PCI adapter Methods Endpoint** |\n| --- | --- |\n| {{Environment}}/transaction/pci/ConnectorAPIKey/transactionType | {{Environment}}/transaction/ConnectorAPIKey/transactionType |\n\n# Headers\n\nThe following headers are applicable to accessing the API and affect detokenize operations, cvv retrieval, and HTTP resilience.\n\n| **Header** | **Applicability** | **Description** |\n| --- | --- | --- |\n| tx-tokenex-id | Required | TokenExId of Universal Token Vault. |\n| tx-apikey | Required | API Key associated with the TokenExId. |\n| tx-passthrough | Optional | When true, bypasses detokenization and cvv retrieval. |\n| tx-cachecvv | Optional | See [https://docs.tokenex.com/docs/cvv-retention-retrieval](https://docs.tokenex.com/docs/cvv-retention-retrieval) |\n| tx-cvv-not-required | Optional | When true, does not error if a CVV is unable to be retrieved. |\n| tx-retry | Optional | See [https://docs.tokenex.com/docs/retries-and-3rd-party-apis](https://docs.tokenex.com/docs/retries-and-3rd-party-apis) |\n| tx-http-timeout | Optional | Value in seconds to wait for a response from the connector before timing out. |\n| tx-connector-shared-secret | Required | Shared secret of the connector. |\n| Authorization | Required | Basic auth of the connector username and password. See Authorization tab. |\n| Date | Required | See collection-level pre-request script for Javascript example. The format of this value is specified in RFC 7231. Example: `Mon, 01 Jan 2018 11:01:36 GMT` |\n| Content-Length | Required | Usually an auto-generated header. Excluding this header will cause the request to fail. |\n| X-Environment | Optional | Applicable only to the PCI endpoint.  <br>Value: \"Sandbox\". Include this header when the desired behavior is to route the request to a Sandbox connector from the Production envrionment. |\n\n# Body\n\nBuild the request body via the [Transaction API](https://documentation.ixopay.com/api/transaction/transaction-api) reference documentation. Please use the following Card Data element for Debit, Preauthorize, Register, and Payout transaction types.\n\n| **cardData** | **Type** | **Description** |\n| --- | --- | --- |\n| pan | string | Universal Token. See [Detokenization](#detokenization) |\n| cvv | string | See [Card Data CVV Retrieval](#card-data-cvv-retrieval) |\n| cardHolder | string | Name of cardholder |\n| expirationMonth | string | Card expiration month. 1 or 2 digits. Examples: 3, 12 |\n| expirationYear | string | Card expiration year. 4 digits. Example: 2030 |\n\n``` json\n{\n    \"cardData\": {\n        \"pan\": \"4111111111111111\",\n        \"cvv\": \"737\",\n        \"cardHolder\": \"Bobby Tables\",\n        \"expirationMonth\": \"3\",\n        \"expirationYear\": \"2030\"\n    },\n    // remainder of request parameters \n}\n\n ```\n\n# Detokenization\n\nWhen a request body contains `cardData.number` , `extraData.accNum` , or the `customer.paymentData.ibanData.iban` parameter and `tx-passthrough` header is false or omitted, a detokenize operation is performed on the value of the parameter. Populate the request parameter with the appropriate Universal Token to be detokenized.\n\nWhen `tx-passthrough` is true, no detokenization is attempted and the value is sent through unmodified.\n\n# Card Data CVV Retrieval\n\nWhen a CVV has been associated with a Universal Token, that CVV can be retrieved and forwarded. To attempt a retrieval, send any non-numeric or non-null value in the `cardData.cvv` request parameter. If there is a CVV associated with the Universal Token present in the `cardData.pan` request parameter, the non-numeric value will be replaced with the retrieved CVV.\n\nWhen a numeric value is presented as the CVV, retrieval is not attempted and the numeric value is forwarded unmodified.\n\nIf a CVV could not be retrieved, the API will return an error. To continue processing and avoid an error response in this situation, utilize the `tx-cvv-not-required` header with a value of true. Instead of erroring, the value specified in `cardData.cvv` request parameter will be forwarded unmodified.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"11766591","collectionId":"fe253388-c1ee-42b1-ae44-5ab0bc8f7d1a","publishedId":"2sA3e5dnbm","public":true,"publicUrl":"https://documenter-api.postman.tech/view/11766591/2sA3e5dnbm","privateUrl":"https://go.postman.co/documentation/11766591-fe253388-c1ee-42b1-ae44-5ab0bc8f7d1a","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/3f9c9147-cc45-4327-8583-2cf474f8490d/bG9nby1peG9wYXktaWNvbi1yZ2IucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":"https://content.pstmn.io/3f9c9147-cc45-4327-8583-2cf474f8490d/bG9nby1peG9wYXktaWNvbi1yZ2IucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-07-12T12:56:07.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/3f9c9147-cc45-4327-8583-2cf474f8490d/bG9nby1peG9wYXktaWNvbi1yZ2IucG5n","logoDark":"https://content.pstmn.io/3f9c9147-cc45-4327-8583-2cf474f8490d/bG9nby1peG9wYXktaWNvbi1yZ2IucG5n"}},"statusCode":200},"environments":[{"name":"Test","id":"d8e79a81-2ccb-47f0-865c-885263899b55","owner":"11766591","values":[{"key":"PaymentServices","value":"https://test-paymentservices.tokenex.com","enabled":true,"type":"default"},{"key":"TokenServicesApi","value":"https://test-api.tokenex.com/v2","enabled":true,"type":"default"},{"key":"DefaultTokenExId","value":"","enabled":true,"type":"default"},{"key":"DefaultApiKey","value":"","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Test","value":"11766591-d8e79a81-2ccb-47f0-865c-885263899b55"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sA3e5dnbm"}