Sale/Auth Transaction

Process a transaction through the gateway.

Request Method: POST

URL Endpoint: /api/transaction

TIP

If you do not have a default processor set, you must include the processor_id property in the request body or the transaction will fail.

Field Notes

Amount - This will be the final amount you want charged and will include all surcharges and related fees(if applicable).

Base Amount - If you are using base_amount it will be the base amount of the transaction. The surcharge and other related fees(if applicable) will be calculated and added unless those values are specifically passed in.

Basic

These are the core fields needed for most transactions.

Name	Type	Default	Required	Description
type	string		Required	"sale", "authorize", "verification" or "credit"
amount	integer		Required	Amount to process in cents (should contain all applicable fees and taxes) (1299 = $12.99)
currency	string	"USD"		ISO 4217 currency (ex "USD")
processor_id	string	""	see description	Processor to be used for the requested transaction. If not passed, will use the default processor for the payment method.
payment_method	object		Required - one payment method	Object containing payment method details, must contain only one of the following: card, ach, customer, terminal, token, apm, apple_pay_token

Details

Additional fields for order tracking and transaction metadata.

Name	Type	Default	Required	Description
order_id	string		Required for L3	Supports up to 17 alphanumeric characters. If paid with invoice, invoice id will be populated. See docs here.
po_number	string			Supports up to 17 alphanumeric characters. If paid with invoice, invoice id will be populated. See docs here.
description	string	""		Text field for miscellaneous notes (max 255 characters)
ip_address	string	Server IP		IPv4 or IPv6 value of the end user. Do not include port
vendor_id	string	""		Vendor ID passed along to certain processors if supported (Special Field, only use if instructed by support)

Idempotency Key

Prevent duplicate transactions using idempotency keys.

Name	Type	Default	Required	Description
idempotency_key	uint			UUID format. Used to identify duplicate transactions. If idempotency_time is not provided, the TTL will default to 5 minutes
idempotency_time	uint	300		Time in seconds. Default is 5 minutes

Payment Methods

All payment method fields are nested within the payment_method object. See the examples below for the JSON structure.

Card

The most common payment method. Process transactions using debit or credit card information.

Name	Type	Default	Required	Description
card	object			Object containing details for processing a transaction against a card
card.entry_type	string			Must be "keyed" or "swiped"
card.number	string		Required	Card number (digits only)
card.expiration_date	string		Required	Expiration date (format MM/YY)
card.cvc	string		required if the applicable rule is set on the gateway	Card Verification Code
card.track_1	string			Decrypted track_1
card.track_2	string			Decrypted track_2
card.encrypted_track_1	string			Encrypted Track 1
card.encrypted_track_2	string			Encrypted Track 2
card.ksn	string			KSN used to encrypt the supplied encrypted tracks
card.cardholder_authentication	object		if passed, it must contain valid values	Optionally pass 3DS collected data
card.cardholder_authentication.eci	string			ECI indicator, ie 01,02,05,07..etc
card.cardholder_authentication.cavv	string			CAVV
card.cardholder_authentication.xid	string			XID
card.cardholder_authentication.cryptogram	string			Cryptogram
card.cardholder_authentication.version	string			Version, 1 or 2
card.cardholder_authentication.ds_transaction_id	string			DS Transaction ID
card.cardholder_authentication.acs_transaction_id	string			ACS Transaction ID
emv	object			Object containing details for processing EMV transactions
emv.tlv_data	map[string]string			map containing the EMV tlv packets. These must be hex encoded strings
emv.device_serial_number	string			String containing the device serial number.

Basic Card Example

Card with 3DS Authentication Example

Customer

Process a transaction using a payment method stored in the Customer Vault.

Name	Type	Default	Required	Description
customer	object			Object containing details for processing against a vaulted customer record
customer.id	string		Required	Used to associate a transaction with a customer already stored in the Customer Vault
customer.payment_method_id	string	Customer default		ID of customer's saved payment method to be charged
customer.payment_method_type	string	Customer default		The type of the payment method referenced in payment_method_id
customer.billing_address_id	string	Customer default		ID of customer's saved billing address to be used
customer.shipping_address_id	string	Customer default		ID of customer's saved shipping address to be used

Token

Process a transaction using a previously tokenized payment method. See Tokenizer for more information on tokenizing payment methods.

