openapi: 3.0.0 info: title: VTex Giftcard Provider Protocol description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\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).\r\n\r\n## Giftcard Provider Protocol API Index\r\n\r\n### Gift Cards\r\n\r\n- `POST` [Create a gift card](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards)\r\n- `GET` [Get a gift card by ID](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-)\r\n- `POST` [List all gift cards](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/_search)\r\n\r\n### Transactions\r\n\r\n- `POST` [Create a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/-giftCardId-/transactions)\r\n- `GET` [Get a gift card transaction by ID](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-transactionId-)\r\n- `GET` [List all gift card transactions](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions)\r\n- `GET` [Get a gift card transaction authorization](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-transactionId-/authorization)\r\n- `POST` [Cancel a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/-giftCardId-/transactions/-transactionId-/cancellations)\r\n- `GET` [List all gift card transactions cancellations](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-transactionId-/cancellations)\r\n- `POST` [Settle a gift card transaction](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#post-/giftcards/-giftCardId-/transactions/-tId-/settlements)\r\n- `GET` [List all gift card transactions settlements](https://developers.vtex.com/docs/api-reference/giftcard-provider-protocol#get-/giftcards/-giftCardId-/transactions/-tId-/settlements)" 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: VTex 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\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: 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.giftcardproviders.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.giftcardproviders.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.giftcardproviders.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: VTex 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## 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.giftcardproviders.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.giftcardproviders.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 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: VTex 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.giftcardproviders.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.giftcardproviders.v1+json requestBody: content: application/vnd.vtex.giftcardproviders.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: VTex 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.giftcardproviders.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: VTex 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: VTex 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 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: VTex 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: VTex 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.giftcardproviders.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: VTex 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: VTex 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.giftcardproviders.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: VTex 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 date: '2023-06-02T18:24:49.252855Z' - oid: hbar6832580652c4b8fb653f15ba9c5a7 value: 40 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: 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. 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. 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: []