Mandatory Invoices for Payins and Payouts API

We are implementing mandatory invoice requirements for all payin and payout transactions to improve compliance, audit trails, and regulatory adherence across our payment platform.

API Changes

Upload Invoice API

Endpoint: POST https://sandbox-api.transfi.com/v2/invoices/create

This API allows the upload of PDF invoices and generates an invoiceId in response. This invoiceId can be passed while creating Payin (Deposit) or Payout (Withdraw) orders as part of the payload.

Body Parameters:

direction (required): Type of transaction (deposit/withdraw)
email (string, required): User email address
invoice (file, required): PDF invoice file
invoiceType (required): Type of invoice document

Create Payin API Changes

Endpoint: POST https://sandbox-api.transfi.com/v2/orders/deposit

New Requirement:

invoiceId (required): Must be included in the request body
The invoiceId should be obtained from the Upload Invoice API response

Create Payout API Changes

Endpoint: POST https://sandbox-api.transfi.com/v2/payout/orders

New Requirement:

invoiceId (required): Must be included in the request body
The invoiceId should be obtained from the Upload Invoice API response

Reasons for Implementation

Enhanced Compliance - Mandatory invoices ensure regulatory compliance across all transactions
Improved Audit Trails - Complete documentation for all financial transactions
Better Risk Management - Enhanced verification and validation of transaction purposes
Regulatory Adherence - Meeting international standards for payment processing
Streamlined Documentation - Centralized invoice management system

What's Changed

Invoice Upload Requirement - All payin and payout transactions now require a pre-uploaded invoice
API Parameter Addition - invoiceId is now a mandatory field in payin and payout creation requests
Validation Enhanced - System validates invoice presence before processing transactions
Error Handling Updated - New error responses for missing or invalid invoice IDs

What Remains Unchanged

Existing API Endpoints - All current endpoint URLs remain the same
Transaction Processing - Core payment processing logic remains identical
Response Formats - API response structures maintain backward compatibility

Action Required

Update Integration Code - Modify your payin and payout creation flows to:
- First call the Upload Invoice API to get an invoiceId
- Include the invoiceId parameter in payin/payout requests
Test in Sandbox - Validate the new flow using the sandbox environment
Update Error Handling - Handle new validation errors for missing invoices

Migration Timeline

Announcement Date: June 3rd, 2025
Mandatory Implementation: June 13th, 2025
Enforcement: All transactions without valid invoiceId field will fail after June 13th, 2025

Support

For migration issues or technical questions regarding invoice implementation, please contact our development team through the respective communication channels.

Example Usage

# Step 1: Upload Invoice
curl -X POST https://sandbox-api.transfi.com/v2/invoices/create \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "deposit",
    "email": "[email protected]",
    "invoice": "dummy-file.pdf",
    "invoiceType": "invoice"
  }'

# Response: { "invoiceId": "IN-250527142029127" }

# Step 2: Create Payin with Invoice ID
curl -X POST https://sandbox-api.transfi.com/v2/orders/deposit \
  -H "Content-Type: application/json" \
  -d '{
    // ... other required parameters,
    "invoiceId": "IN-250527142029127"
  }'

# Step 1: Upload Invoice
curl -X POST https://sandbox-api.transfi.com/v2/invoices/create \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "withdraw",
    "email": "[email protected]",
    "invoice": "dummy-file.pdf",
    "invoiceType": "invoice"
  }'

# Response: { "invoiceId": "IN-250527142029127" }

# Step 2: Create Payout with Invoice ID
curl -X POST https://sandbox-api.transfi.com/v2/payout/orders \
  -H "Content-Type: application/json" \
  -d '{
    // ... other required parameters,
    "invoiceId": "IN-250527142029127"
  }'