# Credit Card
## Overview
This page contains all API documentation for Credit Card (CC) transactions. For more information regarding account access, navigate to the [Transaction API](/api/transaction.md) parent page.
## Transactions
### Sale
`POST` `cc:sale`
`xCommand` = `cc:Sale`
\
The Sale command is a combination of the authorization and capture transactions. it is intended for use when fulfilling an order right away. For transactions that are not fulfilled right away, use the [authonly](#authonly) command initially and then use the [capture](#capture) command to complete the sale.
The card to be charged can be communicated with 4 different approaches: `xCardNum` + `xExp` OR `xMagstripe` OR `xToken` OR `SUT`. Only one of these combinations can be used. Depending on the software or website’s security settings, `cc:sale` may also require `xCVV`, `xStreet`, or `xZip` and their related values.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
| 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. |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| xToken | String | The Sola token that references a previously used payment method. When using a token, `xCardNum` `xExp` and `xMagstripe` should not be used. |
| xCustom01 | String | 20 custom fields are available for custom data such as customer comments, etc. Use `xCustom01` through `xCustom20` |
| 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 |
| 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. |
| 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. |
| 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
\*Required when 3ds is enabled
|
| xFax | String | The customer’s fax number |
| xBillFirstName\* | String | The customer’s first name for their billing profile
\*Required when 3ds is enabled
|
| 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
\*Required when 3ds is enabled
|
| xBillCompany | String | The customer’s company name for their billing profile |
| xBillStreet\* | String | The customer’s street address for their billing profile
\*Required when 3ds is enabled
|
| xBillStreet2 | String | The customer’s street address 2nd line for their billing profile |
| xBillCity\* | String | The customer’s city for their billing profile.
\*Required when 3ds is enabled
|
| xBillState\* | String | The customer’s state for their billing profile
\*Required when 3ds is enabled
|
| xBillZip\* | String | The customer’s zip code for their billing profile
\*Required when 3ds is enabled
|
| 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
\*Required when 3ds is enabled
|
| 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 |
| x1Description | String | Line Item product description. Increment the “1“ for additional items. |
| x1Sku | String | Line Item product sku. Increment the “1“ for additional items. |
| x1Qty | String | Line Item product quantity. Increment the “1“ for additional items. |
| x1UnitPrice | String | Line Item product price. Increment the “1“ for additional items. |
| xHotelCheckInDate | String | The customer’s date of hotel check-in |
| xHotelCheckOutDate | String | The customer's date of hotel check-out |
| xAllowPartialAuth | String | True/false value indicating if an authorization amount is less than the initial request when full initial amount is unavailable. This variable is platform-dependent. Default is false. |
| xAllowNonAuthenticated | String | True/False value, enabling a customer to complete a purchase without needing to verify their identity through a separate authentication step. Defaults to false. |
| xRxAmount | String | Specifies qualifying prescription amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xDentalAmount | String | Specifies qualifying dental amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xVisionAmount | String | Specifies qualifying vision amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xTransitAmount | String | Specifies qualifying transit amount for commuter card transactions. `xAllowPartialAuth` must be set to True. |
| xCopayAmount | String | Specifies Co-pay amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xClinicalAmount | String | Specifies qualifying clinical amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xOrderId | String | Unique order number for FraudWatch verification |
| xExistingCustomer | String | Yes/No value indicating if customer is a repeat customer |
| xAllowDuplicate | String | By default, Sola rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
| xCustReceipt | String | True/False value indicating if the email address specified in `xemail` should receive a receipt containing the transaction details. |
| xCurrency | String | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified (see list of all supported currencies).
|
| xReturnPaymentID | Boolean | True/False value indicating if the user would like to receive xPaymentId in the transaction response. Unless specified, the value is “False”. Unlike an xToken which will return a new value on transactions of the same card, xPaymentId will return the same value for transactions using the same card. |
| xTimeoutSeconds | String | Configurable amount of seconds in which the request will wait for a response. |
| xVendorId | String | The parameter that tells the gateway which developer is performing the transaction. If the value matches the account of the iFields key, the gateway will allow the transaction to work even though the API and iFields keys are from different accounts. See more [here](https://docs.cardknox.com/cardknox-products/ifields#global-ifields-key) |
| xDigitalWalletType | String | This field should indicate the wallet type in a case where the card number is a digital wallet token (Ex: "Google Pay") |
| xRecurringIndicator\* | String | Indicates the type of transaction based on its recurrence. This field helps classify whether a transaction is part of a recurring series, an installment plan, a one-time charge, or a deferred payment.
*Required for Merchant-initiated transactions
Note: Use of this flag on a transaction does NOT set up a recurring schedule for the transaction. Recurring schedules must be set up separately.
Allowed Values:
Recurring- a transaction that is part of a regularly scheduled series (e.g., subscriptions). Usually initiated by the merchant after the first payment.
Installment- one in a series of transactions where the total amount is divided into multiple payments with a fixed schedule (e.g., 3 monthly payments).
*xInstallments is required when xRecurringIndicator = Installment
Single- a one-time transaction, not part of a recurring or installment plan.
Deferred- indicates that the transaction authorization was delayed and submitted later due to temporary issues like connectivity problems or offline environments.
|
| xInstallments | Only when xRecurringIndicator=Installment | Specifies the number of payment installments |
| xSplitInstruction | Object | Array of objects containing split
funding instructions. Each object
must include xMid (merchant ID)
and xAmount (amount to direct to
that merchant). The sum of all split
amounts must equal the total
transaction amount.
|
{% tabs %}
{% tab title="200: OK " %}
For a full list of response codes, see the [table](https://docs.solapayments.com/#triggers) in the Introduction page.
```json
{
"xResult":"A",
"xStatus":"Approved",
"xError":"",
"xErrorCode":"00000",
"xRefNum":"601518451",
"xInvoice":"123456",
"xExp":"1030",
"xAuthCode":"11295A",
"xBatch":"11948741",
"xAvsResultCode":"NNN",
"xAvsResult":"Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode":"M",
"xCvvResult":"Match",
"xAuthAmount":"35.00",
"xMaskedCardNumber":"4xxxxxxxxxxx1111",
"xCardType":"Visa",
"xToken":"8n21126mq0hn253p9m7964p5qn60000g",
"xMID":"xxxxxxxxxx9999",
"xTID":"xxxxx6789",
"xCurrency":"USD",
"xDate":"3/3/2022 7:36:34 AM",
"xEntryMethod":"Keyed",
"xReviewed":"N"
}
```
{% endtab %}
{% endtabs %}
{% code title="Sale - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xExp": "1030",
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:sale",
"xAmount": "35.00",
"xToken": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
"xCustom01": "Register01",
"xCVV": "123",
"xStreet": "123 Main Street",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xDUKPT": "Example",
"xDigitalWalletType": "Google Pay",
"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": "11111",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"x1Description": "Wireless Bluetooth Speaker",
"x1Sku": "12345",
"x1Qty": "5",
"x1UnitPrice": "49.99",
"xHotelCheckInDate": "7/1/2024",
"xHotelCheckOutDate": "7/10/2024",
"xHotelChargeType": "Direct",
"xHotelRoomRate": "159.99",
"xHotelNoShow": "TRUE",
"xAllowPartialAuth": "TRUE",
"xAllowNonAuthenticated": "FALSE",
"xRxAmount": "1.50",
"xDentalAmount": "1.50",
"xVisionAmount": "1.50",
"xTransitAmount": "1.50",
"xCopayAmount": "1.50",
"xClinicalAmount": "1.50",
"xOrderId": "12356",
"xExistingCustomer": "TRUE",
"xAllowDuplicate": "TRUE",
"xCustReceipt": "TRUE",
"xCurrency": "USD",
"xTimeoutSeconds": "10",
"xVendorId": "12345",
"xInstallments": "5",
"xSplitInstruction": [
{
xAmount:1.1,
xMid: "123"
},
{
xAmount:.4,
xMid: "456"
}
]
}
```
{% endcode %}
### AuthOnly
`POST` `cc:authonly`
`xCommand` = `cc:AuthOnly`
\
The AuthOnly command authorizes an amount on a cardholder’s account and places a hold on the available credit for that amount, but does not submit the charge for settlement. AuthOnly is used to reserve funds from a cardholder’s credit limit for a sale that is not ready to be processed. AuthOnly is commonly used when an order is placed on a website prior to the order being shipped, or when a customer makes a hotel or car rental reservation. If the authorization amount exceeds the cardholder’s available credit, a rejected response will be returned. When successful, the authorization number is returned as RefNum and can be used to reference the authorization for a follow-up transaction. The funds will remain held until the authorization is either captured, voided, or expires. To settle an AuthOnly transaction and complete the sale, use the [capture](https://kb.cardknox.com/api/#CREDIT_CARD_Capture) command. If an AuthOnly transaction is captured after 24 hours, it may be subject to a higher processing rate by the acquiring bank.
An AuthOnly hold only reduces the cardholder’s credit limit; it will not appear as a charge on their account. If the authorization will not be converted to a charge, [Void Release](https://kb.cardknox.com/api/#CREDIT_CARD_Void_Release) can be used to release the hold prior to the expiration. The expiration timeframe varies by the issuer, but is typically 7-30 days for credit cards and 3-5 days for debit cards.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| 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.` |
| 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. |
| xToken | String | The Sola token that references a previously used payment method. When using a token, `xCardNum` `xExp` and `xMagstripe` should not be used. |
| xCustom01 | String | 20 custom fields are available for custom data such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
| xCVV | String | 3-digit code from the back of the card (4-digit code from the front of the card for Amex) |
| xStreet | String | The billing street address of the cardholder |
| xZip | String | The billing zip code of the cardholder |
| 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 |
| 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. |
| 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) |
| xRequireSplitCapturable | String | Indicate if you want to ensure that the authorization will allow split capture. When this is set to true and split capture is not supported, an error will be returned “Split capture not supported“. |
| 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 optionally passed along to the receipt |
| xDescription | String | Additional data optionally passed along for reporting |
| xIP | String | The customer’s IP address. Typically used for fraud detection. |
| xEmail | String | The customer’s email address |
| xBillLastName | String | The customer’s last/family name for their billing profile |
| xBillMiddleName | String | The customer’s middle name or initial for their billing profile |
| xBillFirstName | String | The customer’s first name for their billing profile |
| xFax | String | The customer’s fax number |
| 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 |
| xShipCountry | 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 |
| xHotelCheckInDate | String | The customer’s date of hotel check-in. |
| xHotelCheckOutDate | String | The customer’s date of hotel check-out. |
| xHotelChargeType | String | The charge type for the transaction. |
| xHotelRoomRate | String | The nightly room rate for the hotel. |
| xHotelNoShow | String | True/False indicating whether customer was a no-show. |
| xAllowPartialAuth | String | True/False value indicating if an authorization amount is less than the initial request when the full initial amount is unavailable. This variable is platform-dependent. Default is false. |
| xAutoRentalPickupDate | String | Specific date for customer to pick up vehicle.
\*Note: This field is required only for the auto rental industry.
|
| xAutoRentalPickupTime | String | Specific time for customer to pick up vehicle.
\*Note: This field is required only for the auto rental industry.
|
| xAutoRentalReturnDate | String | Specific date for customer to return vehicle.
\*Note: This field is required only for the auto rental industry.
|
| xAutoRentalReturnTime | String | Specific time for customer to return vehicle.
\*Note: This field is required only for the auto rental industry.
|
| xRxAmount | String | Specifies qualifying prescription amount for FSA transactions. xAllowPartialAuth must be set to True.
|
| xDentalAmount | String | Specifies qualifying dental amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xVisionAmount | String | Specifies qualifying vision amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xTransitAmount | String | Specifies qualifying transit amount for commuter card transactions. `xAllowPartialAuth` must be set to True. |
| xCopayAmount | String | Specifies Co-pay amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xClinicalAmount | String | Specifies qualifying clinical amount for FSA transactions. `xAllowPartialAuth` must be set to True. |
| xOrderId | String | Unique order number for FraudWatch verification. |
| xAllowDuplicate | String | By default, Sola rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
| xCustReceipt | String | True/False value indicating if the email address specificied in `xemail` should receive a receipt containing the transaction details. |
| xCurrency | String | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (see list of all supported currencies).
|
| xTimeoutSeconds | String | Configurable amount of seconds in which the request will wait for a response. |
| xRecurringIndicator\* | String | Recurring- a transaction that is part of a regularly scheduled series (e.g., subscriptions). Usually initiated by the merchant after the first payment.
Installment- one in a series of transactions where the total amount is divided into multiple payments with a fixed schedule (e.g., 3 monthly payments).
Single- a one-time transaction, not part of a recurring or installment plan.
Deferred- indicates that the transaction authorization was delayed and submitted later due to temporary issues like connectivity problems or offline environments.
\*Required for Merchant-initiated transactions
|
{% tabs %}
{% tab title="200: OK " %}
For a full list of response codes, see the [table](https://docs.solapayments.com/#triggers) in the Introduction page.
```javascript
{
"xResult":"A",
"xStatus":"Approved",
"xError":"",
"xErrorCode":"00000",
"xRefNum":"601519890",
"xInvoice":"123456",
"xExp":"1030",
"xAuthCode":"47436A",
"xAvsResultCode":"NNN",
"xAvsResult":"Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode":"M",
"xCvvResult":"Match",
"xAuthAmount":"35.00",
"xMaskedCardNumber":"4xxxxxxxxxxx1111",
"xCardType":"Visa",
"xName":"John Doe",
"xToken":"q3nq31h6n8n24623n9qg695hhgh24g61",
"xMID":"xxxxxxxxxx9999",
"xTID":"xxxxx6789",
"xCurrency":"USD",
"xDate":"3/3/2022 7:43:21 AM",
"xIsSplitCapturable":"1",
"xEntryMethod":"Keyed",
"xReviewed":"N"
}
```
{% endtab %}
{% endtabs %}
{% code title="AuthOnly - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xExp": "1030",
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:authonly",
"xAmount": "35.00",
"token": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
"xCustom01": "Register01",
"xCVV": "123",
"xStreet": "123 Main Street",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xDUKPT": "0123456789ABCDEFFEDCBA9876543210",
"xTax": "2.00",
"xTip": "2.00",
"xRequireSplitCapturable": "TRUE",
"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": "11111",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xHotelCheckInDate": "7/1/2024",
"xHotelCheckOutDate": "7/10/2024",
"xAllowPartialAuth": "TRUE",
"xAutoRentalPickupDate": "2020-08-21",
"xAutoRentalPickupTime": "11:15:00",
"xAutoRentalReturnDate": "2020-08-21",
"xAutoRentalReturnTime": "11:15:00",
"xRxAmount": "1.50",
"xDentalAmount": "1.50",
"xVisionAmount": "1.50",
"xTransitAmount": "1.50",
"xCopayAmount": "1.50",
"xClinicalAmount": "1.50",
"xOrderId": "12356",
"xAllowDuplicate": "TRUE",
"xCustReceipt": "TRUE",
"xCurrency": "USD",
"xTimeoutSeconds": "10"
}
```
{% endcode %}
### Capture
`POST` `cc:capture`
`xCommand` = `cc:Capture`\
\
The Capture command is used to settle funds from a previous authorization and withdraw the funds from the cardholder’s account. The RefNumber from the associated authorization is required when submitting a Capture request. To perform an authorization and capture in the same command, use the **Sale** command.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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 |
| xRefNum\* | String | Used to reference a previous transaction when doing 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). |
| 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.` |
| xStreet | String | The billing street address of the cardholder. |
| xZip | String | The billing zip code of the cardholder. |
| 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 optionally passed along to the receipt |
| xDescription | String | Additional data 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 for their billing profile |
| xBillLastName | String | The customer’s last 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 for their shipping profile |
| xShipLastName | String | The customer’s last 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. |
| xCustReceipt | String | True/False value indicating if the email address specified in `xemail` should receive a receipt containing the transaction details. |
{% tabs %}
{% tab title="200: OK " %}
For a full list of response codes, see the [table](https://docs.solapayments.com/#triggers) in the Introduction page.
```javascript
{
"xResult":"E",
"xStatus":"Error",
"xError":"Invalid xRefNum",
"xErrorCode":"01463",
"xRefNum":"601523283",
"xInvoice":"123456",
"xDate":"3/3/2022 7:57:59 AM"
}
```
{% endtab %}
{% endtabs %}
{% code title="Capture - Request Payload Example" %}
```json
{
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:capture",
"xAmount": "35.00",
"xCustom01": "Register01",
"xCVV": "123",
"xStreet": "123 Main Street",
"xZip": "12345",
"xRefNum": "81234568",
"xName": "John Doe",
"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": "11111",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xAllowDuplicate": "TRUE",
"xCustReceipt": "TRUE"
}
```
{% endcode %}
### SplitCapture
`POST` `cc:splitcapture`
`xCommand` = `cc:splitcapture`
The SplitCapture command is used to capture funds in multiple stages from a single authorization. This is useful for scenarios where the total transaction amount is not settled all at once, such as partial shipments or staged payments. Each SplitCapture request requires the xRefNum of the authorization and allows capturing different amounts up until the authorized amount. See [split capture documentation](https://docs.solapayments.com/products/split-capture) for more information.
| **xKey**\* | String | Your Sola API key |
| ------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **xVersion**\* | String | Gateway API Version. The current version is 5.0.0. |
| **xCommand**\* | String | Sola transaction type |
| **xSoftwareName**\* | String | Name of your software |
| **xSoftwareVersion**\* | String | Version number of your software |
| **xRefNum**\* | String | Used to reference a previous transaction when doing 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). |
| **xAmount**\* | String | The portion of the authorized funds to capture in the current SplitCapture request. |
| **xCustom01** | String | 20 custom fields are available for custom data such as customer comments, etc. Use `xCustom01` through `xCustom20`. |
| **xStreet** | String | The billing street address of the cardholder. |
| **xZip** | String | The billing zip code of the cardholder. |
| **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 optionally passed along to the receipt |
| **xDescription** | String | Additional data 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. |
| **xCustReceipt** | String | True/False value indicating if the email address specified in `xemail` should receive a receipt containing the transaction details. |
{% code title="Capture - Response Payload" %}
```json
{
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:splitcapture",
"xRefNum": "81234568",
"xAmount": "9.99",
"xCustom01": "Register01",
"xStreet": "123 Main Street",
"xZip": "12345",
"xName": "John Doe",
"xTax": ".05",
"xTip": ".05",
"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": "11111",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xAllowDuplicate": "TRUE",
"xCustReceipt": "TRUE"
}
```
{% endcode %}
{% code title="SplitCapture - Response Payload" %}
```json
{
"xResult":"A",
"xStatus":"Approved",
"xError":"",
"xErrorCode":"00000",
"xRefNum":"10230508134",
"xInvoice":"123456",
"xExp":"1030",
"xAuthCode":"74119A",
"xBatch":"5128394",
"xAvsResultCode":"NNN",
"xAvsResult":"Address:No Match & 5 Digit Zip: No Match",
"xCvvResultCode":"",
"xCvvResult":"No CVV data available",
"xAuthAmount":"10.00",
"xMaskedCardNumber":"4xxxxxxxxxxx1111",
"xCardType":"Visa",
"xToken":"h0n6m0gn70m99598hp282802h60q2911",
"xMID":"xxxxxxxxxx9999",
"xTID":"xxxxx6789",
"xCurrency":"USD",
"xDate":"1/29/2025 10:58:54 AM",
"xEntryMethod":"Unknown"
}
```
{% endcode %}
### Adjust
`POST` `cc:adjust`
`xCommand` = `cc:Adjust`
The Adjust command updates specific fields on an existing transaction.\
It can be used to:
* Update transaction details (such as xInvoice, xName or custom fields) before the transaction is captured, when the original transaction was either a cc:sale or a cc:authonly.
* Modify the authorized amount (xAmount) before the transaction is captured, when the original transaction was a cc:authonly. These situations occur when the final transaction amount is not known at the time of authorization and must be increased prior to settlement.
* Common Use Cases:
* **Restaurant**: $85 → $105 (tip added)
* **Hotel**: $500 → $575 (incidental charges)
* **Grocery Delivery**: $120 → $134 (weighted items)
* **Car Rental**: $1,050 (rental extension)
* **Fuel Station**: $100 → $128 (final pump total)
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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.
If the amount in the cc:Adjust transaction differs from the original authorization amount, the request should include "xIncremental": "true".
If xIncremental is not set to true when adjusting to a different amount, the transaction may be treated as a forced transaction, which could increase chargeback risk and liability.
|
| xRefNum\* | String | Used to reference a previous transaction when doing 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). |
| Custom01 | String | Custom fields available for custom data such as customer comments, etc. |
| Custom02 | String | Custom fields available for custom data such as customer comments, etc. |
| Custom03 | String | Custom fields available for custom data such as customer comments, etc. |
| xStreet | String | The billing street address of the cardholder |
| xZip | String | The billing zip code of the cardholder |
| xName | String | The cardholder’s name |
| xDescription | String | Additional data optionally passed along for reporting |
| xOrderId | String | Unique Order Number for FraudWatch verification |
| xTip | String | The tip portion that is included in the total transaction amount (xAmount) |
| xTax | String | The tax portion that is included in the total transaction amount (xAmount) |
| xSignature | String | The Base 64 encoded customer signature |
| xInvoice | String | The merchant’s invoice number for the transaction. `xInvoice` is recommended when available for improved duplicate handling |
| xIncremental | String | Incremental authorizations enable increase the authorized amount on a captured transaction. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016879",
"xInvoice": "1234567",
"xRefNumCurrent": "10000016886",
"xDate": "7/11/2022 4:06:11 PM"
}
```
{% endtab %}
{% endtabs %}
{% code title="Adjust - Request Payload Example" %}
```json
{
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:adjust",
"xAmount": "35.00",
"xCustom01": "Register01",
"xCustom02": "Register01",
"xCustom03": "Register01",
"xStreet": "123 Main Street",
"xZip": "12345",
"xRefNum": "81234568",
"xName": "John Doe",
"xDescription": "This is a description",
"OrderID": "123456",
"xTip": "1.05",
"xTax": "1.05",
"xSignature": "aGVsbG8gaG93IGFyZSB5b3UK",
"xInvoice": "123456A",
"xIncremental": "TRUE"
}
```
{% endcode %}
### Save
`POST` `cc:save`
`xCommand` = `cc:Save`\
The Save command is used to send account information and to request a token from Sola. It does not submit the transaction for processing. The response returns a token that references the account information. A token at minimum references the credit card number, but if other data is sent—such as a billing address—it will be associated with the token as well.
**AvsOnly**\
When **AvsOnly** is enabled for `cc:Save`, in addition to just generating a token, the transaction will be submitted to the bank for AVS and CVV verification. This setting can be turned on in the Sola backend settings.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| 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` |
| xKey\* | String | Your Sola API key. |
| xVersion\* | String | Gateway API version. The current version is 5.0.0. |
| xSoftwareName\* | String | Name of your software |
| xCommand\* | String | Sola transaction type |
| xSoftwareVersion\* | String | Version number of your software |
| xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
| xStreet | String | The billing street address of the cardholder |
| xZip | String | The billing zip code of the cardholder |
| 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. |
| xIP | String | The customer’s IP address. Typically used for fraud detection. |
| xCVV | String | 3-digit code from the back of the card (for Amex, 4-digit code from the front of the card) |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016898",
"xExp": "1030",
"xDate": "7/11/2022 4:15:15 PM",
"xToken": "38gn292893h0nq72m0qn69892q9mg56g",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa"
}
```
{% endtab %}
{% endtabs %}
{% code title="Save - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xExp": "1249",
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:save",
"xCustom01": "Register01",
"xStreet": "123 Main Street",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xIP": "1.1.1.1"
}
```
{% endcode %}
### AvsOnly ($0 Auth)
`POST` `cc:avsonly`
`xCommand` = `cc:AvsOnly`\
\
An AVS Only transaction allows you to verify the accuracy of a customer's billing address without processing the payment. This type of transaction is useful for validating the authenticity of the billing address before completing a purchase. It can also be use to verify the card CVV
To perform an AVS Only transaction, you need to send the customer's billing address details along with the request. The bank will then compare the provided address against the billing address on file with the card issuer and return a response indicating whether the address matches or not.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| 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` |
| xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
| 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 |
| 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 |
| xIP | String | The customer’s IP address. Typically used for fraud detection. |
| xCVV | String | 3-digit code from the back of the card (for Amex, 4-digit code from the front of the card) |
### Credit
`POST` `cc:credit`
`xCommand` = `cc:Credit`
To issue a credit (refund) through our API without referring to a previous sale, you can use the following command: `cc:credit`
\
Please note that our system blocks credits on cards that do not have a prior sale by default. To allow such credits to go through, you must send a request to .
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xCardNum\* | String | The customer card number. \*Alternatively, `xToken` `xMagStripe` or `SUT` can be used. |
| 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. |
| 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 payment method. When using a token, `xCardNum` `xExp` and `xMagstripe` should not be 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 |
| 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 |
| 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. |
| 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 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 |
| xOrderId | String | Unique order number for FraudWatch verification |
| xExistingCustomer | String | Yes/No value indicating if the customer is a repeat customer |
| xAllowDuplicate | String | By default, Sola rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
| xCustReceipt | String | True/False value indicating if the email address specified in `xemail` should receive a receipt containing the transaction details. |
| xCurrency | String | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (see list of all supported currencies).
|
| xTimeoutSeconds | String | Configurable amount of seconds in which the request will wait for a response. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016908",
"xInvoice": "123456",
"xExp": "1030",
"xAuthCode": "78685A",
"xBatch": "14594556",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "M",
"xCvvResult": "Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xToken": "n701mmg5qm3969673q92hm0p652h2n9g",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:21:17 PM",
"xEntryMethod": "Keyed"
}
```
{% endtab %}
{% endtabs %}
{% code title="Credit - Request Payload Example" %}
```json
{
"xCardNum": "4444333322221111",
"xExp": "1030",
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:credit",
"xAmount": "35.00",
"token": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
"xCustom01": "Register01",
"xCVV": "123",
"xStreet": "123 Main Street",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xDUKPT": "0123456789ABCDEFFEDCBA9876543210",
"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": "11111",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xAllowPartialAuth": "TRUE",
"xRxAmount": "1.50",
"xDentalAmount": "1.50",
"xVisionAmount": "1.50",
"xTransitAmount": "1.50",
"xCopayAmount": "1.50",
"xClinicalAmount": "1.50",
"xOrderId": "12356",
"xExistingCustomer": "TRUE",
"xAllowDuplicate": "TRUE",
"xCustReceipt": "TRUE",
"xCurrency": "USD",
"xTimeoutSeconds": "10"
}
```
{% endcode %}
### Refund
`POST` `cc:refund`
`xCommand` = `cc:Refund`\
\
The Refund command is used to refund a full or partial amount of a previous transaction using `xRefNum`. Partial check refunds are only supported for ACHQ.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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 |
| 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). |
| xAmount | String | Refund amount. Can be equal or less than the original transaction. |
| xAllowDuplicate | String | By default, Sola rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
| xDescription | String | Additional data optionally passed along for reporting |
| xCustReceipt | String | True/False value indicating if the email address specified in `xemail` should receive a receipt containing the transaction details |
| xTimeoutSeconds | String | Configurable amount of seconds in which the request will wait for a response. |
| xSplitInstruction | Object | Array of objects containing split funding instructions for the refund.
Each object must include xMid (merchant ID) and xAmount (amount to refund from that merchant). The sum of all split amounts must equal the total refund amount.
|
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016913",
"xInvoice": "123456",
"xExp": "1030",
"xAuthCode": "41174A",
"xBatch": "14594556",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "N",
"xCvvResult": "No Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:27:32 PM",
"xEntryMethod": "Unknown"
}
```
{% endtab %}
{% endtabs %}
{% code title="Refund - Request Payload Example" %}
```json
{
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:refund",
"xAmount": "35.00",
"xRefNum": "93827163",
"xDescription": "This is a description",
"xAllowDuplicate": "TRUE",
"xCustReceipt": "FALSE",
"xCurrency": "USD",
"xTimeoutSeconds": "10",
"xSplitInstruction": [
{
xAmount:1.1,
xMid: "123"
},
{
xAmount:.4,
xMid: "456"
}
]
}
```
{% endcode %}
### VoidRefund
`POST` `cc:voidrefund`
`xCommand` = `cc:voidrefund`
The VoidRefund command will either void the pending transaction if it has not settled yet, or it will fully refund the transaction if it has already settled.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 |
| 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). |
| xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016915",
"xInvoice": "123456",
"xRefNumCurrent": "10000016916",
"xExp": "1030",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "N",
"xCvvResult": "No Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xToken": "h9n16qg990p99157640h6m823942934p",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:30:38 PM",
"xEntryMethod": "Unknown"
}
```
{% endtab %}
{% endtabs %}
{% code title="VoidRefund - Request Payload Example" %}
```json
{
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:voidrefund",
"xCustom01": "Register01",
"xRefNum": "93827163"
}
```
{% endcode %}
### VoidRelease
`POST` `cc:voidrelease`
`xCommand` = `cc:voidrelease`\
\
The VoidRelease command releases a pending authorization amount back to the cardholder’s credit limit without waiting for the standard authorization time frame to expire.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 |
| 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). |
| xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016917",
"xInvoice": "123456",
"xRefNumCurrent": "10000016919",
"xExp": "1030",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "N",
"xCvvResult": "No Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:33:02 PM",
"xEntryMethod": "Unknown"
}
```
{% endtab %}
{% endtabs %}
{% code title="VoidRelease - Request Payload Example" %}
```json
{
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:voidrelease",
"xCustom01": "Register01",
"xRefNum": "93827163"
}
```
{% endcode %}
### Void
`POST` `cc:void`
`xCommand` = `cc:Void`\
\
The Void command voids a transaction that has not yet settled using `xRefNum`.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 |
| 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). |
| xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use `xCustom01` through `xCustom20.` |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016875",
"xInvoice": "123456",
"xRefNumCurrent": "10000016882",
"xExp": "1030",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "N",
"xCvvResult": "No Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:03:04 PM",
"xEntryMethod": "Unknown"
}
```
{% endtab %}
{% endtabs %}
{% code title="Void - Request Payload Example" %}
```json
{
"xKey": "[xkeycredentials]",
"xVersion": "5.0.0f",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "cc:void",
"xCustom01": "Register01",
"xRefNum": "93827163"
}
```
{% endcode %}
---
# Agent Instructions: 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/credit-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.