SFTP Transactions

The /transactions folder allows you to create or update transactions in bulk via SFTP. Upload CSV files to process multiple transactions efficiently.

File Format

Upload CSV files to the /transactions folder. The CSV uses dot notation for nested fields and follows the same behavior patterns as other SFTP operations.

Common Required Fields

Field	Description	Required	Example
`action`	Transaction action type	Yes	`CHARGE`, `AUTHORIZE`, `REVERSAL`, `REFUND`, `CAPTURE`, `VOID`, `PAYOUT`, `NONE`

Action-Specific Requirements

CHARGE Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "CHARGE" to create a charge transaction
`amount`	integer/string	Yes	Transaction amount in cents (if no decimal) or dollars (if decimal provided)
`paymentMethod.id`	UUID	Yes	References existing stored payment method for processing

Optional Fields:

Name	Type	Required	Description
`currency`	string	No	3-digit ISO currency code, defaults to USD when not provided
`businessProcess`	string/UUID	No	Links transaction to business process workflow
`businessProcessAction`	UUID	No	Links transaction to specific business process action
`description`	string	No	Human-readable description for transaction records (3-50 characters)
`metadata`	object	No	Additional data for transaction tracking (1-24 key-value pairs)
`adjustments`	array	No	Tax, discount, or fee adjustments applied to transaction
`product`	UUID	No	References product used for transaction processing
`references.external`	string	No	External system reference for transaction reconciliation
`references.customer`	string	No	Customer reference for transaction tracking

AUTHORIZE Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "AUTHORIZE" to create an authorization transaction
`amount`	integer/string	Yes	Authorization amount in cents (if no decimal) or dollars (if decimal provided)
`paymentMethod.id`	UUID	Yes	References existing stored payment method for authorization

Optional Fields:

Name	Type	Required	Description
`currency`	string	No	3-digit ISO currency code, defaults to USD when not provided
`businessProcess`	string/UUID	No	Links transaction to business process workflow
`businessProcessAction`	UUID	No	Links transaction to specific business process action
`description`	string	No	Human-readable description for transaction records (3-50 characters)
`metadata`	object	No	Additional data for transaction tracking (1-24 key-value pairs)
`adjustments`	array	No	Tax, discount, or fee adjustments applied to transaction
`product`	UUID	No	References product used for transaction processing
`references.external`	string	No	External system reference for transaction reconciliation
`references.customer`	string	No	Customer reference for transaction tracking

REVERSAL Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "REVERSAL" to reverse an existing transaction
`originId`	UUID	Yes	References original transaction to be reversed

Optional Fields:

Name	Type	Required	Description
`amount`	integer	No	Partial reversal amount, defaults to full original amount when not provided
`references.external`	string	No	External system reference for reversal tracking
`references.customer`	string	No	Customer reference for reversal tracking

REFUND Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "REFUND" to refund an existing transaction
`originId`	UUID	Yes	References original transaction to be refunded

Optional Fields:

Name	Type	Required	Description
`amount`	integer	No	Partial refund amount, defaults to full original amount when not provided
`references.external`	string	No	External system reference for refund tracking
`references.customer`	string	No	Customer reference for refund tracking

CAPTURE Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "CAPTURE" to capture an authorized transaction
`originId`	UUID	Yes	References original authorization transaction to capture

Optional Fields:

Name	Type	Required	Description
`amount`	integer	No	Capture amount, defaults to full authorization amount when not provided
`references.external`	string	No	External system reference for capture tracking
`references.customer`	string	No	Customer reference for capture tracking

VOID Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "VOID" to void an existing transaction
`originId`	UUID	Yes	References original transaction to be voided

Optional Fields:

Name	Type	Required	Description
`references.external`	string	No	External system reference for void tracking
`references.customer`	string	No	Customer reference for void tracking

PAYOUT Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "PAYOUT" to create a payout transaction
`amount`	integer/string	Yes	Payout amount in cents (if no decimal) or dollars (if decimal provided)
`paymentMethod.id`	UUID	Yes	References existing stored payment method for payout

Optional Fields:

Name	Type	Required	Description
`currency`	string	No	3-digit ISO currency code, defaults to USD when not provided
`businessProcess`	UUID	No	Links transaction to business process workflow
`businessProcessAction`	UUID	No	Links transaction to specific business process action
`description`	string	No	Human-readable description for transaction records (3-50 characters)
`metadata`	object	No	Additional data for transaction tracking (1-24 key-value pairs)
`product`	UUID	No	References product used for transaction processing
`references.external`	string	No	External system reference for transaction reconciliation
`references.customer`	string	No	Customer reference for transaction tracking

