---
title: "Start mobile sale transaction"
method: POST
path: "/rest/v2/mobile/transactions/sale"
tags: ["Mobile Transactions"]
---

# Start mobile sale transaction

`POST /rest/v2/mobile/transactions/sale`

## Request

- The document declares no server URL.
- Auth: none declared. Required headers: `api-key`, `mobilejwt`
- TypeScript: <https://skmtc.dev/xplorpay/apis/external-us-onboarding-workflow/docs/rest/v2/mobile/transactions/sale/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a mobile sale transaction using a mobile transaction token that involves authorization and capture. Transactions of $1.00 or greater are approved and automatically added to the open batch for settlement.

## Request body

- ClearentGatewayRequest
  - `type` 'AUTH,SALE,FORCED SALE,REFUND (unmatched only)', required: Type of transaction.
  - `card` string: Credit card number.
  - `amount` string, required: Total transaction amount.
  - `id` string: Unique identifier for the transaction request.
  - `billing` Address: Contains the customer's billing address details.
    - `company` string: Company name associated with the billing address.
    - `street` string: Primary street address for the billing.
    - `street2` string: Secondary street address information, if available.
    - `city` string: City associated with the billing address.
    - `state` string: State or province of the billing address.
    - `zip` string: ZIP or postal code of the billing address.
    - `country` string: Country of the billing address.
    - `phone` string: Phone number associated with the billing address.
    - `first-name` string: First name of the billing contact.
    - `last-name` string: Last name of the billing contact.
  - `shipping` Address: Contains the customer's billing address details.
    - `company` string: Company name associated with the billing address.
    - `street` string: Primary street address for the billing.
    - `street2` string: Secondary street address information, if available.
    - `city` string: City associated with the billing address.
    - `state` string: State or province of the billing address.
    - `zip` string: ZIP or postal code of the billing address.
    - `country` string: Country of the billing address.
    - `phone` string: Phone number associated with the billing address.
    - `first-name` string: First name of the billing contact.
    - `last-name` string: Last name of the billing contact.
  - `csc` string: Card Security Code (CVV).
  - `invoice` string: Invoice number for the transaction.
  - `description` string: Description of the transaction
  - `comments` string: Additional comments related to the transaction.
  - `software-type` string, required: Type of software initiating the transaction.
  - `software-type-version` string, required: Version of the software used.
  - `sales-tax-type` 'LOCAL_SALES_TAX,TAX_EXEMPT': Type of sales tax.
  - `sales-tax-amount` string: Amount of sales tax applied.
  - `service-fee` string: Additional service fee.
  - `signature-base-64-image` string: Base64-encoded signature image.
  - `tip-amount` string: Tip amount included in the transaction.
  - `authorization-code` string: Code used to authorize the transaction.
  - `purchase-order` string: Purchase order number.
  - `email-receipt` string: Indicates if a receipt should be emailed.
  - `email-address` string: Email address of the customer.
  - `customer-id` string: Identifier for the customer.
  - `order-id` string: Unique identifier for the order.
  - `client-ip` string: IP address of the client initiating the transaction.
  - `billing-is-shipping` string: Indicates if billing and shipping addresses are the same.
  - `create-token` string: Indicates if a token should be created for future use.
  - `token-description` string: Description for the token if created.
  - `check-field` string: Field to be checked for validation.
  - `check-field-mid` boolean: Validates MID (Merchant ID) field.
  - `platform-fees` PlatformFee[]: List of platform fees applied to the transaction.
    - `fee-name` 'DealManager' | 'FillMyBook': The name of the fee applied to the transaction.
  - `card-inquiry` boolean: If true, performs a card inquiry.
  - `level3` Level3: Level 3 data for enhanced transaction details.
    - `vat-tax-amount` string: The VAT amount applied to the transaction.
    - `vat-tax-rate` string: VAT tax rate applied to the transaction.
    - `order-date` string: The date when the order was created.
    - `customer-vat-registration-number` string: Cardholder's VAT registration number.
    - `summary-commodity-code` string: Code that identifies the type of service included in the transaction.
    - `discount-amount` string: Total discount amount.
    - `destination-country-code` string: The ISO country code of the destination.
    - `freight-amount` string: Freight charges.
    - `duty-amount` string: Duty amount applied.
    - `level3-items` Level3Items: Level 3 line-item data for the transaction.
      - `level3-items` Level3Item[]
        - `item-description` string: Description of the item.
        - `item-commodity-code` string: Commodity code of the item.
        - `item-quantity` string: Quantity of items comprising of the order.
        - `item-unit-of-measure` string: The unit of measure of the purchased item as determined by ANSI X-12. Allowable Units of Measure and Codes.
        - `item-unit-cost` string: Per item cost for the order.
        - `item-product-code` string: Merchant identifiable code e.g., SKU or Model Number.
        - `item-tax-amount` string: Tax amount per item.
        - `item-tax-rate` string: Tax rate per item expressed as a decimal.
        - `item-discount` string: Discount amount applied per item.
        - `item-line-total` string: Total item count for the order.
        - `item-net-gross-ind` string: Indicated where the extended item amount is included in the tax. Can either be Yes ("Y") or No ("N") but should be passed as "N".
        - `item-discount-rate` string: Discount rate applied per item expressed as a decimal.
  - `secure3d` string: 3D Secure authentication data.
  - `secure3d-eci` string: Electronic Commerce Indicator for 3D Secure.
  - `add-tax-to-amount` boolean: Indicates whether sales tax should be added to the total amount used for authorization and capture

