> For the complete documentation index, see [llms.txt](https://docs.solapayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.solapayments.com/api/transaction/gift-card.md).
# Gift Card
## Overview
This page contains all API documentation for Gift Card transactions. For more information regarding account access, navigate to the [Transaction API](/api/transaction.md) parent page.
## Transactions
### Issue
`POST` `gift:issue`
`xCommand` = `gift:issue`\
\
The Issue command is used to issue funds to a Sola gift card.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| xKey\* | String | Your Sola API key. |
| xVersion\* | String | Gateway API version. The current version is 5.0.0. |
| xSoftwareName\* | String | Name of your software |
| xSoftwareVersion\* | String | Version number of your software |
| xCommand\* | String | Sola transaction type |
| xCustom01\* | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
| xAmount\* | String | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. |
| xToken | String | The Sola token that references a previously used payment card. When using this variable, `xCardNumand xMagstripe` should not be used maximum 50 alphanumeric characters). |
| xMagstripe | String | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, `xCardNum` `xExp` and `xToken` should not be used. Encryptedcard data can also be sent using `xMagstripe` |
| xName | String | The cardholder’s name |
| xTax | String | The tax portion that is included in the total transaction amount (xAmount) |
| xTip | String | The tip portion that is included in the total transaction amount (xAmount) |
| xInvoice | String | The merchant’s invoice number for the transaction. `xInvoice` is recommended when available for improved duplicate handling. |
| xPONum | String | The merchant’s purchase order number for the transaction |
| xComments | String | Additional data that is optionally passed along to the receipt |
| xDescription | String | Additional data that is optionally passed along for reporting |
| xIP | String | The customer’s IP address. Typically used for fraud detection. |
| xEmail | String | The customer’s email address |
| xFax | String | The customer’s fax number |
| xBillFirstName | String | The customer’s first name for their billing profile |
| xBillMiddleName | String | The customer’s middle name or initial for their billing profile |
| xBillLastName | String | The customer’s last/family name for their billing profile |
| xBillCompany | String | The customer’s company name for their billing profile |
| xBillStreet | String | The customer’s street address for their billing profile |
| xBillStreet2 | String | The customer’s street address 2nd line for their billing profile |
| xBillCity | String | The customer’s city for their billing profile |
| xBillState | String | The customer’s state for their billing profile |
| xBillZip | String | The customer’s zip code for their billing profile |
| xBillCountry | String | The customer’s country for their billing profile |
| xBillPhone | String | The customer’s phone number for their billing profile |
| xBillMobile | String | The customer’s mobile number for their billing profile |
| xShipFirstName | String | The customer’s first name for their shipping profile |
| xShipMiddleName | String | The customer’s middle name or initial for their shipping profile |
| xShipLastName | String | The customer’s last/family name for their shipping profile |
| xShipCompany | String | The customer’s company name for their shipping profile |
| xShipStreet | String | The customer’s street address for their shipping profile |
| xShipStreet2 | String | The customer’s street address 2nd line for their shipping profile |
| xShipCity | String | The customer’s city for their shipping profile |
| xShipState | String | The customer’s state for their shipping profile |
| xShipZip | String | The customer’s zip code for their shipping profile |
| xShipCountry | String | The customer’s country for their shipping profile |
| xShipPhone | String | The customer’s phone number for their shipping profile |
| xShipMobile | String | The customer’s mobile number for their shipping profile |
| xAllowDuplicate | String | By default, Sola rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
| xOrderID | String | Unique order number for FraudWatch verification |
| xExistingCustomer | String | Yes/No value indicating if the customer is a repeat customer |
| xExp | String | Gift card expiration number. Format: MMYY. For sandbox accounts, use any date in the future. \*Required and available only when `xCardNum` is used. |
| xCVV | String | 3-digit code from the back of the card (for Amex, 4-digit code from the front of the card) |
| xStreet | String | The billing street address of the cardholder |
| xZip | String | The billing zip code of the cardholder |
| xDUKPT | String | The DUK/PT key for PIN debit and EBT transactions.The first 16 characters are the encrypted PIN block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN pad serial number and transaction counter. |
| xTimeoutSeconds | String | Configurable amount of seconds in which the request will wait for a response. |
{% code title="Issue - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xKey": "[xkeycredentials]",
"xVersion": "4.5.9",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "gift:issue",
"xAmount": "35.00",
"xToken": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
"xCustom01": "Register01",
"xExp": "12/25",
"xCVV": "945",
"xStreet": "123 Any Street Apt 4b Anytown, NY",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xDUKPT": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;444433",
"xTax": "2.00",
"xTip": "2.00",
"xInvoice": "123456A",
"xPONum": "123456B",
"xComments": "This is a comment",
"xDescription": "This is a description",
"xIP": "1.2.3.4",
"xEmail": "text@example.com",
"xFax": "1234567890",
"xBillFirstName": "John",
"xBillMiddleName": "Max",
"xBillLastName": "Doe",
"xBillCompany": "Acme",
"xBillStreet": "123 Any Street",
"xBillStreet2": "Apt 4b",
"xBillCity": "Anytown",
"xBillState": "NY",
"xBillZip": "12345",
"xBillCountry": "USA",
"xBillPhone": "8005551212",
"xBillMobile": "8005551111",
"xShipFirstName": "John",
"xShipMiddleName": "Max",
"xShipLastName": "Doe",
"xShipCompany": "Acme",
"xShipStreet": "123 Any Street",
"xShipStreet2": "Apt 4b",
"xShipCity": "Anytown",
"xShipState": "NY",
"xShipZip": "12345",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xOrderID": "12356",
"xExistingCustomer": "TRUE",
"xAllowDuplicate": "TRUE",
"xTimeoutSeconds": "10"
}
```
{% endcode %}
### Redeem
`POST` `gift:redeem`
`xCommand` = `gift:redeem`
The Redeem command is used to debit funds from a Sola gift card.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| xKey\* | String | Your Sola API key. |
| xVersion\* | String | Gateway API version. The current version is 5.0.0. |
| xSoftwareName\* | String | Name of your software |
| xSoftwareVersion\* | String | Version number of your software |
| xCommand\* | String | Sola transaction type |
| xAmount\* | String | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. |
| xCustom01\* | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
| xToken | String | The Sola token that references a previously used card. When using a variable, `xCardNumand xMagstripe` should no be used (maximum 50 alphanumeric characters). |
| xMagstripe | String | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, `xCardNum` `xExp` and `xToken` should not be used. Encrypted Card data can also be sent using `xMagstripe.` |
| xName | String | The cardholder’s name |
| xTax | String | The tax portion that is included in the total transaction amount (xAmount) |
| xTip | String | The tip portion that is included in the total transaction amount (xAmount) |
| xInvoice | String | The merchant’s invoice number for the transaction. `xInvoice` is recommended when available for improved duplicate handling. |
| xPONum | String | The merchant’s purchase order number for the transaction |
| xComments | String | Additional data that is optionally passed along to the receipt |
| xDescription | String | Additional data that is optionally passed along for reporting |
| xIP | String | The customer’s IP address. Typically used for fraud detection. |
| xEmail | String | The customer’s email address |
| xFax | String | The customer’s fax number |
| xBillFirstName | String | The customer’s first name for their billing profile |
| xBillMiddleName | String | The customer’s middle name or initial for their billing profile |
| xBillLastName | String | The customer’s last/family name for their billing profile |
| xBillCompany | String | The customer’s company name for their billing profile |
| xBillStreet | String | The customer’s street address for their billing profile |
| xBillStreet2 | String | The customer’s street address 2nd line for their billing profile |
| xBillCity | String | The customer’s city for their billing profile |
| xBillState | String | The customer’s state for their billing profile |
| xBillZip | String | The customer’s zip code for their billing profile |
| xBillCountry | String | The customer’s country for their billing profile |
| xBillPhone | String | The customer’s phone number for their billing profile |
| xBillMobile | String | The customer’s mobile number for their billing profile |
| xShipFirstName | String | The customer’s first name for their shipping profile |
| xShipMiddleName | String | The customer’s middle name or initial for their shipping profile |
| xShipLastName | String | The customer’s last/family name for their shipping profile |
| xShipCompany | String | The customer’s company name for their shipping profile |
| xShipStreet | String | The customer’s street address for their shipping profile |
| xShipStreet2 | String | The customer’s street address 2nd line for their shipping profile |
| xShipCity | String | The customer’s city for their shipping profile |
| xShipState | String | The customer’s state for their shipping profile |
| xShipZip | String | The customer’s zip code for their shipping profile |
| xShipCountry | String | The customer’s country for their shipping profile |
| xShipPhone | String | The customer’s phone number for their shipping profile |
| xShipMobile | String | The customer’s mobile number for their shipping profile |
| xAllowDuplicate | String | By default, Sola rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
| xOrderID | String | Unique order number for FraudWatch verification |
| xExistingCustomer | String | Yes/No value indicating if the customer is a repeat customer |
| xExp | String | Gift card expiration number. Format: MMYY. For sandbox accounts, use any date in the future. \*Required and available only when `xCardNum` is used. |
| xCVV | String | 3-digit code from the back of the card (for Amex, 4-digit code from the front of the card). |
| xStreet | String | The billing street address of the cardholder |
| xZip | String | The billing zip code of the cardholder |
| xDUKPT | String | The DUK/PT key for PIN debit and EBT transactions.The first 16 characters are the encrypted PIN block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN pad serial number and transaction counter. |
| xTimeoutSeconds | String | Configurable amount of seconds in which the request will wait for a response. |
{% code title="Redeem - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xKey": "[xkeycredentials]",
"xVersion": "4.5.9",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "gift:redeem",
"xAmount": "35.00",
"xToken": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
"xCustom01": "Register01",
"xExp": "12/25",
"xCVV": "945",
"xStreet": "123 Any Street Apt 4b Anytown, NY",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xDUKPT": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;444433",
"xTax": "2.00",
"xTip": "2.00",
"xInvoice": "123456A",
"xPONum": "123456B",
"xComments": "This is a comment",
"xDescription": "This is a description",
"xIP": "1.2.3.4",
"xEmail": "text@example.com",
"xFax": "1234567890",
"xBillFirstName": "John",
"xBillMiddleName": "Max",
"xBillLastName": "Doe",
"xBillCompany": "Acme",
"xBillStreet": "123 Any Street",
"xBillStreet2": "Apt 4b",
"xBillCity": "Anytown",
"xBillState": "NY",
"xBillZip": "12345",
"xBillCountry": "USA",
"xBillPhone": "8005551212",
"xBillMobile": "8005551111",
"xShipFirstName": "John",
"xShipMiddleName": "Max",
"xShipLastName": "Doe",
"xShipCompany": "Acme",
"xShipStreet": "123 Any Street",
"xShipStreet2": "Apt 4b",
"xShipCity": "Anytown",
"xShipState": "NY",
"xShipZip": "12345",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xOrderID": "12356",
"xExistingCustomer": "TRUE",
"xAllowDuplicate": "TRUE",
"xTimeoutSeconds": "10"
}
```
{% endcode %}
### Balance
`POST` `gift:balance`
`xCommand` = `gift:balance`\
\
The Balance command is used to check the available balance on a Sola gift card.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| xKey\* | String | Your Sola API key. |
| xVersion\* | String | Gateway API version. The current version is 5.0.0. |
| xSoftwareName\* | String | Name of your software |
| xSoftwareVersion\* | String | Version number of your software |
| xCommand\* | String | Sola transaction type |
| xToken | String | The Sola token that references a previously used payment method. When using a token, `xCardNum` `xExp` and `xMagstripe` should not be used. |
| xMagstripe | String | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, `xCardNum` `xExp` and `xToken` should not be used. Encrypted card data can also be sent using `xMagstripe.` |
| xName | String | The cardholder’s name |
| xTax | String | The tax portion that is included in the total transaction amount (xAmount) |
| xTip | String | The tip portion that is included in the total transaction amount (xAmount) |
| xInvoice | String | The merchant’s invoice number for the transaction. `xInvoice` is recommended when available for improved duplicate handling. |
| xPONum | String | The merchant’s purchase order number for the transaction |
| xComments | String | Additional data that is optionally passed along to the receipt |
| xDescription | String | Additional data that is optionally passed along for reporting |
| xIP | String | The customer’s IP address. Typically used for fraud detection |
| xEmail | String | The customer’s email address |
| xFax | String | The customer’s fax number |
| xBillFirstName | String | The customer’s first name for their billing profile |
| xBillMiddleName | String | The customer’s middle name or initial for their billing profile |
| xBillLastName | String | The customer’s last/family name for their billing profile |
| xBillCompany | String | The customer’s company name for their billing profile |
| xBillStreet | String | The customer’s street address for their billing profile |
| xBillStreet2 | String | The customer’s street address 2nd line for their billing profile |
| xBillCity | String | The customer’s city for their billing profile |
| xBillState | String | The customer’s state for their billing profile |
| xBillZip | String | The customer’s zip code for their billing profile |
| xBillCountry | String | The customer’s country for their billing profile |
| xBillPhone | String | The customer’s phone number for their billing profile |
| xBillMobile | String | The customer’s mobile number for their billing profile |
| xShipFirstName | String | The customer’s first name for their shipping profile |
| xShipMiddleName | String | The customer’s middle name or initial for their shipping profile |
| xShipLastName | String | The customer’s last/family name for their shipping profile |
| xShipCompany | String | The customer’s company name for their shipping profile |
| xShipStreet | String | The customer’s street address for their shipping profile |
| xShipStreet2 | String | The customer’s street address 2nd line for their shipping profile |
| xShipCity | String | The customer’s city for their shipping profile |
| xShipState | String | The customer’s state for their shipping profile |
| xShipZip | String | The customer’s zip code for their shipping profile |
| xShipCountry | String | The customer’s country for their shipping profile |
| xShipPhone | String | The customer’s phone number for their shipping profile |
| xShipMobile | String | The customer’s mobile number for their shipping profile |
| xAllowDuplicate | String | By default, Sola rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
| xOrderID | String | Unique order number for FraudWatch verification |
| xExistingCustomer | String | Yes/No value indicating if the customer is a repeat customer |
| xExp | String | The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. `*xExp` is required when sending in `xCardnum` and cannot be used with `xMagstripe.` |
| xCVV | String | 3-digit code from the back of the card (for Amex, 4-digit code from the front of the card). |
| xStreet | String | The billing street address of the cardholder |
| xZip | String | The billing zip code of the cardholder |
| xDUKPT | String | The DUK/PT key for PIN debit and EBT transactions.The first 16 characters are the encrypted PIN block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN pad serial number and transaction counter. |
| Custom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
| xAuthCode | String | `xAuthCode` is a verification number provided by the issuing bank to be used with the cc:postauth command |
| xRefNum | String | Used to reference a previous transaction when processing a follow-up transaction, typically a refund, void, or capture. (Note: `xRefnum` can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String). |
| xMICR | String | The routing, account, and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner |
| xRouting | String | The check ABA routing number |
| xGatewayRefNum | String | Transaction RefNum received from gateway for FraudWatch verification |
| xGatewayResult | String | Transaction status received from gateway for FraudWatch verification (Approved/Declined/Error) |
| xGatewayError | String | Transaction RefNum received from gateway for FraudWatch verification. |
| xGatewayCVV | String | CVV for for FraudWatch verification. |
| xOrderType | String | Specifies if the order origin is internet OR phone for FraudWatch verification |
| xGatewayAVS | String | Street address for FraudWatch verification |
| xOrderItems | String | Summary of products ordered |
| xCustomerComments | String | Comments submitted by thecustomer along with the order |
| xShipMethod | String | The shipping carrier/service used |
| xShipAmount | String | The total cost of shipping charges |
| xShipEmail | String | The ShipTo email address |
{% code title="Balance - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xKey": "[xkeycredentials]",
"xVersion": "4.5.9",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "gift:balance",
"xToken": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
"xCustom01": "Register01",
"xExp": "12/25",
"xCVV": "945",
"xStreet": "123 Any Street Apt 4b Anytown, NY",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xAuthCode": "T4321A",
"xDUKPT": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;444433",
"xTax": "2.00",
"xTip": "2.00",
"xRefNum": "81234568",
"xInvoice": "123456A",
"xPONum": "123456B",
"xComments": "This is a comment",
"xDescription": "This is a description",
"xIP": "1.2.3.4",
"xEmail": "text@example.com",
"xFax": "1234567890",
"xBillFirstName": "John",
"xBillMiddleName": "Max",
"xBillLastName": "Doe",
"xBillCompany": "Acme",
"xBillStreet": "123 Any Street",
"xBillStreet2": "Apt 4b",
"xBillCity": "Anytown",
"xBillState": "NY",
"xBillZip": "12345",
"xBillCountry": "USA",
"xBillPhone": "8005551212",
"xBillMobile": "8005551111",
"xShipFirstName": "John",
"xShipMiddleName": "Max",
"xShipLastName": "Doe",
"xShipCompany": "Acme",
"xShipStreet": "123 Any Street",
"xShipStreet2": "Apt 4b",
"xShipCity": "Anytown",
"xShipState": "NY",
"xShipZip": "12345",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xMICR": "t021000021t 123456789o _2542",
"xRouting": "021202337",
"xGatewayRefNum": "852585258",
"xGatewayResult": "Approved",
"xGatewayError": "845455484",
"xGatewayCVV": "M",
"xGatewayAVS": "YYY",
"xOrderType": "Internet",
"xOrderID": "12356",
"xExistingCustomer": "TRUE",
"xOrderItems": "Sony Digital Camera",
"xCustomerComments": "Please ship as soon as possible",
"xShipMethod": "UPS Ground",
"xShipAmount": "29.99",
"xShipEmail": "text@example.com",
"xAllowDuplicate": "TRUE"
}
```
{% endcode %}
### Activate
`POST` `gift:activate`
`xCommand` = `gift:activate`\
The Activate command is used to activate a Sola gift card.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, xToken, xMagStripe or `SUT` can be used. |
| xKey\* | String | Your Sola API key. |
| xVersion\* | String | Gateway API version. The current version is 5.0.0. |
| xSoftwareName\* | String | Name of your software |
| xSoftwareVersion\* | String | Version number of your software |
| xCommand\* | String | Sola transaction type |
{% code title="Activate - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xKey": "[xkeycredentials]",
"xVersion": "4.5.9",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "gift:activate"
}
```
{% endcode %}
### Deactivate
`POST` `gift:deactivate`
`xCommand` = `gift:deactivate`\
The Deactivate command is used to deactivate a Sola gift card.(note: you can still check the balance of the gift card even after it has been deactivated).
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, xToken, xMagStripe or `SUT` can be used. |
| xKey\* | String | Your Sola API key. |
| xVersion\* | String | Gateway API version. The current version is 5.0.0. |
| xSoftwareName\* | String | Name of your software |
| xSoftwareVersion\* | String | Version number of your software |
| xCommand\* | String | Sola transaction type |
{% code title="Deactivate - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xKey": "[xkeycredentials]",
"xVersion": "4.5.9",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "gift:deactivate"
}
```
{% endcode %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.solapayments.com/api/transaction/gift-card.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.