{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"6fec7a74-35e3-4c60-af0b-6f4a8ecb6d6c","name":"Ncentiva API Reference","description":"Welcome to the Ncentiva API documentation. This API enables seamless integration with our platform to access various services related to account management, inventory, and order processing. Our team of specialists are always ready to answer your questions, feel free to reach out to us on [support@ncentiva.com](https://mailto:support@ncentiva.com). Below are key details to get you started:\n\n### Security\n\nOur API uses Basic Authentication to ensure secure access. To generate your API keys, log in to the Ncentiva portal, navigate to the \"API Keys\" tab, and generate your keys there. Use the generated keys for authentication in your API requests.\n\n**Example:**\n\n1. Generate API Keys: Log in to the [Ncentiva Portal](https://your-ncentiva-portal-url.com), go to the \"API Keys\" tab, and create new keys.\n    \n2. Construct Basic Auth: Combine your `username` and `password` in the format `username:password` and base64 encode this string.\n    \n3. Add Authorization Header: Include the encoded string in your request headers.\n    \n\n**Example Request Header:**\n\n```\nAuthorization: Basic <base64-encoded-credentials>\n\n ```\n\n### API Flow\n\nOur API follows an asynchronous flow to enhance performance and scalability. When you initiate an action, such as placing an order, the system processes the request in the background. You can check the status or retrieve results through subsequent API calls.\n\n#### Base URLs\n\n| **Environment** | **Base URL** |\n| --- | --- |\n| **UAT** | [https://api-uat.ncentiva.com/](https://api-uat.ncentiva.com/) |\n| **Production** | [https://api.ncentiva.com](https://api.ncentiva.com) |\n\n#### Pagination\n\nTo manage large data sets efficiently, our API supports pagination. When requesting lists, such as inventory or order history, the response includes pagination details with a maximum of `2000` records. Use the provided parameters to navigate through pages in the .\n\n**Example Parameters:**\n\n- `page`: Specifies the page number.\n    \n- `pageSize`: Sets the number of items per page.\n    \n\n#### Rate Limiting\n\nTo ensure fair usage and prevent abuse, our API enforces rate limits:\n\n- **Production Environment:**\n    \n    - 60 requests per minute.\n        \n    - Maximum of 2 requests per second.\n        \n- **UAT Environment:**\n    \n    - 20 requests per minute.\n        \n    - Maximum of 1 request per second.\n        \n\nExceeding these limits will result in rate-limiting responses, advising you to slow down your request rate.\n\n#### Example Request and Handling Rate Limits\n\nWhen making API requests, ensure your application adheres to the rate limits. Handle rate-limiting responses by implementing retry logic with exponential backoff to avoid overwhelming the server.\n\n``` javascript\nfunction makeApiRequest() {\n    // Perform API request\n    // Check for rate limit response\n    if (response.status === 429) {\n        // Implement retry logic\n        setTimeout(makeApiRequest, retryInterval);\n    } else {\n        // Handle successful response\n    }\n}\n\n ```\n\n### Dealing with bulk orders\n\nNcentiva's API allows you to manage your orders cart directly via API. Below is a graphical reprensentation for the orders sequence:\n\n<img src=\"https://content.pstmn.io/944e55a4-c76e-4a4d-9560-336ca71e9970/Q2FydEZsb3cuanBn\">\n\n#### Request Body Parameters\n\n| Name | Type | Required | Description |\n| --- | --- | --- | --- |\n| `giftCardTypeId` | integer | Yes | Identifier for the type of gift card to be purchased. |\n| `amount` | integer | Yes | The monetary value of the gift card. |\n| `quantity` | integer | Yes | The requested quantity of this particular gift card. |\n| `orderReference` | string | No | Optional reference provided by the client for tracking. |\n\n### Individual Order Creation\n\nThis endpoint facilitates the asynchronous creation of individual orders for gift cards. Clients initiate an order by specifying the type and amount of the gift card they wish to purchase. Due to the asynchronous nature of this endpoint, clients will receive a transaction identifier in the response, which they can use to check the status of the order through a separate endpoint.\n\n#### Request Body Parameters\n\n| Name | Type | Required | Description |\n| --- | --- | --- | --- |\n| `giftCardTypeId` | integer | Yes | Identifier for the type of gift card to be purchased. |\n| `amount` | integer | Yes | The monetary value of the gift card. |\n| `orderReference` | string | No | Optional reference provided by the client for tracking. |\n\n#### Asynchronous Operation\n\nAfter submitting the order, the response will include a parameter `name` that contains the transaction identifier (e.g., `NCT-PO-P-099623`). This ID should be used to check the order status via the following endpoint:\n\n``` bash\ncurl --location 'https://w1xwrf4bfa.execute-api.us-east-2.amazonaws.com/uat/api/purchasers/v1/orders/{transaction_id}' \\\n--header 'Authorization: YOUR_BASIC_AUTH'\n\n ```\n\n##### Order Fulfillment Sequence\n\n<img src=\"https://content.pstmn.io/6d2377ae-ff3f-4cfb-b704-aa0ab2670ad6/SW5kaXZpZHVhbE9yZGVyRmxvdzIuanBn\">\n\nIn the case of network timeout, or if for any reason, Ncentiva's order reference wasn't captured by your application, **you can use the Get Order by customerReference endpoint to retrieve the order using your own generated unique reference** (customerReference). Always make sure that you pass this parameter as a unique combination to avoid failures in the case of duplicate references.\n\n#### HTTP Error codes\n\n| HTTP Error Code | Message | Description |\n| --- | --- | --- |\n| **200** | OK | Successful request. The requested information has been returned in the response. |\n| **400** | Bad Request | The server cannot process the request due to a client error. This code is used to ensure the request is proper and to enforce proper data validation. |\n| **401** | Unauthorized | The request requires user authentication. The client must provide valid authentication credentials for the target resource. |\n| **403** | Forbidden | The server understood the request but refuses to authorize it. The client does not have the necessary permissions to access the resource. |\n| **404** | Not Found | The server cannot find the requested resource. This code indicates that the requested data is not found in the database. |\n| **500** | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. |\n| **502** | Bad Gateway | The server, while acting as a gateway or proxy, received an invalid response from the upstream server. |\n| **504** | Gateway Timeout | The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server. |\n\n#### Application error codes and messages (examples)\n\n| Error Code | **Error Message** |\n| --- | --- |\n| **BAD_REQUEST** | Our site is currently on maintenance. You can resume your order after 10 minutes! |\n| **BAD_REQUEST** | Gift Card Type with ID 1234 not found |\n| **BAD_REQUEST** | Card value not match. CardType value should be 5.00 |\n| **NOT_FOUND** | Purchase Order not found |\n| **NOT_FOUND** | Data not found |\n| **NOT_FOUND** | Data is not available for the given order |\n\n#### API Order Statuses\n\n| Status | **Description** |\n| --- | --- |\n| **Open** | The initial status when the order is placed |\n| **Cancelled** | Order is cancelled by Ncentiva.  <br>_After receiving this status, you can_ _**retry**_ _the order, or_ _**refund**_ _your customer._ |\n| **Completed** | Order is completed, you can proceed to retrieve the gift card codes. |\n| **Processing** | The order is in progress to be completed. |\n| **API Low Fund** | The order is on hold due to low funds on the account.  <br>_Please reach out to our team in case your account is running out of funds to decide on the next step, whether to cancel the orders or process them once funds are added._ |\n| **On hold** | The order is on hold from Ncentiva side.  <br>_Please reach out to our team in case your account is running out of funds to decide on the next step, whether to cancel the orders or process them once funds are added._ |\n| **Temporary Out Of Stock** | The requested product is temporary out of stock and should be restocked shortly.  <br>_After receiving this status, you can_ _**retry**_ _the order, or_ _**refund**_ _your customer._ |\n\nBy following these guidelines, you can effectively utilize the Ncentiva API to integrate with our services and build robust applications.\n\nFor detailed endpoint descriptions, please refer to the specific sections in this documentation.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"38333563","team":6448726,"collectionId":"6fec7a74-35e3-4c60-af0b-6f4a8ecb6d6c","publishedId":"2sAXqqc2oo","public":true,"publicUrl":"https://docs.ncentiva.com","privateUrl":"https://go.postman.co/documentation/38333563-6fec7a74-35e3-4c60-af0b-6f4a8ecb6d6c","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2665F2"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"Ncentiva API Documentation: Comprehensive guide for integrating with the Ncentiva API. Learn how to authenticate, retrieve inventory, place orders, and handle asynchronous operations securely. Includes best practices, examples, and error handling techniques for seamless integration."},{"name":"title","value":"Ncentiva API Documentation - Integrate Gift Cards - Prepaid Cards Orders Processing"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/64c483ba-56cf-452b-b2d6-5e727a35cc88/bmNlbnRpdmFfbG9nb19jb2xvci5wbmc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"2665F2"}},{"name":"light","logo":"https://content.pstmn.io/ba0cb8fa-95e3-4da3-a9c4-167736b0423e/bmNlbnRpdmFfbG9nb19jb2xvcl9kYXJrICgyKS5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2665F2"}}]}},"version":"8.10.1","publishDate":"2025-01-02T08:56:48.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"Ncentiva API Documentation - Integrate Gift Cards - Prepaid Cards Orders Processing","description":"Ncentiva API Documentation: Comprehensive guide for integrating with the Ncentiva API. Learn how to authenticate, retrieve inventory, place orders, and handle asynchronous operations securely. Includes best practices, examples, and error handling techniques for seamless integration."},"logos":{"logoLight":"https://content.pstmn.io/ba0cb8fa-95e3-4da3-a9c4-167736b0423e/bmNlbnRpdmFfbG9nb19jb2xvcl9kYXJrICgyKS5wbmc=","logoDark":"https://content.pstmn.io/64c483ba-56cf-452b-b2d6-5e727a35cc88/bmNlbnRpdmFfbG9nb19jb2xvci5wbmc="}},"statusCode":200},"environments":[],"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/36f334aa1475e3faa309aa4af59f53c12df1532bd9a52540e242f01d2e9f6898","favicon":"https://ncentiva.com/favicon.ico"},"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"}],"canonicalUrl":"https://docs.ncentiva.com/view/metadata/2sAXqqc2oo"}