## Response `200`

Successful Transaction

- Transaction: Contains all details related to the authorized transaction.
  - `amount` string: Total value associated with the transaction.
  - `currency` string: Currency used for the transaction.
  - `id` string: Unique transaction ID.
  - `invoice` string: Invoice number associated with the transaction.
  - `description` string: Description of the transaction.
  - `comments` string: Comments associated with the transaction.
  - `serverId` string
  - `created` string: Date and time when the transaction was created.
  - `type` 'AUTH' | 'SALE' | 'REFUND' | 'VOID' | 'CAPTURE' | 'FORCED SALE' | 'CARD INQUIRY': Identifies the transaction type.
  - `result` 'APPROVED' | 'DECLINED' | 'ERROR': Result of the transaction. For example, APPROVED.
  - `billing` Address: Contains the customer's billing address details.
    - `company` string: Company name associated with the billing address.
    - `street` string: Primary street address for the billing.
    - `street2` string: Secondary street address information, if available.
    - `city` string: City associated with the billing address.
    - `state` string: State or province of the billing address.
    - `zip` string: ZIP or postal code of the billing address.
    - `country` string: Country of the billing address.
    - `phone` string: Phone number associated with the billing address.
    - `first-name` string: First name of the billing contact.
    - `last-name` string: Last name of the billing contact.
  - `shipping` Address: Contains the customer's billing address details.
    - `company` string: Company name associated with the billing address.
    - `street` string: Primary street address for the billing.
    - `street2` string: Secondary street address information, if available.
    - `city` string: City associated with the billing address.
    - `state` string: State or province of the billing address.
    - `zip` string: ZIP or postal code of the billing address.
    - `country` string: Country of the billing address.
    - `phone` string: Phone number associated with the billing address.
    - `first-name` string: First name of the billing contact.
    - `last-name` string: Last name of the billing contact.
  - `card` string: Card number used for the transaction.
  - `csc` string: Card Security Code used.
  - `cvm` 'NON (None)' | 'MSG(Manual Signature)' | 'OFC(Offline Pin in the Clear)' | 'PIN(Online Pin)' | 'OFE(Offline Encrypted Pin)': Cardholder Verification Method used.
  - `action` Action: The transaction action performed.
    - `url` string: URL endpoint used for the transaction.
    - `method` string: Method used for the transaction. For example, POST, GET.
    - `type` string: Type of transaction. For example, SALE.
    - `environment` string: Environment in which the transaction was processed. For example, production, test.
    - `locale` string: Locale setting used during the transaction.
    - `data` object: Additional data properties related to the action.
    - `payment-method-type` string: Type of payment method used. For example, card, wallet.
    - `sub-type` string: Sub-category of the transaction type.
    - `client-key` string: Key identifying the client initiating the transaction.
    - `qr-code-data` string: Data encoded in the QR code for the transaction.
  - `authorization-code` string: Code indicating the transaction authorization.
  - `avs-result-code` 'X' | 'Y' | 'A' | 'W' | 'Z' | 'N' | 'U' | 'R' | 'S' | 'G': Result code from Address Verification Service.
  - `avs-result-code-description` string: Description of the AVS result.
  - `csc-result-code` 'M' | 'N' | 'P' | 'S' | 'U' | 'X': Result code from CSC verification.
  - `csc-result-code-description` string: Description of the CSC result.
  - `tip-adjusted-amount` string: Amount of the adjusted tip.
  - `avs-street` string: Street used in AVS check.
  - `avs-zip` string: ZIP code used in AVS check.
  - `token-description` string: Description of the token created.
  - `original-amount` string: Original amount before adjustments.
  - `tip-amount` string: Tip amount included in the transaction.
  - `ref-id` string: Reference ID for the transaction.
  - `entry-method` string: Method used to enter payment data of the transaction. For example, Swipe/Manual.
  - `first-recurring-transaction` string: Indicates whether this is the first recurring transaction.
  - `batch-string-id` string: Identifies the settlement batch ID.
  - `order-id` string: Order id passed in with the transaction.
  - `purchase-order` string: Purchase order number.
  - `customer-id` string: Customer id passed in with the transaction.
  - `email-address` string: Email address associated with the transaction.
  - `display-message` string: Displayable message about transaction result.
  - `result-code` string: Result code associated with transaction result.
  - `billing-is-shipping` string: Indicates if billing and shipping addresses are the same.
  - `tip-adjusted` string: Indicates if the tip was adjusted.
  - `exp-date` string: Expiration date of the card.
  - `client-ip` string: IP address of the client initiating the transaction.
  - `voided` string: Indicates if the transaction was voided.
  - `pending` string: Indicates if the transaction is pending.
  - `voided-auth` string: Indicates if the authorization was voided.
  - `settled` string: Indicates if the transaction has been settled.
  - `status` string: Status of the transaction. For example, approved.
  - `emv-data` string: Raw EMV data string.
  - `key-serial-number` string: Serial number of the encryption key used.
  - `emv-entry-method` 'EMV_DIP' | 'EMV_CONTACTLESS' | 'EMV_FALLBACK_SWIPE' | 'EMV_FALLBACK_NONTECH': Method used to enter EMV data.
  - `software-type` string: Type of software used for the transaction.
  - `customer-first-name` string: First name of the customer.
  - `customer-last-name` string: Last name of the customer.
  - `plan-name` string: Name of the payment plan used.
  - `card-type` string: Type of card used. For example, VISA.
  - `contactless` string: Indicates if contactless payment was used.
  - `contactless-device` string: Indicates if a contactless device was used.
  - `sales-tax-type` string: Type of sales tax applied.
  - `sales-tax-amount` string: Amount of sales tax applied.
  - `add-tax-to-amount` boolean: Indicates if tax was added to the transaction amount.
  - `emv-data-response` string: Response data from EMV processing.
  - `emv` Emv: EMV chip data related to the transaction.
    - `application-name` string: The name of the EMV application used to process the transaction.
    - `application-id` string: The unique identifier of the application.
    - `terminal-verification-results` string: Results of terminal-level verification during the transaction.
    - `transaction-status-information` string: Status details that describes the processing state of the transaction.
    - `iad` string: IAD provided by the card issuer during the authorization.
    - `transaction-certificate` string: A certificate generated during the transaction processing.
    - `application-transaction-counter` string: A counter that increments with each transaction.
  - `signature-base-64-image` string: Base64-encoded image of the signature.
  - `last-four` string: Last four digits of the card number.
  - `check-field-duplicate` boolean: Indicates if a duplicate check was performed.
  - `service-fee` string: Service fee applied to the transaction
  - `base-amount` string: Base amount before taxes and fees.
  - `platform-fees` PlatformFee[]: List of platform fees applied.
    - `fee-name` 'DealManager' | 'FillMyBook': The name of the fee applied to the transaction.
  - `merchant-id` string: Identifier for the merchant.
  - `terminal-id` string: Identifier for the terminal used.
  - `surcharge-applied` boolean: Indicates if a surcharge was applied.
  - `level3` Level3: Level 3 data for enhanced transaction details.
    - `vat-tax-amount` string: The VAT amount applied to the transaction.
    - `vat-tax-rate` string: VAT tax rate applied to the transaction.
    - `order-date` string: The date when the order was created.
    - `customer-vat-registration-number` string: Cardholder's VAT registration number.
    - `summary-commodity-code` string: Code that identifies the type of service included in the transaction.
    - `discount-amount` string: Total discount amount.
    - `destination-country-code` string: The ISO country code of the destination.
    - `freight-amount` string: Freight charges.
    - `duty-amount` string: Duty amount applied.
    - `level3-items` Level3Items: Level 3 line-item data for the transaction.
      - `level3-items` Level3Item[]
        - `item-description` string: Description of the item.
        - `item-commodity-code` string: Commodity code of the item.
        - `item-quantity` string: Quantity of items comprising of the order.
        - `item-unit-of-measure` string: The unit of measure of the purchased item as determined by ANSI X-12. Allowable Units of Measure and Codes.
        - `item-unit-cost` string: Per item cost for the order.
        - `item-product-code` string: Merchant identifiable code e.g., SKU or Model Number.
        - `item-tax-amount` string: Tax amount per item.
        - `item-tax-rate` string: Tax rate per item expressed as a decimal.
        - `item-discount` string: Discount amount applied per item.
        - `item-line-total` string: Total item count for the order.
        - `item-net-gross-ind` string: Indicated where the extended item amount is included in the tax. Can either be Yes ("Y") or No ("N") but should be passed as "N".
        - `item-discount-rate` string: Discount rate applied per item expressed as a decimal.
  - `partial-authorization` boolean: Indicates if partial authorization was allowed.
  - `partial-approved` boolean: Indicates if the transaction was partially approved.
  - `additional-amounts` AdditionalAmount[]: List of additional amounts applied to the transaction.
    - `amount` string: Amount of transaction.
    - `account-type` string: Account type of transaction.
    - `amount-type` string: Refers to amount type of transaction.
  - `secure3d-eci` string: Electronic Commerce Indicator for 3D Secure.
  - `secure3d-result-code` string: Result code from 3D Secure authentication.
  - `total-amount` string: Total amount including all charges.
  - `processing-party-reference` string: Reference ID from the processing party.
  - `original-processing-party-reference` string: Reference of the original transaction assigned by the processing party.
  - `external-transaction-reference` string: External reference ID for the transaction.
  - `funding-reference` string: Reference for the funding transaction.
  - `token-id` string: Identifier of the payment token.
  - `network-transaction-reference` string: Reference ID from the payment network for the transaction.
  - `create-token` boolean: Indicates if a token should be created for the transaction.
  - `moto` boolean: Indicates whether the transaction is MOTO.
  - `issuer_id` string: Identifier for the card issuer.
  - `digital-wallet-type` string: Type of digital wallet used. For example, GOOGLE.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Business Exception (decline, etc)
- `500`: Internal server error

---

[API](https://skmtc.dev/xplorpay/apis/external-us-onboarding-workflow.md) - [All operations](https://skmtc.dev/xplorpay/apis/external-us-onboarding-workflow/llms.txt) - [OpenAPI document](https://skmtc.dev/xplorpay/apis/external-us-onboarding-workflow/revisions/f37077c24b66?raw)