メインコンテンツへスキップ

受取人管理

受取人は、振込を受け取ることができる銀行口座です。このガイドでは、受取人を作成、検証、および管理する方法について説明します。

概要​

受取人は以下を可能にします:

  • 銀行口座の保存: 銀行詳細を安全に保存
  • 検証と確認: KYCプロセスにより詳細を確認
  • 複数の受取人: 複数の銀行口座を管理
  • 振込: 受取人への資金送信
  • スケジュール: 受取人への定期出金

受取人の作成​

基本的な受取人作成​

const omise = require('omise')({
  secretKey: 'skey_test_123456789'
});

async function createRecipient(bankDetails) {
  const recipient = await omise.recipients.create({
    name: bankDetails.accountHolder,
    email: bankDetails.email,
    description: bankDetails.description,
    bank_account: {
      brand: bankDetails.bankCode,
      number: bankDetails.accountNumber,
      name: bankDetails.accountHolder
    }
  });

  console.log('受取人作成:', recipient.id);
  console.log('ステータス:', recipient.active ? 'アクティブ' : '非アクティブ');
  console.log('検証済み:', recipient.verified ? 'はい' : 'いいえ');

  return recipient;
}

// 使用例
createRecipient({
  accountHolder: 'John Doe',
  email: 'john@example.com',
  description: 'メインベンダーアカウント',
  bankCode: 'bbl', // バンコク銀行
  accountNumber: '1234567890'
});
import omise

omise.api_secret = 'skey_test_123456789'

def create_recipient(bank_details):
    """銀行口座受取人を作成"""
    recipient = omise.Recipient.create(
        name=bank_details['account_holder'],
        email=bank_details['email'],
        description=bank_details['description'],
        bank_account={
            'brand': bank_details['bank_code'],
            'number': bank_details['account_number'],
            'name': bank_details['account_holder']
        }
    )

    print(f"受取人作成: {recipient.id}")
    print(f"アクティブ: {recipient.active}")
    print(f"検証済み: {recipient.verified}")

    return recipient

受取人の取得と一覧表示​

単一の受取人を取得​

async function getRecipient(recipientId) {
  const recipient = await omise.recipients.retrieve(recipientId);

  console.log('受取人:', recipient.name);
  console.log('メール:', recipient.email);
  console.log('銀行:', recipient.bank_account.brand);
  console.log('末尾4桁:', recipient.bank_account.last_digits);
  console.log('検証済み:', recipient.verified);
  console.log('アクティブ:', recipient.active);

  return recipient;
}

すべての受取人を一覧表示​

async function listRecipients(status = 'verified') {
  const recipients = await omise.recipients.list({
    limit: 100,
    order: 'reverse_chronological'
  });

  recipients.data.forEach(recipient => {
    console.log(`${recipient.id}: ${recipient.name} (${recipient.verified ? '検証済み' : '未検証'})`);
  });

  return recipients;
}

受取人の更新​

受取人情報を更新​

async function updateRecipient(recipientId, updates) {
  const recipient = await omise.recipients.update(recipientId, {
    name: updates.name,
    email: updates.email,
    description: updates.description,
    metadata: updates.metadata
  });

  console.log('受取人更新:', recipient.id);
  return recipient;
}

銀行口座を更新​

async function updateBankAccount(recipientId, bankDetails) {
  const recipient = await omise.recipients.update(recipientId, {
    bank_account: {
      brand: bankDetails.bankCode,
      number: bankDetails.accountNumber,
      name: bankDetails.accountHolder
    }
  });

  console.log('銀行口座更新');
  return recipient;
}

受取人の検証​

検証プロセス​

def verify_recipient(recipient_id):
    """受取人を手動で検証(サポート権限が必要)"""
    recipient = omise.Recipient.retrieve(recipient_id)

    if recipient.verified:
        print(f"受取人{recipient_id}は既に検証済みです")
        return recipient

    # 検証ドキュメントをアップロード
    verification = omise.Recipient.verify(
        recipient_id,
        documents={
            'id_document': open('id.pdf', 'rb'),
            'bank_account_verification': open('bank_verification.pdf', 'rb')
        }
    )

    print(f"{recipient_id}の検証を送信しました")
    return verification

検証ステータスを確認​

async function checkVerificationStatus(recipientId) {
  const recipient = await omise.recipients.retrieve(recipientId);

  const status = {
    id: recipient.id,
    name: recipient.name,
    verified: recipient.verified,
    active: recipient.active,
    verification_status: recipient.verification?.status,
    created: recipient.created_at
  };

  console.log('検証ステータス:', JSON.stringify(status, null, 2));
  return status;
}

受取人の削除​

受取人を削除​

async function deleteRecipient(recipientId) {
  const result = await omise.recipients.destroy(recipientId);

  console.log('受取人削除:', result.id);
  console.log('削除済み:', result.deleted);

  return result;
}

一般的なユースケース​

ベンダー管理システム​

