Authorizes a transaction

Request

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

This endpoint authorizes a payment transaction.

This verifies that the customer's payment method is valid and that sufficient funds or credit are available.

See Also:
To create a transaction, see POST /pay-api/v1/transactions/sale.
To capture a transaction, see POST /pay-api/v1/transactions/capture.
To void a transaction, see POST /pay-api/v1/transactions/void.
To retrieve a transaction by ID, see GET /pay-api/v1/transactions/{transactionId}.
To verify a card without charging it, see POST /pay-api/v1/transactions/card-verification.

Security

Bearer

Bodyapplication/json

amountnumber, (double)required

Specifies the amount of the transaction.

Example: 29.99

Example:29.99

accountNumberstring

Specifies the card number used for the transaction.

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

Example: 4111111111111111

Example:"4111111111111111"

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

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"

cardDataSourceinteger, (int32)

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

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.

A list of available payment processers can be found with GET {{baseURL}}/pay-api/v1/configurations/payments. See response availablePaymentProcessors.id.
If omitted, the merchant's default payment processor will be used.

Example: 37bd9ccb-2c9d-45cf-a65f-c9a224bdeaeb

Example:"37bd9ccb-2c9d-45cf-a65f-c9a224bdeaeb"

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"

tipAmountnumber or null, (double), decimal places <= 2

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

This amount adds to the number included in the field amount earlier. For example if amount is $100 and this tipAmount is $10, the authorize amount is $110.

No additional tip amount or tip rate is required to be added, such as from POST {{baseURL}}/pay-api/v1/transactions/tip-adjustment

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

Example: 14.50 (for $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 number included in the field amount earlier. For example if amount is $100 and this tipRate is 10, the authorize amount is $110.

No additional tip amount or tip rate is required to be added, such as from POST {{baseURL}}/pay-api/v1/transactions/tip-adjustment

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)

The percent of the base amount to be discounted.

Example:
8.25 (as 8.25%)
12 (as 12%)

Example:12

surchargeRatenumber or null, (double)

The percent of transaction amount to be added to the amount after percentageOffRate is applied.

Example:
8.25 (as 8.25%)
12 (as 12%)

Example:12

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.01

Example:"8.61.01"

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

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

track1string or null

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, including 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

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.

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

Specifies the Level 2 card data for the transaction.

l3object

Specifies the Level 3 card data for the transaction.

customerInitiatedTransactionboolean

Customer Initiated Transaction if true Merchant Initiated Transaction if false Default value - false.

curl -i -X POST \
  https://developer.flute.com/_mock/api-reference/pay-api/v1/transactions/auth \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cardDataSource": 1,
    "deviceid": "a30f9b66-b2f0-4b18-a03a-b861b00afa8b",
    "paymentProcessorId": "37bd9ccb-2c9d-45cf-a65f-c9a224bdeaeb",
    "customerId": null,
    "paymentMethodId": "d6e6a259-6e7f-4a8b-9c0d-1e2f3a4b5c81",
    "accountNumber": null,
    "amount": 123.45,
    "tipAmount": 1,
    "tipRate": null,
    "currencyId": 1,
    "percentageOffRate": 3,
    "surchargeRate": 4,
    "useCardPrice": null,
    "appVersion": "10.413.01",
    "sdkVersion": "8.61.01",
    "billingAddress": {
      "city": "Phoenix",
      "countryId": 1,
      "line1": "21 E. Main Street",
      "line2": "Office 7",
      "postalCode": "85099",
      "stateName": "Arizona",
      "stateId": 4
    },
    "shippingAddress": {
      "city": "Phoenix",
      "countryId": 1,
      "line1": "21 E. Main Street",
      "line2": null,
      "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": 24,
    "track1": null,
    "track2": null,
    "emvTags": null,
    "emvPaymentAppVersion": null,
    "pin": null,
    "pinKsn": 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

Indicates additional processor-level response details for the transaction.

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 will be filled out.

processedAmountnumber, (double)

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

avsResponseobject

Indicates the Address Verification Service (AVS) response.

Response

Transaction, type Authorization, status = Authorized. Transaction status after an approved pre-authorization request

{
  "processedAmount": 10,
  "avsResponse": {
    "actionId": 1,
    "action": "Allow",
    "responseCode": "0",
    "groupId": 5,
    "group": "ValidGroup",
    "resultId": 1,
    "result": "Passed",
    "codeDescription": "Street Address and ZIP Code Match the information on file."
  },
  "transactionReceipt": null,
  "transactionId": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a14",
  "transactionDateTime": "2025-12-16T10:35:52.4081694Z",
  "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
  }
}