Natural Person Condensed Flow

Create complete transactions between individuals (natural persons) with automatic KYC screening in a single API call.

Use Case

Perfect for individual-to-individual transactions where both the originator and beneficiary are natural persons (not corporations or legal entities).

Request

Endpoint: POST https://api.trpcontinuum.com/trp/transactions/condensed

Headers:

Content-Type: application/json
Authorization: Bearer {your-token}

Request Body:

{
  "transaction": {
    "network": "bitcoin",
    "virtualAsset": "Bitcoin (BTC)",
    "amount": "100.50",
    "beneficiaryWalletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "originatorWalletAddress": "bc1qabc123def456ghi789jkl012mno345pqr678stu",
    "memo": "Payment for invoice #123",
    "purpose": "Commercial payment"
  },
  "beneficiary": {
    "beneficiaryVaspId": "vasp_123456",
    "beneficiaryIsLegalPerson": false,
    "beneficiaryFirstName": "Jane",
    "beneficiaryLastName": "Smith",
    "dateOfBirth": "1990-05-15",
    "placeOfBirth": "New York, NY",
    "nationality": "US",
    "beneficiaryIdNumber": "123456789",
    "beneficiaryIdType": "PASSPORT",
    "beneficiaryIdCountryOfIssue": "US",
    "buildingNumber": "123",
    "streetName": "Main Street",
    "townName": "New York",
    "postCode": "10001",
    "country": "US"
  },
  "originator": {
    "originatorIsLegalPerson": false,
    "originatorFirstName": "John",
    "originatorLastName": "Doe",
    "originatorDob": "1985-03-20",
    "originatorPlaceOfBirth": "Chicago, IL",
    "originatorIdNumber": "987654321",
    "originatorIdType": "PASSPORT",
    "originatorIdCountryOfIssue": "US",
    "originatorAddressLine1": "456 Oak Street",
    "originatorAddressLine2": "Apt 5B",
    "originatorCity": "San Francisco",
    "originatorState": "CA",
    "originatorPostalCode": "94102",
    "originatorCountry": "US"
  },
  "forceApproveKyc": false
}

Response Examples

Success (No KYC Matches)

{
  "success": true,
  "data": {
    "id": "txn_abc123",
    "status": "Client Info Pending Send",
    "network": "bitcoin",
    "virtualAsset": "Bitcoin (BTC)",
    "amount": "100.50",
    "beneficiaryWalletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "originatorWalletAddress": "bc1qabc123def456ghi789jkl012mno345pqr678stu",
    "beneficiary": {
      "beneficiaryFirstName": "Jane",
      "beneficiaryLastName": "Smith",
      "beneficiaryVaspId": "vasp_123456"
    },
    "originator": {
      "originatorFirstName": "John",
      "originatorLastName": "Doe"
    },
    "kycCheck": {
      "hasMatches": false,
      "totalMatches": 0,
      "beneficiaryChecked": true,
      "originatorChecked": true,
      "screenedAt": "2024-08-07T10:00:00Z"
    },
    "createdAt": "2024-08-07T10:00:00Z",
    "updatedAt": "2024-08-07T10:00:00Z"
  }
}

Success (KYC Matches Found)

{
  "success": true,
  "message": "Transaction created but requires KYC approval due to matches found. Use http://localhost:5001/api/trp/transactions/1fe7918c-0d58-49a6-a55a-ae3b919d1db8/kyc-check/approve to approve and automatically send, or http://localhost:5001/api/trp/transactions/1fe7918c-0d58-49a6-a55a-ae3b919d1db8/kyc-check/reject to reject.",
  "data": {
    "id": "1fe7918c-0d58-49a6-a55a-ae3b919d1db8",
    "status": "KYC Beneficiary Pending Review",
    "kycCheck": {
      "hasMatches": true,
      "totalMatches": 5,
      "requiresReview": true,
      "approvalEndpoint": "http://localhost:5001/api/trp/transactions/1fe7918c-0d58-49a6-a55a-ae3b919d1db8/kyc-check/approve",
      "rejectionEndpoint": "http://localhost:5001/api/trp/transactions/1fe7918c-0d58-49a6-a55a-ae3b919d1db8/kyc-check/reject",
      "performedAt": "2025-08-27T16:20:10.609Z",
      "riskLevel": "critical",
      "highestScore": 0.9,
      "kycDetails": {
        "matches": [
          {
            "id": "us-fed-excl-patricia-jane-smith-32456-port-st-joe",
            "caption": "PATRICIA JANE SMITH",
            "schema": "Person",
            "score": 0.9,
            "datasets": ["us_sam_exclusions"],
            "properties": {
              "name": ["PATRICIA JANE SMITH"],
              "firstName": ["PATRICIA"],
              "middleName": ["JANE"],
              "lastName": ["SMITH"],
              "address": ["PORT ST. JOE, FL 32456, USA"],
              "country": ["us"],
              "topics": ["debarment"]
            }
          }
        ],
        "reason": "Found 5 potential matches in sanctions/PEP databases",
        "source": "OpenSanctions"
      }
    }
  }
}