NONE Transactions

Required Fields:

Name	Type	Required	Description
`action`	string	Yes	Must be "NONE" to create a transaction record without processing
`actionType`	string	Yes	Original transaction type (CHARGE, REVERSAL, or PAYOUT) for record keeping
`amount`	integer	Yes	Transaction amount for record keeping (minimum 0)
`description`	string	Yes	Human-readable description for transaction records (3-50 characters)

Optional Fields:

Name	Type	Required	Description
`status`	string	No	Transaction status for record keeping
`currency`	string	No	3-digit ISO currency code, defaults to USD when not provided
`businessProcess`	UUID	No	Links transaction to business process workflow
`businessProcessAction`	UUID	No	Links transaction to specific business process action
`metadata`	object	No	Additional data for transaction tracking (1-24 key-value pairs)
`adjustments`	array	No	Tax, discount, or fee adjustments for record keeping
`createdOn`	integer	No	Timestamp in milliseconds when transaction was completed
`references.external`	string	No	External system reference for transaction reconciliation
`references.customer`	string	No	Customer reference for transaction tracking

Example CSV Files

CHARGE Transaction Example

action,amount,paymentMethod.id,currency,description
CHARGE,100.00,pm_123456789,USD,Product Purchase
CHARGE,250.50,pm_987654321,EUR,Invoice Payment

AUTHORIZE Transaction Example

action,amount,paymentMethod.id,currency,description
AUTHORIZE,100.00,pm_123456789,USD,Product Authorization
AUTHORIZE,250.50,pm_987654321,CAD,Invoice Authorization

REVERSAL Transaction Example

action,originId,amount,references.external
REVERSAL,123e4567-e89b-12d3-a456-426655440000,100.00,ext_ref_123
REVERSAL,123e4567-e89b-12d3-a456-426655440001,50.00,ext_ref_456

REFUND Transaction Example

action,originId,amount,references.external
REFUND,123e4567-e89b-12d3-a456-426655440000,100.00,ext_ref_123
REFUND,123e4567-e89b-12d3-a456-426655440001,50.00,ext_ref_456

CAPTURE Transaction Example

action,originId,amount,references.external
CAPTURE,123e4567-e89b-12d3-a456-426655440000,100.00,ext_ref_123
CAPTURE,123e4567-e89b-12d3-a456-426655440001,50.00,ext_ref_456

VOID Transaction Example

action,originId,references.external
VOID,123e4567-e89b-12d3-a456-426655440000,ext_ref_123
VOID,123e4567-e89b-12d3-a456-426655440001,ext_ref_456

PAYOUT Transaction Example

action,amount,paymentMethod.id,currency,description
PAYOUT,75.00,pm_123456789,USD,Service Payment
PAYOUT,125.25,pm_987654321,GBP,Refund Payment

NONE Transaction Example

action,actionType,amount,description,status,currency,createdOn
NONE,CHARGE,100.00,Transaction Record,CHARGED,USD,1727378861336
NONE,PAYOUT,50.00,Payout Record,COMPLETED,EUR,1727378861337

Processing Workflow

For each valid record:

Action validation: Verify action type is valid (CHARGE, AUTHORIZE, REVERSAL, REFUND, CAPTURE, VOID, PAYOUT, NONE)
Required field validation: Check all required fields for the action type
Payment method validation: Verify payment method exists (if required)
Origin transaction validation: Verify origin transaction exists (for child transactions)
Transaction creation: Create transaction via API
Status update: Mark record as processed

Error Codes

Code	Description	Resolution
`INVALID_ACTION`	Invalid transaction action	Check action type (CHARGE, AUTHORIZE, REVERSAL, REFUND, CAPTURE, VOID, PAYOUT, NONE)
`MISSING_REQUIRED_FIELD`	Required field missing for action	Check action-specific requirements
`INVALID_PAYMENT_METHOD`	Payment method validation failed	Verify payment method ID exists
`ORIGIN_TRANSACTION_NOT_FOUND`	Origin transaction ID not found	Verify origin transaction exists
`INVALID_AMOUNT`	Invalid transaction amount	Check amount format and minimum values
`INVALID_CURRENCY`	Invalid currency code	Use valid 3-digit ISO currency code
`INVALID_DESCRIPTION`	Description too short/long	Use 3-50 characters
`INVALID_METADATA`	Invalid metadata object	Use 1-24 key-value pairs