class VendorRecipientManager:
    def __init__(self):
        pass

    def create_vendor_recipient(self, vendor_info):
        """ベンダー情報から受取人を作成"""
        recipient = omise.Recipient.create(
            name=vendor_info['vendor_name'],
            email=vendor_info['contact_email'],
            description=f"{vendor_info['vendor_category']} - {vendor_info['vendor_id']}",
            bank_account={
                'brand': vendor_info['bank_code'],
                'number': vendor_info['account_number'],
                'name': vendor_info['account_holder_name']
            },
            metadata={
                'vendor_id': vendor_info['vendor_id'],
                'vendor_category': vendor_info['vendor_category'],
                'tax_id': vendor_info['tax_id']
            }
        )

        return recipient

    def bulk_create_vendors(self, vendor_list):
        """複数のベンダーを一括作成"""
        results = {
            'created': [],
            'failed': []
        }

        for vendor in vendor_list:
            try:
                recipient = self.create_vendor_recipient(vendor)
                results['created'].append({
                    'vendor_id': vendor['vendor_id'],
                    'recipient_id': recipient.id
                })
                print(f"✓ {vendor['vendor_name']}の受取人を作成しました")

            except Exception as e:
                results['failed'].append({
                    'vendor_id': vendor['vendor_id'],
                    'error': str(e)
                })
                print(f"✗ 失敗: {vendor['vendor_name']} - {str(e)}")

        return results

従業員給与システム​

class EmployeePaymentManager {
  async createEmployeeRecipients(employees) {
    const recipients = [];

    for (const employee of employees) {
      try {
        const recipient = await omise.recipients.create({
          name: employee.fullName,
          email: employee.email,
          description: `従業員: ${employee.employeeId}`,
          bank_account: {
            brand: employee.bankCode,
            number: employee.accountNumber,
            name: employee.fullName
          },
          metadata: {
            employee_id: employee.employeeId,
            department: employee.department,
            position: employee.position,
            salary: employee.baseSalary
          }
        });

        recipients.push({
          employeeId: employee.employeeId,
          recipientId: recipient.id,
          status: 'created'
        });

        console.log(`✓ ${employee.fullName}を作成しました`);

      } catch (error) {
        recipients.push({
          employeeId: employee.employeeId,
          error: error.message,
          status: 'failed'
        });
      }
    }

    return recipients;
  }

  async updateEmployeeSalary(recipientId, newSalary) {
    const recipient = await omise.recipients.retrieve(recipientId);

    await omise.recipients.update(recipientId, {
      metadata: {
        ...recipient.metadata,
        salary: newSalary,
        salary_updated_at: new Date().toISOString()
      }
    });

    console.log(`${recipient.name}の給与を更新しました`);
  }
}

ベストプラクティス​

1. 受取人を作成する前に検証​

function validateBankDetails(bankDetails) {
  const errors = [];

  if (!bankDetails.accountHolder) {
    errors.push('口座名義人名が必要です');
  }

  if (!bankDetails.accountNumber || bankDetails.accountNumber.length < 8) {
    errors.push('無効な口座番号です');
  }

  if (!bankDetails.bankCode) {
    errors.push('銀行コードが必要です');
  }

  if (!bankDetails.email || !bankDetails.email.includes('@')) {
    errors.push('有効なメールアドレスが必要です');
  }

  return {
    valid: errors.length === 0,
    errors: errors
  };
}

async function createValidatedRecipient(bankDetails) {
  const validation = validateBankDetails(bankDetails);

  if (!validation.valid) {
    throw new Error(`検証エラー: ${validation.errors.join(', ')}`);
  }

  return await omise.recipients.create({
    name: bankDetails.accountHolder,
    email: bankDetails.email,
    bank_account: {
      brand: bankDetails.bankCode,
      number: bankDetails.accountNumber,
      name: bankDetails.accountHolder
    }
  });
}

2. メタデータを使用して受取人をリンク​

async function createLinkedRecipient(bankDetails, internalId) {
  const recipient = await omise.recipients.create({
    name: bankDetails.accountHolder,
    email: bankDetails.email,
    description: `内部ID: ${internalId}`,
    bank_account: {
      brand: bankDetails.bankCode,
      number: bankDetails.accountNumber,
      name: bankDetails.accountHolder
    },
    metadata: {
      internal_id: internalId,
      created_at: new Date().toISOString(),
      source: 'api',
      department: bankDetails.department
    }
  });

  return recipient;
}

よくある質問​

受取人情報をどのように検証しますか?​

受取人は自動的に検証されるか、支援者による手動検証が必要な場合があります。KYC(顧客確認)プロセスに従って、本人確認および銀行口座の証明書をアップロードしてください。

受取人を削除できますか?​

はい、受取人を削除できます。ただし、その受取人への保留中のスケジュール振込がある場合、それらは処理されます。

1つのアカウントで何人の受取人を持つことができますか?​

受取人の数に厳密な制限はありませんが、アクティブな受取人の管理を推奨します。

受取人のメールアドレスを更新できますか?​

はい、受取人のメールアドレスとその他の詳細を更新できます。ただし、銀行口座の詳細の変更は新しい検証が必要な場合があります。

タイ以外の銀行口座の受取人を作成できますか?​

現在、Omiseはタイの銀行口座への振込のみをサポートしています。

受取人がアクティブでない場合はどうなりますか?​

その受取人への振込を作成することはできません。Omiseサポートに連絡して、受取人のステータスを確認してください。

関連リソース​