{ "openapi": "3.0.0", "info": { "title": "Giftcard Provider Protocol", "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 Provider Protocol** is a set of definitions to help you integrate your Gift Card API into VTEX platform. \r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications from this documentation and configure your provider in your store using [Gift Card Hub API](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#overview).", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{providerApiEndpoint}", "description": "Gift card provider endpoint URL.", "variables": { "providerApiEndpoint": { "description": "Gift card provider endpoint URL.", "default": "{providerApiEndpoint}" } } } ], "paths": { "/giftcards/_search": { "post": { "tags": [ "Gift Cards" ], "summary": "List all gift cards", "description": " Returns a list of all gift cards available from a gift card provider for a specific customer's cart.\r\n\r\nFor scenarios in which there is a gift card with no balance associated with the customer, the payment provider must choose one of the options below to display the information in the response body and implement it on the endpoint:\n\r\n\r- Response body returns the complete gift card data mentioning the balance field equal to 0 (`\"balance\": 0`): In this option, whenever the customer has associated a gift card without a balance, they will need to log in to the store to access the balance information.\n\r- The response body only returns an empty array (`[]`): The customer does not need to log in to the store to access balance information when they have a gift card with no balance associated with it.\n\r\n\r> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "ListAllGiftCards", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/vnd.vtex.giftcards.v1+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/vnd.vtex.giftcards.v1+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" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcards.v1+json": { "schema": { "$ref": "#/components/schemas/ListAllGiftCardsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/response" } }, "example": [ { "id": "3ad63br54-988e-4a14-8b7f-31fc6a5b955c_24", "provider": "ProviderName", "balance": 5.9, "_self": { "href": "/gatewayqa/giftcards/3ad63br54-988e-4a14-8b7f-31fc6a5b955c_24" } } ] } } } }, "deprecated": false } }, "/giftcards/{giftCardId}": { "get": { "tags": [ "Gift Cards" ], "summary": "Get a gift card by ID", "description": "Returns information for a specific gift card from a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n> ℹ️ This endpoint must respond to the flow triggered by the [Add payment data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/paymentData) endpoint within 1.5 seconds. If the response time exceeds 1.5 seconds, the Checkout UI will show an error message stating that the gift card is invalid.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "GetGiftCardbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/vnd.vtex.giftcards.v1+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/vnd.vtex.giftcards.v1+json" } }, { "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 creation date." }, "expiringDate": { "type": "string", "description": "Gift card expiration date." }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." }, "discount": { "type": "boolean", "description": "Discount information.", "deprecated" : true }, "transactions": { "type": "object", "description": "Transactions information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The number described in the URL refers to the gift card identification." } } } } }, "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" } } } } } }, "deprecated": false } }, "/giftcards": { "post": { "tags": [ "Gift Cards" ], "summary": "Create a gift card", "description": "Creates a gift card for a specific user in a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "CreateGiftCard", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/vnd.vtex.giftcards.v1+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/vnd.vtex.giftcards.v1+json" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcards.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "relationName": { "type": "string", "description": "Field to be filled in when it is not necessary to use a loyalty program for the gift card. Note that a new `relationNamevalue` is required for each new gift card to be created." }, "emissionDate": { "type": "string", "description": "Gift card creation 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." }, "restrictedToOwner": { "type": "boolean", "description": "The gift card can only be used for a specified client's ID." }, "multipleRedemptions": { "type": "boolean", "description": "The gift card can be used to make new purchases until its value is completely used." }, "multipleCredits": { "type": "boolean", "description": "The gift card balance can be changed." }, "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)." }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." } } }, "example": { "id": "38", "relationName": "loyalty-program", "emissionDate": "2011-02-04T17:02:19.17", "expiringDate": "2020-02-04T17:02:19.17", "caption": "Loyalty Program", "restrictedToOwner": true, "multipleRedemptions": true, "multipleCredits": true, "profileId": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff", "currencyCode":"USD" } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions": { "post": { "tags": [ "Transactions" ], "summary": "Create a gift card transaction", "description": "Creates a transaction (credit or debit) for a gift card in a gift card provider and authorizes the item reservation.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "2" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcards.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardTransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GiftCardTransactionResponse" }, "example": { "cardId": "24", "id": "68347b311ce5407c90fa5316975d047a", "_self": { "href": "gatewayqa/giftcards/24/transactions/68347b311ce5407c90fa5316975d047a" } } } } } }, "deprecated": false }, "get": { "tags": [ "Transactions" ], "summary": "List all gift card transactions", "description": "Returns the IDs of all transactions performed in a gift card provider for a specific gift card.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "2" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GiftCardTransactionResponse" } }, "example": [ { "cardId": "3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24", "id": "68347b311ce5407c90fa5316975d047a", "_self": { "href": "gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/68347b311ce5407c90fa5316975d047a" } }, { "cardId": "3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24", "id": "e122ebd4501a4b3b93640b7444ac425d", "_self": { "href": "gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d" } } ] } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{transactionId}": { "get": { "tags": [ "Transactions" ], "summary": "Get a gift card transaction by ID", "description": "Returns a specific transaction for a gift card from a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "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": "GiftCardProvider1", "date": "2023-06-02T18:24:49.252855Z", "settlement": { "href": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/settlements" }, "cancellation": { "href": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/cancellations" }, "authorization": { "href": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/authorization" }, "operation": "Debit" } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{transactionId}/authorization": { "get": { "tags": [ "Transactions" ], "summary": "Get a gift card transaction authorization", "description": "Returns information about a gift card transaction authorization from a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "GetGiftCardTransactionAuthorization", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "example": { "oid": "e122ebd4501a4b3b93640b7444ac425d", "value": 5.92, "date": "2019-03-18T14:42:32.1291783Z" } } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{transactionId}/cancellations": { "post": { "tags": [ "Transactions" ], "summary": "Cancel a gift card transaction", "description": "This request can be used to:\r\n\r\n1. Cancel a transaction for a specific gift card in a gift card provider.\r\n\r\n2. Cancel an item's reservation or create a refund.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "CreateGiftCardTransactionCancellation", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b476900c" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcards.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardTransactionCancellationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "example": { "oid": "7582d93baccc44e9867b0b861696fc0a", "value": 4.1, "date": "2019-03-19T14:35:16.7157238Z" } } } } }, "deprecated": false }, "get": { "tags": [ "Transactions" ], "summary": "List all gift card transactions cancellations", "description": "Returns all transactions cancelled for a specific gift card from a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "ListAllGiftCardTransactionsCancellations", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionResponse" } }, "example": [ { "oid": "7582d93baccc44e9867b0b861696fc0a", "value": 4.1, "date": "2019-03-19T14:35:16.7157238Z" } ] } } } }, "deprecated": false } }, "/giftcards/{giftCardId}/transactions/{tId}/settlements": { "post": { "tags": [ "Transactions" ], "summary": "Settle a gift card transaction", "description": "Creates a transaction settlement for a specific gift card from a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "CreateGiftCardTransactionSettlement", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "2" } }, { "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": "3146f46162f042f483cd3979ba4e8317" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcards.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardTransactionSettlementRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "example": { "oid": "e122ebd4501a4b3b93640b7444ac425d", "value": 1.8, "date": "2019-03-18T14:42:32.1291783Z" } } } } }, "deprecated": false }, "get": { "tags": [ "Transactions" ], "summary": "List all gift card transactions settlements", "description": "Returns all transactions settlements for a specific gift card from a gift card provider.\r\n\r\n> ℹ️ This request is made from VTEX to the gift card payment provider.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed.", "operationId": "ListAllGiftCardTransactionsSettlements", "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": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7" } }, { "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": "3146f46162f042f483cd3979ba4e8317" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "array", "description": "Array containing gift card transactions settlements information.", "items": { "type": "object", "description": "Payment rules 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" } ] } } } }, "deprecated": false } } }, "components": { "schemas": { "ListAllGiftCardsRequest": { "description": "Gift cards information.", "required": [ "client", "cart" ], "type": "object", "properties": { "client": { "$ref": "#/components/schemas/Client" }, "cart": { "$ref": "#/components/schemas/Cart" } } }, "Client": { "description": "Customer information.", "required": [ "id", "email", "document" ], "type": "object", "properties": { "id": { "type": "string", "description": "Customer's identification.", "example": "3b1abc17" }, "email": { "type": "string", "description": "Customer's email address.", "example": "email@domain.com" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "234235" } } }, "Cart": { "description": "Cart information.", "required": [ "grandTotal", "relationName", "redemptionCode", "discounts", "shipping", "taxes", "items", "itemsTotal" ], "type": "object", "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": "BAHD-ASDB-ADQW-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", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item" } }, "itemsTotal": { "type": "integer", "description": "Total items value.", "example": 200 } } }, "Item": { "description": "Items information.", "required": [ "productId", "id", "refId", "name", "price", "quantity" ], "type": "object", "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 } } }, "response": { "description": "Response information.", "required": [ "id", "provider", "balance", "_self" ], "type": "object", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "provider": { "type": "string", "description": "Provider's name." }, "balance": { "type": "number", "description": "Gift card current balance." }, "_self": { "$ref": "#/components/schemas/Self" } } }, "Self": { "required": [ "href" ], "type": "object", "description": "It is an 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`." } } }, "response1": { "description": "Items information.", "required": [ "id", "redemptionToken", "redemptionCode", "balance", "emissionDate", "expiringDate", "discount", "transaction" ], "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 creation date." }, "expiringDate": { "type": "string", "description": "Gift card expiration date." }, "discount": { "type": "boolean", "description": "Discount applied on item." }, "transaction": { "$ref": "#/components/schemas/Transaction" } }, "example": { "id": "3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24", "redemptionToken": "XTYB-IOBW-WLJE-SEYG", "redemptionCode": "XTYB-IOBW-WLJE-SEYG", "balance": 5.9, "emissionDate": "2018-03-20T09:37:13.797", "expiringDate": "2020-03-18T11:42:55.183", "discount": false, "transaction": { "href": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions" } } }, "Transaction": { "description": "Transaction information.", "required": [ "href" ], "type": "object", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The number described in the URL refers to the gift card identification." } }, "example": { "href": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions" } }, "CreateGiftCardRequest": { "description": "Create a gift card request body information.", "required": [ "relationName", "caption", "profileId" ], "type": "object", "properties": { "relationName": { "type": "string", "description": "Field to be filled in when it is not necessary to use a loyalty program for the gift card. Note that a new `relationNamevalue` is required for each new gift card to be created.", "example": "loyalty-program" }, "emissionDate": { "type": "string", "description": "Gift card creation date.", "example": "2020-08-01T13:15:30Z" }, "expiringDate": { "type": "string", "description": "Gift card expiration date.", "example": "2020-09-01T13: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": true }, "multipleRedemptions": { "type": "boolean", "description": "The gift card can be used to make new purchases until its value is completely used.", "example": true }, "multipleCredits": { "type": "boolean", "description": "The gift card balance can be changed.", "example": true }, "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": "92de2249-0e02-4ca9-a4aa-a09cc9d8f7ff" }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217.", "example": "USD" } } }, "CreateGiftCardTransactionRequest": { "description": "Create a gift card transaction request body information.", "required": [ "operation", "value", "description", "redemptionToken", "redemptionCode", "requestId", "orderInfo" ], "type": "object", "properties": { "operation": { "type": "string", "description": "Type of operation. Possible values are: `Debit` or `Credit`.", "example": "Debit" }, "value": { "type": "number", "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": { "description": "Order Information.", "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID.", "example": "v500" }, "sequence": { "type": "integer", "description": "Sequence number.", "example": 5006128 }, "cart": { "$ref": "#/components/schemas/Cart1" }, "clientProfile": { "$ref": "#/components/schemas/ClientProfile" }, "shipping": { "$ref": "#/components/schemas/Shipping" } } }, "Cart1": { "description": "Cart information.", "required": [ "items", "grandTotal", "discounts", "shipping", "taxes", "itemsTotal" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item2" }, "description": "Items information." }, "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": { "description": "Item information.", "required": [ "id", "productId", "refId", "name", "value", "price", "quantity", "shippingDiscount", "discount", "priceTags" ], "type": "object", "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": "array", "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.", "items": { "type": "string", "description": "Price tags information." } } } }, "ClientProfile": { "description": "Client profile information.", "required": [ "email", "firstName", "lastName", "document", "phone", "birthDate", "isCorporate" ], "type": "object", "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": { "description": "Shipping information.", "required": [ "receiverName", "postalCode", "city", "state", "country", "street", "number", "neighborhood", "complement", "reference" ], "type": "object", "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 } } }, "GiftCardTransactionResponse": { "description": "Gift card transaction response information.", "required": [ "cardId", "id", "_self" ], "type": "object", "properties": { "cardId": { "type": "string", "description": "Gift card identification." }, "id": { "type": "string", "description": "Transaction identification." }, "_self": { "$ref": "#/components/schemas/Self" } } }, "Cart2": { "description": "Cart information.", "required": [ "items", "grandTotal", "discounts", "shipping", "taxes", "itemsTotal" ], "type": "object", "properties": { "items": { "type": "array", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item2" } }, "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 } } }, "Item2": { "description": "Items information.", "required": [ "id", "productId", "refId", "name", "value", "price", "quantity", "shippingDiscount", "discount", "priceTags" ], "type": "object", "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": "array", "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.", "items": { "$ref": "#/components/schemas/PriceTag" } } } }, "PriceTag": { "description": "Price tag information.", "required": [ "name", "value" ], "type": "object", "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 } } }, "Settlement": { "type": "object", "description": "Settlement transaction information.", "required": [ "href" ], "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.", "example": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/settlements" } } }, "Cancellation": { "type": "object", "description": "Cancellation transaction information.", "required": [ "href" ], "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.", "example": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/cancellations" } } }, "Authorization": { "type": "object", "description": "Authorization transaction information.", "required": [ "href" ], "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.", "example": "/gatewayqa/giftcards/3b1abc17-988e-4a14-8b7f-31fc6a5b955c_24/transactions/e122ebd4501a4b3b93640b7444ac425d/authorization" } } }, "TransactionResponse": { "description": "Transaction response information.", "required": [ "oid", "value", "date" ], "type": "object", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date information." } } }, "CreateGiftCardTransactionCancellationRequest": { "description": "Cancel a gift card transaction request information.", "required": [ "value", "requestId" ], "type": "object", "properties": { "value": { "type": "number", "description": "Transaction value.", "example": 4.1 }, "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": "12093812masoidj120398" } } }, "CreateGiftCardTransactionSettlementRequest": { "description": "Settle a gift card transaction request information.", "required": [ "value", "requestId" ], "type": "object", "properties": { "value": { "type": "number", "description": "Transaction value.", "example": 1.8 }, "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": "12093812masoidj120398" } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-PROVIDER-API-AppKey", "description": "Unique identifier created by the provider and configured through [Giftcard Hub API](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#put-/api/giftcardproviders/-giftCardProviderId-)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-PROVIDER-API-AppToken", "description": "Unique token created by the provider and configured through [Giftcard Hub API](https://developers.vtex.com/docs/api-reference/giftcard-hub-api#put-/api/giftcardproviders/-giftCardProviderId-)." } } }, "tags": [ { "name": "Gift Cards" }, { "name": "Transactions" } ], "security": [ { "appKey": [], "appToken": [] } ] }