Name	Type	Default	Required	Description
token	string		Required	Token value for a previously tokenized payment

Apple Pay

Process transactions using Apple Pay. Two methods are supported: Wallet.js (temporary token) and native ApplePay.js/Payment Request API (pkpaymenttoken).

Name	Type	Default	Required	Description
apple_pay_token	object			Object containing details for processing Apple Pay transactions
apple_pay_token.temporary_token	string		required if using Wallet.js, should not be present if using native ApplePay.js or Payment Request API	A one-time token when processing Apple Pay transactions using Wallet.js
apple_pay_token.key_id	string		required if apple_pay_token is present	The ID of the registered Apple Pay credential, not Apple's Merchant ID.
apple_pay_token.pkpaymenttoken	object		required if using ApplePay.js or Payment Request API	Object containing encrypted data of a credit card tokenized with Apple Pay, getting from Apple Pay client

Apple Pay (Apple Pay JS)

Apple Pay (Wallet.js)

Apple Pay Decrypted

ACH

Process transactions via Automated Clearing House (ACH) for bank account debits.

Name	Type	Default	Required	Description
ach	object			Object containing details for processing a transaction via ACH
ach.routing_number	string		Required	Routing number for account to be charged
ach.account_number	string		Required	Account number for account to be charged
ach.sec_code	string		Required	SEC code for ACH transaction type: "web", "ccd", "ppd", or "tel"
ach.account_type	string		Required	ACH account type: "checking" or "savings"
ach.check_number	string		required if ach.sec_code = "tel"	Check number
ach.funding_speed	string	"standard"	"standard" or "sameday"	Funding Speed, available on select ACH Providers.
ach.accountholder_authentication	object		if required by processor	Object containing details for accountholder authentication
ach.accountholder_authentication.dl_state	string		required if ach.accountholder_authentication is present	Driver's License state
ach.accountholder_authentication.dl_number	string		required if ach.accountholder_authentication is present	Driver's License number

Terminal

Process transactions using a physical payment terminal device.

Name	Type	Default	Required	Description
terminal	object			Object containing details for processing a transaction against a Terminal
terminal.id	string		Required	ID of the terminal to be used for the transaction
terminal.expiration_date	string			Optionally pass an expiration date along with the transaction
terminal.cvc	string			Optionally pass a CVV along with the transaction
terminal.print_receipt	string		Required	"no" (no receipt), "customer" (customer copy only), "merchant" (merchant copy only), or "both" (both copies)
terminal.signature_required	string		Required	If true, requests that the terminal capture a signature (if supported)

APM

Process transactions using alternative payment methods (Alternative Payment Methods) like Klarna, OXXO, Alipay, etc.

Name	Type	Default	Required	Description
apm	object			Object containing details for processing APM transactions
apm.type	string		Required	APM type (see chart below)
apm.merchant_redirect_url	string		Required	This is the redirect url you wish to send the customer to after processing the payment
apm.locale	string		Required	Locale to be used for the payment page, if supported by the APM (ex. "en-US")
apm.mobile_view	boolean		Required	If true, tells the APM to render a mobile version of the landing page (if supported by the APM)
apm.national_id	string			Consumer's National ID (max 30 characters)
apm.consumer_ref	string			Unique reference identifiying the customer. May contain [a-z0-9-], max 20 characters

Supported APMs

Type	Supported Processing Countries	Supported Currencies
alipay	CN	EUR, USD, GBP
dragonpay	PH	PHP
wechatpay	CN	EUR, USD
oxxo	MX	USD, MXN
klarna	AT, DK, FI, DE, NL, NO, SE, GB	EUR, DKK, GBP, NOK, SEK
sepa	DE	EUR

APM Requirements

See specific APM requirements below for additional required fields per payment method type.

Amounts

Configure transaction pricing components including the total amount, base amount, taxes, shipping, discounts, tips, and payment adjustments (surcharges, convenience fees). Use amount for the final total including all fees, or base_amount to let the system calculate and add applicable fees automatically.

Amount Calculation API

For complex transactions with multiple fees, taxes, discounts, and line items, consider using the Amount Calculation API to automatically calculate all applicable amounts before submitting your transaction. This ensures accurate totals and handles processor-specific fee calculations, surcharges, and tax computations.

