--- schema_version: "1" id: f30d8eaaa839f91df5012afca84c5f28d2e867ccc0d5cb5f0d4ec7348036251c title: Gift Card SPI collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/gift-card-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/gift-card-spi source_site: developer.salesforce.com content_type: documentation content_hash: 1d260d810e8b3e74c7da2b77a5beded74a4780cc936f18c3071a8e10f1a9e5ea products: - Point of Sale for Developers - Salesforce APIs --- Gift Card SPI # Gift Card SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-card-spi/gift-card-spi-oas-public.yaml) Merchant SPI to perform gift card operations via a customer-managed provider adapter. Enables retailers to integrate any gift card provider without Point of Sale engineering involvement. APIs include balance check, card activation, loading funds, redemption, and void/reversal. ### Configuration 1. **Store Management** > **Integration** > **Custom API Connectors** > **Create** * **API KEY:** GIFT\_CARD\_SERVICE with authentication details and URL Base. * All the APIs defined below will use this URL base; only the operation-specific path suffix will change. 2. Set **Store Management** > **Integration** > **Gift Card** > **Service** to `SPI` 3. **Store Management** > **Integration** > **Gift Card** > **PIN Setting** controls whether cardPin is required or optional in requests. **Version:** 2.3.4 ## Tags ### Gift Card SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-card-spi/gift-card-spi-oas-public.yaml) Merchant SPI to perform gift card operations via a customer-managed provider adapter. Enables retailers to integrate any gift card provider without Point of Sale engineering involvement. APIs include balance check, card activation, loading funds, redemption, and void/reversal. ### Configuration 1. **Store Management** > **Integration** > **Custom API Connectors** > **Create** * **API KEY:** GIFT\_CARD\_SERVICE with authentication details and URL Base. * All the APIs defined below will use this URL base; only the operation-specific path suffix will change. 2. Set **Store Management** > **Integration** > **Gift Card** > **Service** to `SPI` 3. **Store Management** > **Integration** > **Gift Card** > **PIN Setting** controls whether cardPin is required or optional in requests. ## Operations ### POST Activate Gift Card `POST /merchant/spi/sample/endpoint/spiGiftCard/activateGiftCard` Operation ID: `activateGiftCard`. Tags: Gift Card SPI. Activates a new or inactive gift card at the provider with the specified amount. Called when a store associate sells a new gift card or issues a refund to a new card (step 1 of a two-step flow). The response `cardNumber` should echo back the card number from the request. The `providerTransactionId` returned must be stored by the platform and passed back in any subsequent void request. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset. #### Request body Media type: `application/json`. Schema: `SpiGiftCardActivateRequest`. #### Responses * **default** default response. Media type: `application/json`. Schema: `SpiGiftCardActivateResponse`. ### POST Add Balance to Gift Card `POST /merchant/spi/sample/endpoint/spiGiftCard/addBalance` Operation ID: `addBalance`. Tags: Gift Card SPI. Loads funds onto an existing active gift card. Used during gift card purchase (step 2 after activation) or when issuing a refund to an existing card. The `providerTransactionId` returned must be stored by the platform and passed back in any subsequent void request. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset. #### Request body Media type: `application/json`. Schema: `SpiGiftCardAddBalanceRequest`. #### Responses * **default** default response. Media type: `application/json`. Schema: `SpiGiftCardAddBalanceResponse`. ### POST Check Gift Card Balance `POST /merchant/spi/sample/endpoint/spiGiftCard/checkBalance` Operation ID: `checkBalance`. Tags: Gift Card SPI. Checks the current balance and active status of a gift card. This single endpoint serves two platform operations: * **getBalance()** — platform reads `balance` and `cardNumber` from the response * **isInactive()** — platform reads `isActive` from the response The response must always include both `balance` and `isActive` so either operation can be served. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset. #### Request body Media type: `application/json`. Schema: `SpiGiftCardBalanceRequest`. #### Responses * **default** default response. Media type: `application/json`. Schema: `SpiGiftCardBalanceResponse`. ### POST Redeem Gift Card `POST /merchant/spi/sample/endpoint/spiGiftCard/redeemGiftCard` Operation ID: `redeemGiftCard`. Tags: Gift Card SPI. Deducts funds from a gift card. Used for two scenarios: * **Payment tender** — deducts the requested amount during checkout * **Cash out** — platform validates the balance is at or below the configured threshold, then calls this endpoint with the full balance to bring the card to $0 On success (no errorCode), the full requested amount is redeemed. Partial redemption is not supported. The `providerTransactionId` is stored as the capture token and the `providerReferenceId` is stored as the requestId on the tender — both are required for reconciliation and void operations. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset. #### Request body Media type: `application/json`. Schema: `SpiGiftCardRedeemRequest`. #### Responses * **default** default response. Media type: `application/json`. Schema: `SpiGiftCardRedeemResponse`. ### POST Void Gift Card Transaction `POST /merchant/spi/sample/endpoint/spiGiftCard/voidGiftCard` Operation ID: `voidGiftCard`. Tags: Gift Card SPI. Reverses a previous gift card operation (redeem or addBalance). Called when an order fails after a gift card charge was captured, or when an explicit reversal is needed. The `originalProviderTransactionId` in the request must match the `providerTransactionId` returned by the original operation so the provider can identify which transaction to reverse. The `amount` must match the `approvedAmount` from the original operation. The `providerReferenceId` returned is stored by the platform as the paymentReversalRequestId on the tender. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset. #### Request body Media type: `application/json`. Schema: `SpiGiftCardVoidRequest`. #### Responses * **default** default response. Media type: `application/json`. Schema: `SpiGiftCardVoidResponse`. ## Schemas ### SpiGiftCardActivateRequest * `cardNumber` (_string_, required) Gift card PAN (primary account number). * `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN. * `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing. * `amount` (_number_, required) Activation amount (gift card purchase price); non-negative. ### SpiGiftCardActivateResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `cardNumber` (_string_, required) Echoed card number from the request. * `balance` (_number_, required) Current balance on the gift card; non-negative. * `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations. * `error` (_boolean_) ### SpiGiftCardAddBalanceRequest * `cardNumber` (_string_, required) Gift card PAN (primary account number). * `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN. * `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing. * `amount` (_number_, required) Amount to load onto the card; non-negative. ### SpiGiftCardAddBalanceResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `cardNumber` (_string_, required) Echoed card number from the request. * `balance` (_number_, required) Current balance on the gift card; non-negative. * `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations. * `error` (_boolean_) ### SpiGiftCardBalanceRequest * `cardNumber` (_string_, required) Gift card PAN (primary account number). * `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN. * `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing. ### SpiGiftCardBalanceResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `balance` (_number_, required) Current balance on the gift card; non-negative. * `isActive` (_boolean_) True if the card is active and usable; defaults to true. * `cardNumber` (_string_) Echoed card number from the request. * `error` (_boolean_) ### SpiGiftCardRedeemRequest * `cardNumber` (_string_, required) Gift card PAN (primary account number). * `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN. * `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing. * `amount` (_number_, required) Amount to deduct from the card; non-negative. ### SpiGiftCardRedeemResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `cardNumber` (_string_, required) Echoed card number from the request. * `balance` (_number_, required) Current balance on the gift card; non-negative. * `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations. * `providerReferenceId` (_string_, required) Provider's reference identifier; stored by platform as requestId on the tender for reconciliation. * `error` (_boolean_) ### SpiGiftCardVoidRequest * `cardNumber` (_string_, required) Gift card PAN (primary account number). * `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN. * `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing. * `amount` (_number_, required) Amount to reverse; must match the approvedAmount from the original operation. * `originalProviderTransactionId` (_string_, required) Provider's transaction identifier from the original operation being voided. ### SpiGiftCardVoidResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `cardNumber` (_string_, required) Echoed card number from the request. * `providerReferenceId` (_string_, required) Provider's reference identifier for the void; stored by platform as paymentReversalRequestId. * `error` (_boolean_)