{ "openapi": "3.0.0", "info": { "title": "Giftcard Hub API", "description": ">ℹ️ Check the [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview) for a journey-based overview of the Payments documentation available in the Developer Portal.\r\n\r\nThe Gift Card Hub API allows interactions with all Gift card providers registered to a store from a single point.\r\n\r\nGift card providers are systems capable of providing cards to be used in the buying process.\r\n\r\nThe following is the sequence diagram that represents calls in the purchase closing process.\r\n![](https:\/\/cdn.jsdelivr.net\/gh\/vtexdocs\/dev-portal-content@main\/images\/gift-card-integration-guide-provider-protocol-0.png)\r\n\r\n**Checkout + Gateway**: Systems responsible for the sale and for processing orders and payments.\r\n\r\n**Gift Card Hub**: System responsible for managing multiple registered Gift card providers for a store.\r\n\r\n**Gift Card Provider**: System responsible for providing the Gift cards available to the user not closing a purchase. This system can be implemented by third parties.", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/giftcardproviders": { "get": { "tags": [ "Provider" ], "summary": "List all gift card providers", "description": "Returns a collection of gift card providers from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardProviders", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "REST-Range", "in": "header", "description": "Pagination control. This query variable must follow the format `_resources={from}-{to}_`.", "required": false, "style": "simple", "schema": { "type": "string", "default": "resources=0-49" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Gift card providers information.", "properties": { "id": { "type": "string", "description": "Gift card provider identification." }, "serviceUrl": { "type": "string", "description": "URL from the provider." }, "oauthProvider": { "type": "string", "description": "Provider's authentication." }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider." }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": [ { "id": "GiftCardExample", "serviceUrl": "https://api.vtex.com.br/basedevmkp", "oauthProvider": "vtex", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample" } }, { "id": "GiftCardExample2", "serviceUrl": "https://giftcard--cosmetics2.myvtex.com/my-provider", "oauthProvider": "vtex", "caption": "My Updated Gift Card Provider", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample2" } } ] } } } } } }, "/api/giftcardproviders/{giftCardProviderId}": { "get": { "tags": [ "Provider" ], "summary": "Get a gift card provider by ID", "description": "Returns a gift card provider from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card provider identification." }, "serviceUrl": { "type": "string", "description": "URL from the provider." }, "oauthProvider": { "type": "string", "description": "Provider's authentication." }, "caption": { "type": "string", "description": "Description about the provider." }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider." }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "items": { "type": "object", "description": "Provider route information.", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": { "id": "GiftCardExample", "serviceUrl": "https://api.vtex.com.br/basedevmkp", "oauthProvider": "vtex", "caption": "My Updated Gift Card Provider", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample" } } } } }, "500": { "description": "Object reference not set to an instance of an object (The gift card provider described does not exist)." } } }, "put": { "tags": [ "Provider" ], "summary": "Create or update a gift card provider by ID", "description": "Create or update a gift card provider from a store.\r\n\r\n> ⚠️ The `X-PROVIDER-API-AppKey` and `X-PROVIDER-API-AppToken` headers are not mandatory for the native VTEX gift card, only for [external gift card providers](https://developers.vtex.com/updates/release-notes/2024-05-27-changes-in-authentication-requirements-for-external-gift-card-providers).\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Create/UpdateGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "customProvider" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateUpdateGiftCardProviderbyIDRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card provider identification." }, "serviceUrl": { "type": "string", "description": "URL from the provider." }, "oauthProvider": { "type": "string", "description": "Provider's authentication." }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider." }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "items": { "type": "object", "description": "Provider route information.", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": { "id": "customProvider", "serviceUrl": "https://api.vtex.com.br/basedevmkp", "oauthProvider": "vtex", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmetics2/giftcardproviders/customprovider" } } } } } } }, "delete": { "tags": [ "Provider" ], "summary": "Delete a gift card provider by ID", "description": "Delete a gift card provider from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "DeleteGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "responses": { "200": { "description": "OK. This endpoint does not return any data in the response body." }, "404": { "description": "Not Found" } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards": { "post": { "tags": [ "Transaction" ], "summary": "Create a gift card at a gift card provider", "description": "Creates a gift card in a gift card provider.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardinGiftCardProvider", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardinGiftCardProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "emissionDate": { "type": "string", "description": "Gift card emission date." }, "expiringDate": { "type": "string", "description": "Gift card expiration date." }, "caption": { "type": "string", "description": "Field to be filled in if a loyalty program must be created for the gift card." }, "provider": { "type": "string", "description": "Provider name." }, "discount": { "type": "boolean", "description": "Deprecated field.", "deprecated" : true }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." }, "transaction": { "type": "object", "description": "Transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The number described in the URL refers to the gift card identification." } } } } }, "example": { "id": "38", "emissionDate": "2023-06-27T17:02:19.17", "expiringDate": "2023-09-27T17:02:19.17", "caption": "Loyalty Program", "provider": "GiftCardExample", "discount": false, "currencyCode":"USD", "transactions": { "href": "cosmetics2/giftcardproviders/GiftCardExample/giftcards/38/transactions" } } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/_search": { "post": { "tags": [ "Transaction" ], "summary": "Get a gift card from a gift card provider", "description": "Returns all gift cards from a gift card provider according to the filters.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardfromGiftCardProvider", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "REST-Range", "in": "header", "description": "Pagination control. This query variable must follow the format `_resources={from}-{to}_`.", "required": false, "style": "simple", "schema": { "type": "string", "default": "resources=0-49" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/GetGiftCardfromGiftCardProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Gift card information.", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "provider": { "type": "string", "description": "Gift card provider name." }, "balance": { "type": "number", "description": "Gift card current balance." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": [ { "id": "262498", "provider": "GiftCardExample", "balance": 45.50, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample/giftcards/262498" } } ] } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}": { "get": { "tags": [ "Transaction" ], "summary": "Get a gift card from a gift card provider by ID", "description": "Returns a specific gift card from a gift card provider.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardfromGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "5" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "redemptionToken": { "type": "string", "description": "Gift card redemption token." }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters." }, "balance": { "type": "number", "description": "Gift card current balance. For newly created gift cards, the balance will be 0.0." }, "emissionDate": { "type": "string", "description": "Gift card emission date." }, "expiringDate": { "type": "string", "description": "Gift card expiration date." }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." }, "discount": { "type": "boolean", "description": "Deprecated field.", "deprecated" : true }, "transactions": { "type": "object", "description": "Transactions information.", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } }, "example": { "id": "5", "redemptionToken": "32ScL57220Vapb8pc50HJ3mWH1cl1L8x", "redemptionCode": "***********ASDQ", "balance": 870.0, "emissionDate": "2014-04-24T20:22:58.163", "expiringDate": "2016-01-01T00:00:00", "currencyCode":"USD", "discount": false, "transactions": { "href": "cards/954/transactions" } } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions": { "get": { "tags": [ "Transaction" ], "summary": "List all gift card transactions", "description": "Returns the IDs of all transactions performed on a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardTransactions", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Transaction information.", "properties": { "cardId": { "type": "string", "description": "Gift card identification." }, "id": { "type": "string", "description": "Transaction identification." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": [ { "cardId": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70", "id": "jac68316306453f4b8tr3fdb892dfba1", "_self": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1" } }, { "cardId": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70", "id": "g4a348e1d1f146ba25e19bb016cc6f18", "_self": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/g4a348e1d1f146ba25e19bb016cc6f18" } } ] } } } } }, "post": { "tags": [ "Transaction" ], "summary": "Create a gift card transaction", "description": "Creates a transaction (credit or debit) to a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardTransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "Gift card identification." }, "id": { "type": "string", "description": "Transaction identification." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } }, "example": { "cardId": "24", "id": "68347b311ce5407c90fa5316975d047a", "_self": { "href": "gatewayqa/giftcards/24/transactions/68347b311ce5407c90fa5316975d047a" } } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{transactionId}": { "get": { "tags": [ "Transaction" ], "summary": "Get a gift card transaction by ID", "description": "Returns a specific transaction from a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardTransactionbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "number", "description": "Transaction value." }, "description": { "type": "string", "description": "Transaction description." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." }, "requestId": { "type": "string", "description": "VTEX request identifier." }, "settlement": { "type": "object", "description": "Settlement transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification." } } }, "cancellation": { "type": "object", "description": "Cancellation transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification." } } }, "authorization": { "type": "object", "description": "Authorization transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification." } } }, "operation": { "type": "string", "description": "Operation information (`Credit` or `Debit`)." } } }, "example": { "value": 140.0, "description": "GiftCardHub", "date": "2023-06-02T18:24:49.252855Z", "requestId": "3", "settlement": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1/settlements" }, "cancellation": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1/cancellations" }, "authorization": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1/authorization" }, "operation": "Credit" } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/authorization": { "get": { "tags": [ "Transaction" ], "summary": "Get a gift card transaction authorization", "description": "Returns information about a gift card transaction authorization. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardAuthorizationTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "object", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } }, "example": { "oid": "faa6831230634c4b8fb897e02ba9c5a1", "value": 140.0, "date": "2023-06-02T18:24:49.252855Z" } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/settlements": { "get": { "tags": [ "Transaction" ], "summary": "List all gift card transactions settlements", "description": "Returns all transactions settlements for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardSettlementTransactions", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "array", "items": { "type": "object", "description": "Transaction information.", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } } }, "example": [ { "oid": "faa6831230634c4b8fb897e02ba9c5a1", "value": 15.0, "date": "2023-06-02T18:24:49.252855Z" }, { "oid": "hbar6832580652c4b8fb653f15ba9c5a7", "value": 40.0, "date": "2023-06-04T15:00:35.252855Z" } ] } } } } }, "post": { "tags": [ "Transaction" ], "summary": "Settle a gift card transaction", "description": "Creates a transaction settlement for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardSettlementTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "value", "requestId" ], "properties": { "value": { "type": "number", "description": "Transaction value.", "example": 1.8 }, "requestId": { "type": "string", "description": "Request identification of the transaction.", "example": "12093812masoidj120398" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "oid", "value", "date" ], "type": "object", "description": "Transaction information.", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date information." } } } }, "example": [ { "oid": "e122ebd4501a4b3b93640b7444ac425d", "value": 1.8, "date": "2019-03-18T14:42:32.1291783Z" } ] } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/cancellations": { "get": { "tags": [ "Transaction" ], "summary": "List all gift card transactions cancellations", "description": "Returns all transactions cancelled for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardCancellationTransactions", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "array", "items": { "type": "object", "description": "Transaction information.", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } } }, "example": [ { "oid": "1248f9b9d4564792b64013bba27151f2", "value": 30.0, "date": "2023-06-02T18:24:49.252855Z" }, { "oid": "8cb71c9e893A67E1b94d9b2ba15d102F", "value": 5.0, "date": "2023-06-08T11:30:00.252855Z" } ] } } } } }, "post": { "tags": [ "Transaction" ], "summary": "Cancel a gift card transaction", "description": "Creates a cancellation transaction to a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardCancellationTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardCancellationTransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "object", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } }, "example": { "oid": "7582d93baccc44e9867b0b861696fc0a", "value": 4.1, "date": "2019-03-19T14:35:16.7157238Z" } } } } } } } }, "components": { "schemas": { "CreateUpdateGiftCardProviderbyIDRequest": { "required": [ "serviceUrl", "oauthProvider", "preAuthEnabled", "cancelEnabled", "appKey", "appToken" ], "type": "object", "description": "Gift card provider information.", "properties": { "id": { "type": "string", "description": "Gift card provider identification. This value must be the same as the one sent in the path parameter (`giftCardProviderId`).", "example": "customProvider" }, "serviceUrl": { "type": "string", "description": "URL from the provider.", "example": "https://api.vtex.com.br/example" }, "oauthProvider": { "type": "string", "description": "Provider's authentication.", "example": "vtex" }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider.", "example": true }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider.", "example": true }, "appKey": { "type": "string", "description": "Credential provided by the merchant that VTEX will use for identification.", "example": "key" }, "appToken": { "type": "string", "description": "Credential provided by the merchant that VTEX will use for identification.", "example": "token" } } }, "CreateGiftCardinGiftCardProviderRequest": { "required": [ "relationName", "emissionDate", "expiringDate", "caption", "restrictedToOwner", "multipleRedemptions", "multipleCredits", "profileId" ], "type": "object", "description": "Gift card provider information.", "properties": { "relationName": { "type": "string", "description": "Represents the relationship between the client and the store.", "example": "loyalty-program" }, "emissionDate": { "type": "string", "description": "Gift card emission date. It must be in the format `YYYY-MM-DDThh:mm:ss.fff` (ISO 8601 format).", "example": "2020-09-01T13:15:30Z" }, "expiringDate": { "type": "string", "description": "Gift card expiration date. It must be in the format `YYYY-MM-DDThh:mm:ss.fff` (ISO 8601 format).", "example": "2020-09-10T13:15:30Z" }, "caption": { "type": "string", "description": "Field to be filled in if a loyalty program must be created for the gift card.", "example": "Loyalty Program" }, "restrictedToOwner": { "type": "boolean", "description": "The gift card can only be used for a specified client's ID.", "example": false }, "multipleRedemptions": { "type": "boolean", "description": "The gift card can be used to make new purchases until its value is completely used.", "example": false }, "multipleCredits": { "type": "boolean", "description": "The gift card balance can be changed.", "example": false }, "profileId": { "type": "string", "description": "Client ID. You can use the customer's registered email or the `userId` parameter which can be found in the [Master Data](https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw).", "example": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff" }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217.", "example": "USD" } } }, "GetGiftCardfromGiftCardProviderRequest": { "required": [ "client", "cart" ], "type": "object", "description": "Gift card provider information.", "properties": { "client": { "$ref": "#/components/schemas/Client" }, "cart": { "$ref": "#/components/schemas/Cart" } } }, "Client": { "type": "object", "description": "Client information.", "properties": { "id": { "type": "string", "description": "Customer's identification.", "example": "3b1abc17-988e-4a14-8b7f-31fc6a5b955c" }, "email": { "type": "string", "description": "Customer's email address.", "example": "email@domain.com" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "42151783120" } } }, "Cart": { "type": "object", "description": "Cart information.", "properties": { "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 0 }, "relationName": { "type": "string", "description": "Represents the relationship between the client and the store.", "example": "loyalty-program" }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters.", "example": "***********ASDQ" }, "discounts": { "type": "integer", "description": "Discounts value.", "example": 20 }, "shipping": { "type": "integer", "description": "Shipping value.", "example": 2 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "description": "Items information." }, "itemsTotal": { "type": "integer", "description": "Total items value.", "example": 200 } } }, "Item": { "type": "object", "description": "Items information.", "properties": { "productId": { "type": "string", "description": "Product ID.", "example": "2000000" }, "id": { "type": "string", "description": "The ID of the SKU in VTEX platform.", "example": "2000002" }, "refId": { "type": "string", "description": "Product Reference ID.", "example": "MEV41" }, "name": { "type": "string", "description": "Product name.", "example": "Shoes" }, "price": { "type": "integer", "description": "Product price.", "example": 200 }, "quantity": { "type": "integer", "description": "Product quantity.", "example": 1 } } }, "CreateGiftCardTransactionRequest": { "required": [ "operation", "value", "description", "redemptionToken", "redemptionCode", "requestId", "orderInfo" ], "type": "object", "description": "Transaction information.", "properties": { "operation": { "type": "string", "description": "Type of operation. Possible values are: `Debit` or `Credit`.", "example": "Debit" }, "value": { "type": "number", "format": "decimal", "description": "Operation value.", "example": 3 }, "description": { "type": "string", "description": "Description information.", "example": "GiftCardHub" }, "redemptionToken": { "type": "string", "description": "Gift card redemption token.", "example": "b2dac6f2-f365-48cd-82a9-0b376a55557a" }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters.", "example": "***********ASDQ" }, "requestId": { "type": "string", "description": "Request identification of the transaction. You need to send a different `requestId` value every time you make a new transaction. If you send the same `requestId`two or more times with a specific `redemptionCode`or `redemptionToken`, the gift card balance will not be updated.", "example": "B56CBE231DEE4E1A859183C1030CE926" }, "orderInfo": { "$ref": "#/components/schemas/OrderInfo" } } }, "OrderInfo": { "type": "object", "description": "Order information.", "properties": { "orderId": { "type": "string", "description": "Order ID.", "example": "v5006128str" }, "sequence": { "type": "integer", "description": "Sequence number.", "example": 5006128 }, "cart": { "$ref": "#/components/schemas/Cart1" }, "clientProfile": { "$ref": "#/components/schemas/ClientProfile" }, "shipping": { "$ref": "#/components/schemas/Shipping" } } }, "Cart1": { "type": "object", "description": "Cart information.", "required": [ "items", "grandTotal", "discounts", "shipping", "taxes", "itemsTotal" ], "properties": { "items": { "type": "array", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item1" } }, "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 0 }, "discounts": { "type": "number", "description": "Discounts value.", "example":-7.5 }, "shipping": { "type": "number", "description": "Shipping value.", "example": 7.27 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "itemsTotal": { "type": "number", "description": "Total items value.", "example": 14.99 } } }, "Item1": { "type": "object", "description": "Items information.", "required": [ "id", "productId", "refId", "name", "value", "price", "quantity", "shippingDiscount", "discount", "priceTags" ], "properties": { "id": { "type": "string", "description": "SKU ID.", "example": "2001023" }, "productId": { "type": "string", "description": "Product ID.", "example": "2000492" }, "refId": { "type": "string", "description": "Product Reference ID.", "example": "35994" }, "name": { "type": "string", "description": "Product name.", "example": "Vaporizador Des. ColC4nia Branco" }, "value": { "type": "number", "description": "Product value.", "example": 14.99 }, "price": { "type": "number", "description": "Product price.", "example": 14.99 }, "quantity": { "type": "integer", "description": "Product quantity.", "example": 1 }, "shippingDiscount": { "type": "integer", "description": "Discount to be applied for the shipping value.", "example": 0 }, "discount": { "type": "number", "description": "Discount applied on item.", "example": -7.5 }, "priceTags": { "type": "object", "description": "Array of price tags, each of which modifies the price in some way, like discounts or rates that apply to the item in the context of the order.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Price tag name.", "example": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c" }, "value": { "type": "integer", "description": "Price tag value.", "example": 0 } } } } }, "ClientProfile": { "type": "object", "description": "Client profile information.", "required": [ "email", "firstName", "lastName", "document", "phone", "birthDate", "isCorporate" ], "properties": { "email": { "type": "string", "description": "Customer's email address.", "example": "michael.scott96@mail.com" }, "firstName": { "type": "string", "description": "Customer's first name.", "example": "Michael" }, "lastName": { "type": "string", "description": "Customer's last name.", "example": "Scott" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "02906792063" }, "phone": { "type": "string", "description": "Customer's phone number.", "example": "+551111111111" }, "birthDate": { "type": "string", "description": "Customer's birth date.", "example": "0001-01-01T00:00:00" }, "isCorporate": { "type": "boolean", "description": "Defines if the customer is a company (`true`) or not (`false`).", "example": false } } }, "Shipping": { "type": "object", "description": "Shipping information.", "required": [ "receiverName", "postalCode", "city", "state", "country", "street", "number", "neighborhood", "complement", "reference" ], "properties": { "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order.", "example": "Michael Scott" }, "postalCode": { "type": "string", "description": "Postal code.", "example": "22250040" }, "city": { "type": "string", "description": "City of the shipping address.", "example": "Rio de Janeiro" }, "state": { "type": "string", "description": "State of the shipping address.", "example": "RJ" }, "country": { "type": "string", "description": "Country of the shipping address.", "example": "BRA" }, "street": { "type": "string", "description": "Street of the shipping address.", "example": "Praia de Botafogo" }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address.", "example": "111" }, "neighborhood": { "type": "string", "description": "Neighborhood of the address.", "example": "Botafogo" }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies.", "example": "House", "nullable": true }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery.", "example": "Subway", "nullable": true } } }, "CreateGiftCardSettlementTransactionRequest": { "type": "object", "description": "Gift card provider information.", "required": [ "client", "cart" ], "properties": { "client": { "$ref": "#/components/schemas/Client" }, "cart": { "$ref": "#/components/schemas/Cart2" } } }, "Cart2": { "type": "object", "description": "Cart information.", "required": [ "grandTotal", "relationName", "redemptionCode", "discounts", "shipping", "taxes", "items", "itemsTotal" ], "properties": { "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 182 }, "relationName": { "type": "string", "nullable": true, "description": "Represents the relationship between the client and the store.", "example": null }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters.", "example": "FASD-ASDS-ASDA-ASDA" }, "discounts": { "type": "integer", "description": "Discounts value.", "example": -20 }, "shipping": { "type": "integer", "description": "Shipping value.", "example": 2 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "items": { "type": "array", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item" } }, "itemsTotal": { "type": "integer", "description": "Total items value.", "example": 200 } } }, "CreateGiftCardCancellationTransactionRequest": { "type": "object", "description": "Transaction information.", "required": [ "value", "requestId" ], "properties": { "value": { "type": "number", "description": "Transaction value.", "example": 4.1 }, "requestId": { "type": "string", "description": "Request identification of the transaction.", "example": "12093812masoidj120398" } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } } }, "tags": [ { "name": "Provider" }, { "name": "Transaction" } ], "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ] }