Name	Type	Default	Required	Description
amount	integer			Amount to process in cents (should contain all applicable fees and taxes) (1299 = $12.99)
base_amount	integer			Amount to process in cents (surcharge and related fees will be added to this amount during processing) (1299 = $12.99)
tax_amount	integer	0	Required for L3	Tax Amount in cents
tax_exempt	boolean	false	Required for L3	Is the transaction tax exempt
shipping_amount	integer	0		Shipping Amount in cents (should be included in Amount)
discount_amount	integer	0		Discount Amount in cents (should be included in Amount)
tip_amount	integer	0		Tip Amount in cents (should be included in Amount)
payment_adjustment	object			Object containing payment adjustment details. (ex. convenience fees, service fees, and surcharges)
payment_adjustment.type	string	""		"flat" or "percentage"
payment_adjustment.value	integer	0		Amount of adjustment in cents for "flat" (ex. 199 = $1.99) or 3 decimal places for "percentage" (ex. 1000 = 1.000%)

Amount with Tax and Shipping Example

Amount with Payment Adjustment Example

Addresses

Provide billing and shipping address information for the transaction. Billing addresses are used for AVS (Address Verification System) checks and fraud prevention, while shipping addresses are required for Level 3 data transactions. Both addresses support standard address fields including name, company, street address, city, state, postal code, country, and contact information.

Billing

Name	Type	Default	Required	Description
billing_address	object	null		Object containing billing address details
billing_address.first_name	string			Up to 50 characters
billing_address.last_name	string			Up to 50 characters
billing_address.company	string			Up to 100 characters
billing_address.address_line_1	string			Up to 100 characters
billing_address.address_line_2	string			Up to 100 characters
billing_address.city	string			Up to 50 characters
billing_address.state	string			State abbreviation
billing_address.postal_code	string		Required for L3	If card is present, defaults to Postal Code associated with card
billing_address.country	string			"US"
billing_address.email	string			Email address (must be valid email format, "example@mail.com")
billing_address.phone	string			Digits only
billing_address.fax	string			Digits only

Shipping

Name	Type	Default	Required	Description
shipping_address	object	null		Object containing shipping address details
shipping_address.first_name	string			Up to 50 characters
shipping_address.last_name	string			Up to 50 characters
shipping_address.company	string			Up to 100 characters
shipping_address.address_line_1	string			Up to 100 characters
shipping_address.address_line_2	string			Up to 100 characters
shipping_address.city	string			Up to 50 characters
shipping_address.state	string			State abbreviation
shipping_address.postal_code	string		Required for L3
shipping_address.country	string
shipping_address.email	string			Email address (must be valid email format, "example@mail.com")
shipping_address.phone	string			Digits only
shipping_address.fax	string			Digits only

Address Requirements

• Billing Address: Recommended for card transactions to enable AVS verification and reduce fraud risk. If a card payment method is used, the postal code will default to the card's associated postal code if not provided.
• Shipping Address: Required for Level 3 data transactions. Both billing and shipping addresses must include postal codes for L3 transactions.

Transaction with Billing and Shipping Addresses Example

Line Items

Itemize products or services in a transaction. Line items provide detailed information about each item being purchased, including pricing, quantities, and product details. This is useful for detailed receipts, reporting, and transaction tracking.

Name	Type	Required	Description
line_items	array		Array of line items
line_items[].name	string		Friendly name up to 50 alpha characters
line_items[].description	string		Product Description up to 50 alpha characters
line_items[].product_code	string		Product Code/SKU up to 50 alpha characters
line_items[].quantity	float64		Quantity ##.##
line_items[].unit_price	int		Unit price in cents
line_items[].amount	int		Total amount for this line item in cents
line_items[].tax_amount	int		Tax amount for this line item in cents
line_items[].discount_amount	int		Discount amount for this line item in cents

Custom Fields

Add custom data to transactions for additional tracking and reporting. Custom fields allow you to capture merchant-specific information during transaction processing. You must first create custom fields using the Custom Fields API before you can use them in transactions.

The custom_fields object contains key-value pairs where:

• Keys are the custom_field_id (the ID of the custom field you created)
• Values are arrays of strings (even for single values)

Group Name Requirement