Required Fields

Transaction

network - Blockchain network (e.g., "bitcoin", "ethereum")
virtualAsset - Asset name (e.g., "Bitcoin (BTC)")
amount - Transaction amount as string
beneficiaryWalletAddress - Recipient wallet address
originatorWalletAddress - Sender wallet address

Beneficiary (Natural Person)

beneficiaryVaspId - Target VASP identifier
beneficiaryIsLegalPerson - Must be false
beneficiaryFirstName - First name
beneficiaryLastName - Last name
dateOfBirth - Birth date (YYYY-MM-DD format)
country - Country code (ISO 3166-1 alpha-2)

Originator (Natural Person)

originatorIsLegalPerson - Must be false
originatorFirstName - First name
originatorLastName - Last name
originatorDob - Birth date (YYYY-MM-DD format)
originatorCountry - Country code (ISO 3166-1 alpha-2)

Optional Fields

Enhanced Beneficiary Data

placeOfBirth - Place of birth
nationality - Nationality code
beneficiaryIdNumber - ID document number
beneficiaryIdType - ID type ("PASSPORT", "NATIONAL_ID", "DRIVERS_LICENSE")
beneficiaryIdCountryOfIssue - Issuing country
Address fields: buildingNumber, streetName, townName, postCode

Enhanced Originator Data

originatorPlaceOfBirth - Place of birth
originatorIdNumber - ID document number
originatorIdType - ID type
originatorIdCountryOfIssue - Issuing country
Address fields: originatorAddressLine1, originatorAddressLine2, originatorCity, originatorState, originatorPostalCode

Transaction Metadata

memo - Transaction description
purpose - Transaction purpose

KYC Processing

Automatic Screening

The system automatically screens both beneficiary and originator against:

Sanctions Lists: OFAC, EU, UN sanctions
PEP Lists: Politically Exposed Persons
Watchlists: High-risk individuals
Adverse Media: Negative news screening

Match Scoring

0.0 - 0.5: Low risk, auto-approve
0.5 - 0.8: Medium risk, may require review
0.8 - 1.0: High risk, manual review required

Review Required

If matches are found with scores above threshold:

Transaction status: KYC Beneficiary Pending Review
Manual review required via KYC Review Process
Compliance officer approves/rejects

Next Steps

No KYC Matches

After successful creation with no matches:

Status: Client Info Pending Send
Next: Use Send to Beneficiary VASP API
Continue: Follow standard transaction completion flow

KYC Matches Found

When matches require review:

Status: KYC Beneficiary Pending Review
Next: Use KYC Review Process to approve/reject
After Approval: Status becomes Client Info Pending Send
Continue: Follow standard transaction completion flow

Code Examples

JavaScript/Node.js

const axios = require('axios');

async function createNaturalPersonTransaction() {
  try {
    const response = await axios.post('https://api.trpcontinuum.com/trp/transactions/condensed', {
      transaction: {
        network: "bitcoin",
        virtualAsset: "Bitcoin (BTC)",
        amount: "100.50",
        beneficiaryWalletAddress: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        originatorWalletAddress: "bc1qabc123def456ghi789jkl012mno345pqr678stu",
        memo: "Payment for services",
        purpose: "Commercial payment"
      },
      beneficiary: {
        beneficiaryVaspId: "vasp_123456",
        beneficiaryIsLegalPerson: false,
        beneficiaryFirstName: "Jane",
        beneficiaryLastName: "Smith",
        dateOfBirth: "1990-05-15",
        country: "US"
      },
      originator: {
        originatorIsLegalPerson: false,
        originatorFirstName: "John",
        originatorLastName: "Doe",
        originatorDob: "1985-03-20",
        originatorCountry: "US"
      }
    }, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });

    if (response.data.success) {
      const transaction = response.data.data;
      
      if (transaction.kycCheck.hasMatches) {
        console.log(`Transaction ${transaction.id} held for KYC review`);
        console.log(`Found ${transaction.kycCheck.totalMatches} potential matches`);
        // Handle KYC review process
      } else {
        console.log(`Transaction ${transaction.id} created successfully`);
        console.log(`Status: ${transaction.status}`);
        // Proceed to send to beneficiary
      }
    }
  } catch (error) {
    console.error('Transaction creation failed:', error.response?.data);
  }
}

