Creates a transaction

Request

POST {{baseURL}}/pay-api/v1/transactions/sale

This endpoint completes a transaction in a single step.

It combines the two actions of authorizing and capturing a transaction into a single endpoint. Use this endpoint when the final amount is known and will not change. The transaction can be made immediately.

See Also:
To authorize a transaction, see POST /pay-api/v1/transactions/auth
To capture or complete a transaction, see POST {/pay-api/v1/transactions/capture
To settle a transaction, see POST /pay-api/v1/transactions/settle

Security

Bearer

Bodyapplication/json

amountnumber, (double)required

Specifies the amount of the transaction.

Example: 64.99

Example:64.99

cardDataSourceinteger, (int32)required

Specifies the card data source.

Possible values:

Value	Name	Description
1	Internet	Virtual Terminal, ISV API
2	Swipe	Track1, Track2
3	NFC	EMV Tags, Track2
4	EMV	EMV Tags
5	EMVContactless	EMV Tags
6	FallbackSwipe	Track 2
7	Manual	Card present keyed transaction

Example: 2

Example:2

currencyIdinteger, (int32)required

Specifies the Flute currency identifier.

Always set to 1.

Example: 1

Example:1

expirationMonthinteger, (int32)required

Specifies the expiration month of the card.

Example: 7

Example:7

expirationYearinteger, (int32)required

Specifies the expiration year of the card.

Example: 2032

Example:2032

deviceIdstring or null, (uuid)

Specifies the device when using the Flute mobile app.

If this value is included, the user is linked to that device. This stores their name as the transaction creator createdBy.

Example: a30f9b66-b2f0-4b18-a03a-b861b00afa8b

Example:"a30f9b66-b2f0-4b18-a03a-b861b00afa8b"

paymentProcessorIdstring or null, (uuid)

Specifies the payment processor identifier.

Example: 8ebb41c8-e1b0-4777-8f8e-1402e756ee7d

Example:"8ebb41c8-e1b0-4777-8f8e-1402e756ee7d"

customerIdstring or null, (uuid)

Specifies the customer identifier.

This is used when saving the payment method.
If this value is provided, the payment method is saved to the specified customer.
If this value is not provided, a new customer record is created.

Example: fd9198a4-eb6f-4620-9603-4f4638289de5

Example:"fd9198a4-eb6f-4620-9603-4f4638289de5"

paymentMethodIdstring or null, (uuid)

Specifies the customer payment method identifier.

We recommend using paymentMethodId instead of accountNumber.

Example: b4c48037-4c5d-4e6f-7a8b-9c0d1e2f3a69

Example:"b4c48037-4c5d-4e6f-7a8b-9c0d1e2f3a69"

accountNumberstring

Specifies the 13-19 digit card number used for the transaction.

We recommend using paymentMethodId instead of accountNumber

This field may contain a token issued against a card number. This is de-tokenized by TransIT to process the transaction.

tipAmountnumber or null, (double)

Specifies the absolute amount (in USD) of the tip to be added.

This amount adds to the base amount of the original transaction. That transaction must be authorized first.

Values for `tipAmount` and `tipRate` are mutually exclusive. Care must be taken to include one or the other but not both.

Example: 14.50

Example:14.5

tipRatenumber or null, (double)

Specifies the tip rate as a percentage of the base amount to be added.

This amount adds to the base amount of the original transaction. That transaction must be authorized first.

Values for `tipAmount` and `tipRate` are mutually exclusive. Care must be taken to include one or the other but not both.

Example: 15 (as 15%)

Example:15

percentageOffRatenumber or null, (double)

Identifies the discount percentage.

This value is percentage rate for the discount.

Example: 3.5 (as 3.5%)

Example:3.5

surchargeRatenumber or null, (double)

Identifies the surcharge percentage.

This is a surcharge on the base amount. This value is surcharge percentage rate. This surcharge percentage calculates the surcharge amount for surchargeAmount.

Example: 1.5 (as 1.5%)

Example:1.5

useCardPriceboolean or null

Parameter is mandatory when merchant has ZeroCostProcessingOption == Dual Pricing.

Parameter must be null when merchant has other ZeroCostProcessingOption.

For Dual Pricing, amount should be the card price and useCardPrice should be true, or amount should be the cash price and useCardPrice should be `false'.

appVersionstring or null

Specifies the version of the mobile app.

This value is stored on the transaction. It is visible in the transaction details. The appVersion value takes priority over the sdkVersion if both are present.

Example: 10.413.01

Example:"10.413.01"

sdkVersionstring or null

Specifies the version of the Flute SDK.

This value is stored on the transaction. It is visible in the transaction details. The appVersion value takes priority over the sdkVersion if both are present.

Example: 8.61.08

Example:"8.61.08"

billingAddressobject

Specifies an object defining the address.

shippingAddressobject

Specifies an object defining the address.

contactInfoobject

This group contains the customer's contact details.

securityCodestring or null

Specifies the three or four digit security code on the credit card.

track1string or null

Specifies the card data from track 1 of the magnetic stripe.

track2string or null

Information stored on the magnetic stripe of a credit or debit card.

This includes the card number, expiration date, and cardholder's name.

emvTagsArray of strings or null

Each tag corresponds to a particular piece of data stored on the card.

emvPaymentAppVersionstring or null

Specifies the version number of the payment application in use.

pinstring or null

Specifies the encrypted PIN for the terminal.

pinKsnstring or null

Specifies the KSN for DUKPT PIN encryption.

Required only if the PIN is encrypted using DUKPT.

debitboolean or null

IF Debit THEN use card as a debit card, else use card as a credit card

emvFallbackConditioninteger, (int32)

Possible values:

Value	Name
0	ICCTerminalError
1	NoCandidateList

Example: 2

Example:2

emvFallbackLastChipReadinteger, (int32)

Possible values:

Value	Name
0	Successful
1	Failed
2	NotAChipTransaction
3	Unknown

Example: 1

Example:1

referenceIdstring or null

Specifies an external transaction identifier for client-side tracking.

Also used in duplicate control validation. A unique value allows similar transactions to process as distinct, bypassing duplicate blocking when needed.

l2object

l3object

customerInitiatedTransactionboolean

Customer Initiated Transaction if true.

Merchant Initiated Transaction if false

Default:false

curl -i -X POST \
  https://developer.flute.com/_mock/api-reference/pay-api/v1/transactions/sale \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cardDataSource": 1,
    "deviceId": "a30f9b66-b2f0-4b18-a03a-b861b00afa8b",
    "paymentProcessorId": "8d72c23b-5d52-42df-beee-1a96655e2be6",
    "customerId": null,
    "paymentMethodId": "c5d59148-5d6e-4f7a-8b9c-0d1e2f3a4b70",
    "accountNumber": null,
    "amount": 123.45,
    "tipAmount": 1,
    "tipRate": null,
    "currencyId": 1,
    "percentageOffRate": 3,
    "surchargeRate": 4,
    "useCardPrice": null,
    "billingAddress": {
      "city": "Phoenix",
      "countryId": 1,
      "line1": "7429 Desert Mirage Lane",
      "line2": null,
      "postalCode": "85099",
      "stateName": "Arizona",
      "stateId": 4
    },
    "shippingAddress": {
      "city": "Phoenix",
      "countryId": 1,
      "line1": "7429 Desert Mirage Lane",
      "line2": "Office 7",
      "postalCode": "85099",
      "stateName": "Arizona",
      "stateId": 4
    },
    "contactInfo": {
      "firstName": "John",
      "lastName": "Smith",
      "companyName": "Flute",
      "email": "j.smith29f@example.com",
      "mobileNumber": "+1415558787",
      "smsNotification": true
    },
    "securityCode": "123",
    "expirationMonth": 12,
    "expirationYear": 2032,
    "track1": null,
    "track2": null,
    "emvTags": null,
    "emvPaymentAppVersion": null,
    "pin": null,
    "pinKsn": null,
    "debit": null,
    "emvFallbackCondition": null,
    "emvFallbackLastChipRead": null,
    "referenceId": null,
    "l2": null,
    "l3": null,
    "customerInitiatedTransaction": false
  }'

Responses

Bodyapplication/json

transactionIdstring, (uuid)

Identifies the transaction identifier.

Example: c7c15dd0-03e7-4e55-917c-54bedafba5e7

Example:"c7c15dd0-03e7-4e55-917c-54bedafba5e7"

transactionDateTimestring, (date-time)

Specifies the date and time (in an ISO 8601 date-time UTC format) of the transaction execution.

Examples: 2026-02-19T20:24:52.934Z

Example:"2026-02-19T20:24:52.934Z"

typeIdinteger, (int32)

Type id of transaction.

typestring or null

Type name of transaction

statusIdinteger, (int32)

Indicates the status identifier of the transaction.

statusstring or null

Indicates the status name of the transaction

detailsobject

transactionReceiptobject or null

Indicates an object describing the transaction receipt. The transaction receipt will be null or empty before the transaction is completed. After the completed transaction, it be filled out.

processedAmountnumber, (double)

Indicates which amount is authorized. The amount may differ from the amount in the request.

avsResponseobject

Address Verification Service Response

Response

{
  "processedAmount": 10,
  "avsResponse": {
    "actionId": 1,
    "action": "Allow",
    "responseCode": "0",
    "groupId": 5,
    "group": "ValidGroup",
    "resultId": 1,
    "result": "Passed",
    "codeDescription": "The street address and ZIP Code match the information on file."
  },
  "transactionReceipt": {
    "transactionId": "a7b8c9d0-e1f2-4a3b-4c5d-6e7f8a9b0c36",
    "transactionDateTime": "2026-12-16T10:35:52.000000Z",
    "amount": {
      "baseAmount": 0,
      "percentageOffAmount": 0,
      "percentageOffRate": 0,
      "cashDiscountAmount": 0,
      "cashDiscountRate": 0,
      "surchargeAmount": 0,
      "surchargeRate": 0,
      "tipAmount": 0,
      "tipRate": 0,
      "totalAmount": 0
    },
    "currencyId": 1,
    "currency": "USD",
    "processorId": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b25",
    "processor": "TSYS",
    "operationTypeId": 0,
    "operationType": null,
    "paymentMethodTypeId": 0,
    "paymentMethodType": null,
    "transactionTypeId": 0,
    "transactionType": null,
    "customerId": null,
    "customerPan": null,
    "cardTokenType": 1,
    "statusId": 0,
    "status": null,
    "merchantName": null,
    "merchantAddress": null,
    "merchantPhoneNumber": null,
    "merchantEmailAddress": null,
    "merchantWebsite": null,
    "authCode": null,
    "source": null,
    "cardholderAuthenticationMethodId": null,
    "cardholderAuthenticationMethod": null,
    "cvmResultMsg": null,
    "cardDataSourceId": null,
    "cardDataSource": null,
    "responseCode": null,
    "responseDescription": null,
    "cardProcessingDetails": {
      "authCode": "A0000",
      "mid": null,
      "tid": null,
      "cardCreditDebitTypeId": 2,
      "cardCreditDebitType": "Debit",
      "processCreditDebitTypeId": 1,
      "processCreditDebitType": "Credit",
      "rrn": "10628361287F",
      "cardTypeId": 0,
      "cardType": null
    },
    "achProcessingDetails": {
      "customerAccountNumber": null,
      "customerRoutingNumber": null,
      "accountHolderType": null,
      "accountHolderTypeId": 0,
      "accountType": null,
      "accountTypeId": 0,
      "taxId": null
    },
    "availableOperations": [
      {
        "typeId": 4,
        "type": "Void",
        "availableAmount": null,
        "suggestedTips": null
      },
      {
        "typeId": 8,
        "type": "TipAdjustment",
        "availableAmount": null,
        "suggestedTips": [
          {
            "tipPercent": 5,
            "tipAmount": 10
          },
          {
            "tipPercent": 10,
            "tipAmount": 20
          },
          {
            "tipPercent": 15,
            "tipAmount": 30
          }
        ]
      }
    ],
    "avsResponse": {
      "actionId": 1,
      "action": "Allow",
      "responseCode": null,
      "groupId": 5,
      "group": "ValidGroup",
      "resultId": 1,
      "result": "Passed",
      "codeDescription": null
    },
    "emvTags": {
      "ac": "533C2902770EA987",
      "tvr": "0040040000",
      "tsi": null,
      "aid": "A0000000031010",
      "applicationLabel": "MasterCard",
      "rawTags": [
        {
          "key": "5F34",
          "value": "SOMETHING"
        },
        {
          "key": "5F35",
          "value": "SOMETHING"
        }
      ]
    },
    "orderNumber": "752314"
  },
  "transactionId": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b25",
  "transactionDateTime": "2025-12-16T10:35:52.4155781Z",
  "typeId": 1,
  "type": "Authorization",
  "statusId": 1,
  "status": "Authorized",
  "details": {
    "hostResponseCode": "00",
    "hostResponseMessage": "APPROVAL",
    "hostResponseDefinition": "Approved and completed",
    "code": "Approve",
    "message": "Success",
    "processorResponseCode": null,
    "authCode": "VTLMC1",
    "maskedPan": null
  }
}