If your custom fields have a non-default group_name, you must include the group_name field in your transaction request. Custom fields with the default group name do not require this field.

Name	Type	Default	Required	Description
group_name	string	"default"	Required if custom fields have non-default group	Custom fields group name. Only required when using custom fields that belong to a non-default group.
custom_fields	object		Only required if fields are set to required	Object where keys are custom_field_id and values are arrays of strings. For more information, see Custom fields with transaction.

Transaction with Custom Fields Example

Processor-Specific

Processor-specific configuration options (PaySafe Direct only).

Name	Type	Default	Required	Description
processor_specific.paysafe_direct.subscription_trial_solution	bool
processor_specific.paysafe_direct.subscription_start_date	string			YYYY-MM-DD
processor_specific.paysafe_direct.subscription_trial_start_date	string			YYYY-MM-DD
processor_specific.paysafe_direct.subscription_trial_end_date	string			YYYY-MM-DD
processor_specific.paysafe_direct.subscription_secondary_billing_date	string			YYYY-MM-DD
processor_specific.paysafe_direct.subscription_cancel_url	string			weburl
processor_specific.paysafe_direct.subscription_amount	uint			in cents
processor_specific.paysafe_direct.subscription_unit_cost	uint			in cents
processor_specific.paysafe_direct.subscription_item_quantity	uint
processor_specific.paysafe_direct.subscription_product_desc	string

Customer Vault

Automatically create or update customer vault records during transaction processing.

Name	Type	Default	Required	Description
create_vault_record	boolean	false		If true, triggers the creation of a customer vault record after a successful transaction. Multiple transactions with the same details will create duplicative customer records.
create_vault_record_for	string			If true and transaction was run successfully, adds the payment method to the customer id set on this field

Email & Receipts

Send email receipts to customers after transaction processing.

Name	Type	Default	Required	Description
email_receipt	boolean	false		If true, sends an email receipt (email_address must be provided)
email_address	string		required if email_receipt is true	Email address (must be valid email format, "example@mail.com")

Descriptor

Customize the merchant descriptor shown on customer credit and debit card statements. The descriptor is the text that appears on a customer's bank or credit card statement to identify your business and the transaction. This information helps customers recognize charges from your business and reduces confusion, disputes, and chargebacks.

Why Use Custom Descriptors?

• Reduce Chargebacks: Customers are less likely to dispute transactions they can easily recognize
• Improve Customer Experience: Clear, recognizable business names build trust and reduce support inquiries
• Brand Recognition: Use your business name or DBA that customers know to maintain brand consistency
• Transaction Clarity: Helps customers identify specific purchases when reviewing their statements

Processor-Specific

Descriptor customization is processor-specific and may not be supported by all payment processors. Check with your processor to confirm descriptor support and any additional formatting requirements.

Name	Type	Default	Required	Description
descriptor	object
descriptor.name	string			Maximum 38 characters
descriptor.address	string			Maximum 38 characters
descriptor.city	string			Maximum 21 characters
descriptor.state	string			Maximum 2 characters
descriptor.postal_code	string			Maximum 5 characters

Transaction with Descriptor Example

Partial Payment

Allow partial transactions to be approved (only if supported by processor).

Name	Type	Default	Required	Description
allow_partial_payment	bool	false		Allow partial transactions to be approved (only if supported by processor)

Split Transaction

If your gateway account has our "Split Transaction" feature enabled, using the following example will trigger two independent transactions to run on the same card, using two different processors in the gateway. This is a useful feature when charging something like an application fee.

Important Response Field

split_transaction_response - This field in the response contains information about the secondary transaction that was processed. You can use the id from this field to reference the other transaction if you need to perform operations like refunds, voids, or lookups on the secondary transaction.

Name	Type	Default	Required	Description
split_transaction_amount	integer			Amount to process in cents as the secondary transaction

L3 Data

Level 3 processing data for enhanced transaction detail reporting. The following fields are required for Level 3 processing.

