The VTEX Gift Card Provider Protocol defines the interface for integrating external gift card providers with VTEX. It specifies the endpoints external providers must implement to handle gift card transactions, balance checks, and redemption flows within VTEX checkout.
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 protected]
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:
redemptio
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-gift-card-provider-protocol-openapi-original.yml