Sale Transaction

A sale transaction is the most common payment flow, where funds are immediately captured from the customer's account and transferred to the merchant in a single step. Unlike pre-authorization, a sale does not place a temporary hold; it completes the payment instantly.

Quick Reference

• Sale Transaction: Immediately captures and settles funds from the customer to the merchant.
• API Endpoints:
  • POST v1/sessions — Initiate a session for a sale transaction
  • POST v1/payments — Initiate a payment for a sale transaction
• API Scopes: user, merchant, merchant-pci
• Allowed Session Modes: PAYMENT, PAYMENT_WITH_WALLET
• Supported Payment Methods: CARD, BANK_ACCOUNT
• Key Fields: amount, status, paymentType
• Common Statuses: COMPLETED, FAILED, CANCELLED
• Error Codes: See Payment Error Codes

Handling Sale Transactions

• Sale transactions are completed in a single step: funds are captured and settled immediately.
• No additional capture or cancellation is required after a successful sale.
• If the sale fails, the status will be FAILED and an error will be returned.

Payment Request for Sale Transaction

To process a sale, simply omit the authorizeCard flag or set it to false in the /sessions or /payments API request.

/sessions Request Example

Sample /sessions request for Sale

{
  "customer": {
    "firstName": "foo",
    "lastName": "bar",
    "email": "foo.bar@email.com",
    "ssnLastFour": "1234",
    "dateOfBirth": "1970-31-12",
    "phoneNumber": {
      "number": "9876543210",
      "countryCode": "1"
    },
    "zip5": "54321",
    "hsid": "120c5730-e796-4448-8da9-081fde4e3e79",
    "metadata": {}
  },
  "payment": {
    "merchantTransactionId": "f32736c8-266a-4da1-af16-293fa02a351a",
    "amount": 1200,
    "authorizeCard": false
  }
}

/payments Request Example

Sample /payments request for Sale

{
  "customer": {
    "firstName": "foo",
    "lastName": "bar",
    "email": "foo.bar@email.com",
    "ssnLastFour": "1234",
    "dateOfBirth": "1970-31-12",
    "phoneNumber": {
      "number": "9876543210",
      "countryCode": "1"
    },
    "zip5": "54321",
    "hsid": "120c5730-e796-4448-8da9-081fde4e3e79",
    "metadata": {}
  },
  "merchantTransactionId": "f32736c8-266a-4da1-af16-293fa02a351a",
  "amount": 1200,
  "authorizeCard": false,
  "paymentMethodId": ""
}

Payment Response for Sale Transaction

A successful sale transaction returns:

• amount: The amount captured and settled
• status: COMPLETED
• paymentType: SALE

Sample /sessions response: Sale payment

{
  "data": {
    "sessionId": "",
    "status": "COMPLETED",
    "payment": {
      "id": "",
      "amount": 1200,
      "capturedAmount": 1200,
      "description": "",
      "merchantTransactionId": "",
      "merchantId": "",
      "paymentType": "SALE",
      "currencyCode": "usd",
      "status": "COMPLETED",
      "paymentMethodId": "",
      "statementDescriptorSuffix": "",
      "authorizeCard": false,
      "metadata": {},
      "paymentMethod": {},
      "agent": {}
    }
  }
}

Sample /payments response: Sale payment

{
  "data": {
    "id": "95bec1ab-9762-4fe7-a4cd-fcf92b20d5c5",
    "amount": 1200,
    "capturedAmount": 1200,
    "description": "",
    "merchantTransactionId": "",
    "merchantId": "",
    "paymentType": "SALE",
    "currencyCode": "usd",
    "status": "COMPLETED",
    "customerId": "",
    "vendor": "",
    "vendorPaymentId": "",
    "vendorMerchantId": "",
    "statementDescriptorSuffix": "",
    "authorizeCard": false,
    "metadata": {},
    "paymentMethod": {}
  }
}

Sale Statuses

Status	Description
COMPLETED	The payment has been captured and settled
FAILED	The sale transaction failed

Error Handling

See Payment Error Codes