Name	Type	Required	Description
line_items	array	Required for L3	Array of line items
line_items[].name	string		Friendly name up to 50 alpha characters
line_items[].description	string		Product Description up to 50 alpha characters
line_items[].product_code	string		Product Code/SKU up to 50 alpha characters
line_items[].commodity_code	string		Commodity Code up to 12 alpha characters
line_items[].quantity	float64		Quantity ##.##
line_items[].discount_amount	int		in cents
line_items[].freight_amount	int		in cents
line_items[].unit_price	int		in cents
line_items[].tax_amount	int		in cents
line_items[].national_tax_amount	int		in cents
line_items[].amount	int		in cents
line_items[].national_tax_rate	string		3 decimal rate. 10% = 10.000
line_items[].tax_rate	string		3 decimal rate. 10% = 10.000
line_items[].unit_of_measure	string
summary_commodity_code	string	Required for L3	Summary Commodity Code 4 AlphaNumeric characters
ship_from_postal_code	string	Required for L3	Ship From Postal Code

CIT/MIT

Card-on-File indicators that specify whether a transaction is using stored payment credentials and who initiated the transaction. These variables are available for including CIT/MIT variables to the processors.

Name	Type	Default	Required	Description
card_on_file_indicator	null | string	null	Optional	[CR] Optional value, C = General purpose storage, R = recurring payment
initiated_by	string	"customer" or "merchant"	Required	Who is initiating the transaction, "customer" or "merchant". Indicates who initiated the transaction.
initial_transaction_id	string		Optional	Optional if using our tokenization, otherwise this is transaction id used when storing the payment
stored_credential_indicator	string		Optional	Optional if using our tokenization, otherwise "used" or "stored". Indicates if a stored payment was used or not
billing_method	string	"straight"	Optional	"straight", "initial_recurring", or "recurring". Defaults to "straight", but if this is a recurring transaction, passing "recurring" will set recurring indicators on the transaction

HSA/FSA

Process Health Savings Account (HSA) and Flexible Spending Account (FSA) transactions.

Name	Type	Default	Required	Description
iias_status	string	""		Required for HSA/FSA Valid values are: "verified" or "exempt"
additional_amounts.hsa.total	int	0		Required for HSA/FSA Total amount for HSA/FSA, passed as an unsigned integer
additional_amounts.hsa.rx_amount	int	0		RX Amount for HSA/FSA, passed as an unsigned integer
additional_amounts.hsa.vision_amount	int	0		Vision Amount for HSA/FSA, passed as an unsigned integer
additional_amounts.hsa.clinic_amount	int	0		Clinic Amount for HSA/FSA, passed as an unsigned integer
additional_amounts.hsa.dental_amount	int	0		Dental Amount for HSA/FSA, passed as an unsigned integer

APM Requirements

Additional requirements for specific Alternative Payment Methods.

SEPA

Field	Required
payment_method.apm.consumer_id
payment_method.apm.iban
payment_method.apm.mandate_reference	merchant assigned value referencing the mandate
payment_method.apm.mandate_url
payment_method.apm.mandate_signature_date	YYYY-MM-DD

Alipay

Field	Required
payment_method.apm.mobile_view

DragonPay

Field	Required
billing_address.email
billing_address.phone

WeChatPay

Field	Required
payment_method.apm.locale

OXXO

Field	Description	Required
payment_method.apm.national_id	Consumer's national id (max 30 characters). Not required for OXXO MXN.
payment_method.apm.consumer_ref	Unique customer reference provided by merchant. (max 20 alphanumeric characters)
payment_method.apm.due_date	"YYYY-MM-DD" expiry date for payment voucher. Voucher expires at midnight local Mexico City Time. Only applies to OXXO MXN currency.
billing_address.email	Email address (must be valid email format, "example@mail.com")
billing_address.address_1
billing_address.postal_code

Klarna

Field	Description	Required
payment_method.apm.payment_method_category	"direct_debit", "direct_bank_transfer", "pay_now", "pay_later", or "pay_over_time"
payment_method.apm.purchase_type	"buy", "rent", "book", "subscribe", "download", "order", or "continue" (default = "continue")
payment_method.apm.hpp_title	Title to be used for Hosted Payment Page
payment_method.apm.logo_url	Logo Url to be used on Hosted Payment Page
billing_address
shipping_address
line_items[].name
line_items[].quantity
line_items[].unit_of_measure	unit of measure
line_items[].unit_price	unit price
line_items[].amount	total amount
line_items[].product_code	sku/reference
line_items[].local_tax	tax amount per item
line_items[].discount_amount	discount amount as an unsigned integer
tax_amount