Python

import requests

def create_natural_person_transaction():
    payload = {
        "transaction": {
            "network": "bitcoin",
            "virtualAsset": "Bitcoin (BTC)",
            "amount": "100.50",
            "beneficiaryWalletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
            "originatorWalletAddress": "bc1qabc123def456ghi789jkl012mno345pqr678stu",
            "memo": "Payment for services",
            "purpose": "Commercial payment"
        },
        "beneficiary": {
            "beneficiaryVaspId": "vasp_123456",
            "beneficiaryIsLegalPerson": False,
            "beneficiaryFirstName": "Jane",
            "beneficiaryLastName": "Smith",
            "dateOfBirth": "1990-05-15",
            "country": "US"
        },
        "originator": {
            "originatorIsLegalPerson": False,
            "originatorFirstName": "John",
            "originatorLastName": "Doe",
            "originatorDob": "1985-03-20",
            "originatorCountry": "US"
        }
    }
    
    response = requests.post(
        'https://api.trpcontinuum.com/trp/transactions/condensed',
        json=payload,
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    if response.status_code == 200:
        data = response.json()
        if data['success']:
            transaction = data['data']
            
            if transaction['kycCheck']['hasMatches']:
                print(f"Transaction {transaction['id']} held for KYC review")
                print(f"Found {transaction['kycCheck']['totalMatches']} potential matches")
            else:
                print(f"Transaction {transaction['id']} created successfully")
                print(f"Status: {transaction['status']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")

Common Errors

Validation Errors

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Missing required fields",
  "details": {
    "missing_fields": ["beneficiaryFirstName", "originatorDob"],
    "invalid_fields": {
      "dateOfBirth": "Invalid date format, expected YYYY-MM-DD"
    }
  }
}

VASP Not Found

{
  "success": false,
  "error": "VASP_NOT_FOUND",
  "message": "Beneficiary VASP not found or inactive",
  "details": {
    "vaspId": "invalid_vasp_123",
    "suggestion": "Use /trp/vasps/search to find valid VASPs"
  }
}

Network Mismatch

{
  "success": false,
  "error": "NETWORK_MISMATCH",
  "message": "Wallet address does not match specified network",
  "details": {
    "network": "bitcoin",
    "address": "0x1234...",
    "expectedFormat": "bc1... or 1... or 3..."
  }
}

Testing

Test Data

Use these sample values for testing:

Low Risk (No Matches):

Beneficiary: "Test User" / DOB: "1990-01-01"
Originator: "Demo Person" / DOB: "1985-01-01"

High Risk (Will Generate Matches):

Beneficiary: "Vladimir Putin" / DOB: "1952-10-07"
Originator: "Kim Jong Un" / DOB: "1984-01-08"

Force Approve for Testing

{
  // ... transaction data ...
  "forceApproveKyc": true
}

⚠️ Never use forceApproveKyc: true in production!

Use Case​

Request​

Response Examples​

Success (No KYC Matches)​

Success (KYC Matches Found)​

Required Fields​

Transaction​

Beneficiary (Natural Person)​

Originator (Natural Person)​

Optional Fields​

Enhanced Beneficiary Data​

Enhanced Originator Data​

Transaction Metadata​

KYC Processing​

Automatic Screening​

Match Scoring​

Review Required​

Next Steps​

No KYC Matches​

KYC Matches Found​

Code Examples​

JavaScript/Node.js​

Python​

Common Errors​

Validation Errors​

VASP Not Found​

Network Mismatch​

Testing​

Test Data​

Force Approve for Testing​