Golang ACH 文件处理与验证：ach 库使用指南

ACH (Automated Clearing House) 是美国常用的电子资金转账系统，用于银行间批量交易处理。在Go语言中，ach 库提供了创建、读取和验证ACH文件的功能。

安装 ach 库

go get github.com/moov-io/ach

基本使用示例

1. 创建 ACH 文件

package main

import (
	"fmt"
	"time"
	
	"github.com/moov-io/ach"
)

func main() {
	// 创建新的ACH文件头
	fileHeader := ach.NewFileHeader()
	fileHeader.ImmediateDestination = "231380104" // 接收方路由号码
	fileHeader.ImmediateOrigin = "121042882"     // 发起方路由号码
	fileHeader.FileCreationDate = time.Now().Format("060102") // YYMMDD
	fileHeader.FileCreationTime = time.Now().Format("1504")    // HHMM
	fileHeader.ImmediateDestinationName = "Federal Reserve Bank"
	fileHeader.ImmediateOriginName = "My Bank Name"
	fileHeader.ReferenceCode = "12345678"

	// 创建新的ACH文件
	file := ach.NewFile()
	file.SetHeader(fileHeader)

	// 创建批次
	batchHeader := ach.NewBatchHeader()
	batchHeader.ServiceClassCode = ach.CreditsOnly
	batchHeader.CompanyName = "Company Name"
	batchHeader.CompanyIdentification = file.Header.ImmediateOrigin
	batchHeader.StandardEntryClassCode = ach.PPD
	batchHeader.CompanyEntryDescription = "PAYROLL"
	batchHeader.EffectiveEntryDate = time.Now().AddDate(0, 0, 1).Format("060102") // 明天
	batchHeader.ODFIIdentification = "12104288" // 前8位路由号码

	// 创建批次并添加到文件
	batch, err := ach.NewBatch(batchHeader)
	if err != nil {
		fmt.Printf("Error creating batch: %v\n", err)
		return
	}

	// 创建条目
	entry := ach.NewEntryDetail()
	entry.TransactionCode = ach.CheckingCredit
	entry.SetRDFI("231380104") // 接收方路由号码
	entry.DFIAccountNumber = "12345678"
	entry.Amount = 100000 // 1000美元（以分为单位）
	entry.IdentificationNumber = "1234567890"
	entry.IndividualName = "Receiver Name"
	entry.SetTraceNumber(batchHeader.ODFIIdentification, 1)
	entry.Category = ach.CategoryForward

	// 将条目添加到批次
	batch.AddEntry(entry)
	if err := batch.Create(); err != nil {
		fmt.Printf("Error creating batch: %v\n", err)
		return
	}

	// 将批次添加到文件
	file.AddBatch(batch)
	if err := file.Create(); err != nil {
		fmt.Printf("Error creating file: %v\n", err)
		return
	}

	// 输出ACH文件内容
	fmt.Println(file.String())
}

2. 读取和验证ACH文件

package main

import (
	"fmt"
	"log"
	
	"github.com/moov-io/ach"
)

func main() {
	// 示例ACH文件内容
	achFileContents := `101 231380104 1210428820610121504A094101Federal Reserve BankMy Bank Name     12345678
5225Company Name                        PPDPAYROLL   061013   1121042880000001
62723138010412345678         00001000001234567890       Receiver Name       0121042880000001
822500000100231380104000000000000001000000000000001121042880000001
90000010000010000000100231380104000000000000001000000000000001121042880000001`

	// 从字符串读取ACH文件
	file, err := ach.NewReader([]byte(achFileContents)).Read()
	if err != nil {
		log.Fatalf("Error reading ACH file: %v", err)
	}

	// 验证文件
	if err := file.Validate(); err != nil {
		log.Fatalf("ACH file validation failed: %v", err)
	}

	// 输出文件信息
	fmt.Printf("File Header: %+v\n", file.Header)
	for i, batch := range file.Batches {
		fmt.Printf("Batch %d Header: %+v\n", i+1, batch.GetHeader())
		for j, entry := range batch.GetEntries() {
			fmt.Printf("  Entry %d: %+v\n", j+1, entry)
		}
		fmt.Printf("Batch %d Control: %+v\n", i+1, batch.GetControl())
	}
	fmt.Printf("File Control: %+v\n", file.Control)
}

3. 高级功能

自定义验证规则

// 自定义验证函数
func customValidate(file *ach.File) error {
	// 检查文件是否包含至少一个批次
	if len(file.Batches) == 0 {
		return fmt.Errorf("file must contain at least one batch")
	}
	
	// 检查总金额是否超过限额
	total := 0
	for _, batch := range file.Batches {
		for _, entry := range batch.GetEntries() {
			total += entry.Amount
		}
	}
	
	if total > 25000000 { // 250,000美元
		return fmt.Errorf("total amount exceeds limit")
	}
	
	return nil
}

func main() {
	file := createACHFile() // 假设这是创建ACH文件的函数
	
	// 先执行标准验证
	if err := file.Validate(); err != nil {
		log.Fatal(err)
	}
	
	// 再执行自定义验证
	if err := customValidate(file); err != nil {
		log.Fatal(err)
	}
	
	fmt.Println("File passed all validations")
}

处理不同SEC代码

func createBatch(secCode string) (*ach.Batch, error) {
	switch secCode {
	case ach.PPD:
		return createPPDBatch()
	case ach.CCD:
		return createCCDBatch()
	case ach.TEL:
		return createTELBatch()
	default:
		return nil, fmt.Errorf("unsupported SEC code: %s", secCode)
	}
}

func createPPDBatch() (*ach.Batch, error) {
	batchHeader := ach.NewBatchHeader()
	batchHeader.ServiceClassCode = ach.CreditsOnly
	batchHeader.CompanyName = "Company Name"
	batchHeader.StandardEntryClassCode = ach.PPD
	batchHeader.CompanyEntryDescription = "PAYROLL"
	
	batch, err := ach.NewBatch(batchHeader)
	if err != nil {
		return nil, err
	}
	
	// 添加PPD条目...
	
	return batch, batch.Create()
}

最佳实践

1. 验证所有输入：在创建ACH条目前验证所有字段
2. 错误处理：始终检查Create()和Validate()方法的错误
3. 金额处理：记住ACH金额以分为单位（1美元=100）
4. 日期格式：使用正确的日期格式(YYMMDD)
5. 测试：为不同SEC代码和边缘情况编写测试

总结

ach 库提供了强大的功能来处理ACH文件的创建、读取和验证。通过合理使用这个库，可以轻松实现银行间的电子资金转账功能。记得始终验证生成的文件，并处理所有可能的错误情况。