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. Below are key details to get you started:
\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.
\nExample:
\nGenerate API Keys: Log in to the Ncentiva Portal, go to the \"API Keys\" tab, and create new keys.
\nConstruct Basic Auth: Combine your username and password in the format username:password and base64 encode this string.
Add Authorization Header: Include the encoded string in your request headers.
\nExample Request Header:
\nAuthorization: Basic <base64-encoded-credentials>\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.
\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 .
Example Parameters:
\npage: Specifies the page number.
pageSize: Sets the number of items per page.
To ensure fair usage and prevent abuse, our API enforces rate limits:
\nProduction Environment:
\n60 requests per minute.
\nMaximum of 2 requests per second.
\nUAT Environment:
\n20 requests per minute.
\nMaximum of 1 request per second.
\nExceeding these limits will result in rate-limiting responses, advising you to slow down your request rate.
\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.
\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\nNcentiva's API allows you to manage your orders cart directly via API. Below is a graphical reprensentation for the orders sequence:
\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.
\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:
curl --location 'https://w1xwrf4bfa.execute-api.us-east-2.amazonaws.com/uat/api/purchasers/v1/orders/{transaction_id}' \\\n--header 'Authorization: YOUR_BASIC_AUTH'\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.
\nBy following these guidelines, you can effectively utilize the Ncentiva API to integrate with our services and build robust applications.
\nFor detailed endpoint descriptions, please refer to the specific sections in this documentation.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"38333563","collectionId":"6fec7a74-35e3-4c60-af0b-6f4a8ecb6d6c","publishedId":"2sAXqqc2oo","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2665F2"},"publishDate":"2025-01-02T08:56:48.000Z"},"item":[{"name":"Get Balance - (to be deprecated)","id":"dd128d0b-1b20-438c-aa11-31a8ffab0ce5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"{{base_url}}/api/purchasers/v1/accounts/balances","description":"Retrieve the current balance of the purchaser's account.
\nFlow:
\nAuthentication: Use basic authentication with the provided username and password.
Request: Send a GET request to the endpoint.
\nResponse: If the request is successful, the response will include the account balance details.
\nRetrieve available cards inventory details for a specified brand.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a GET request with the brandName query parameter (e.g., Adidas). If the brand name is not passed in the query parameter then all the available catalog will be back.
Response: If the request is successful, the response will include the available card types for the specified brand.
\nPlace an individual order for a specific gift card type and amount.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a POST request with the order details in the body, including giftCardTypeId, amount, and orderReference.
Response: If the request is successful, the response will include the order details. The order ID will be extracted and stored in the collection variable orderRef.
Retrieve the current status of the purchaser's cart.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a GET request to the endpoint.
\nResponse: If the request is successful, the response will include the cart status details.
\nAdd an item to the purchaser's cart.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a POST request with the item details in the body, including giftCardTypeId, amount, quantity, and orderReference.
Response: If the request is successful, the response will confirm the item was added to the cart.
\nDelete a specific item from the purchaser's cart.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a DELETE request with the itemId in the path parameter.
Response: If the request is successful, the response will confirm the item was removed from the cart.
\nPlace a purchase order to submit the orders in cart.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a POST request to the endpoint. The request body will be empty.
\nResponse: If the request is successful, the response will include the purchase order details.
\nRetrieve the details of a specific order by its ID.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a GET request with the orderRef in the path parameter.
Response: If the request is successful, the response will include the order details.
\nRetrieve the details of a specific order using your own generated unique reference (customerReference).
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a GET request with the customerReference that was used in the API request.
Response: If the request is successful, the response will include the order details.
\nRetrieve the purchase gift card code by response order name.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a GET request with the order_name in the path parameter.
Response: If the request is successful, the response will include the gift card code details.
\nDownload the gift card codes for a specific order.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a GET request with the orderId in the path parameter.
Response: If the request is successful, the response will include the downloadable gift card codes.
\nRetrieve purchase orders placed within a specified date range.
Flow:
Authentication: Use basic authentication with the provided username and password.
Request: Send a GET request with the startDate and endDate in the path parameters.
Response: If the request is successful, the response will include the purchase orders within the specified date range.
\n