Sandbox LoginProduction Login
Changelog
Start typing to search…
Back to All
added

API Update: Enhanced Purpose Codes & Mandatory Reason Field

29 days ago by Sumanth M Devadiga

To enhance transaction clarity and improve regulatory compliance, we are introducing significant updates to the purposeCode field across our API endpoints. This includes both an expanded list of purpose codes and a mandatory purposeCodeReason field for specific scenarios.

This is a breaking change for existing integrations that usepurposeCode: "other". The deadline to implement this change is August 1st, 2025. After this date, API calls using purposeCode: "other" without the corresponding purposeCodeReason will fail.


What's New

1. Enhanced Purpose Code Options

We've significantly expanded the available purposeCode values to provide better categorization for transactions. The complete list now includes 47 specific purpose codes covering various business and personal transaction types.

📋View Complete Purpose Code List

Key Categories Added:

  • Business Operations: COMPANY_EXPENSES, BUSINESS_OPERATION_EXPENSES, VENDOR_PAYMENT
  • Gaming & Entertainment: GAMING_TOP_UPS, GAMING_WITHDRAWALS, GAMING_FEES
  • Investment & Trading: SHARES_INVESTMENT, FUND_INVESTMENT, ARBITRAGE_TRADING
  • Real Estate: PROPERTY_PURCHASE, PROPERTY_RENTAL, CONSTRUCTION_EXPENSES
  • Healthcare: HEALTHCARE_EXPENSES, MEDICAL_EXPENSES, INSURANCE_CLAIMS
  • Personal Transfers: FRIENDS_AND_FAMILY_TRANSFER, GIFT_AND_DONATION, HOUSEHOLD_SUPPORT
  • Treasury Operations: LIQUIDITY_MANAGEMENT, TREASURY_RECONCILIATION, MARKET_MAKING

2. Mandatory Purpose Code Reason Field

When purposeCode is set to "other", you must now include the purposeCodeReason field to provide a brief explanation for the transaction's purpose.


Affected API Endpoints

This change applies to the following three API endpoints:

1. Create Fiat Payin API

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

Change: When purposeCode in the request body is "other", you must now include the purposeCodeReason field.

Updated Example Request:

curl --request POST \
     --url https://sandbox-api.transfi.com/v2/orders/deposit \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentType": "bank_transfer",
  "purposeCode": "other",
  "purposeCodeReason": "Paying for custom freelance graphic design work",
  "amount": 10000,
  "currency": "PHP",
  "email": "[email protected]",
  "redirectUrl": "https://www.example.com",
  "sourceUrl": "https://www.example.com",
  "invoiceId": "IN-398749283649"
}
'

2. Create Fiat Payin with Wallet API (iGaming)

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

Change: Similar to the standard payin, if purposeCode is "other", the purposeCodeReason field becomes mandatory.

Updated Example Request:

curl --request POST \
     --url https://sandbox-api.transfi.com/v2/orders/gaming \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentType": "bank_transfer",
  "purposeCode": "other",
  "purposeCodeReason": "Purchase of special event in-game items",
  "amount": 25,
  "currency": "EUR",
  "email": "[email protected]",
  "redirectUrl": "http://www.example.com",
  "sourceUrl": "http://www.example.com"
}
'

3. Create Fiat Payout API

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

Change: For all payouts where the purposeCode is "other", a purposeCodeReason must be supplied.

Updated Example Request:

curl --request POST \
     --url https://sandbox-api.transfi.com/v2/payout/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "purposeCode": "other",
  "purposeCodeReason": "Refund for order #RF-98765",
  "amount": 500,
  "email": "[email protected]",
  "currency": "PHP",
  "paymentCode": "gcash",
  "invoiceId": "IN-252387389423"
}
'

Reasons for Implementation

  • Enhanced Compliance: Providing detailed purpose codes and clear reasons for transactions categorized as 'other' helps us and our partners meet evolving regulatory requirements for transaction monitoring.
  • Improved Data Quality: This change ensures that we capture more precise information about the nature of payments, leading to better analytics and reporting.
  • Reduced Ambiguity: The expanded purpose code options reduce the need for using "other" while the mandatory reason field removes ambiguity for edge cases.
  • Better User Experience: More specific purpose codes provide clearer categorization for end users and reduce manual follow-ups.

Changes Introduced

  • 47 New Purpose Code Options: A comprehensive list of specific purpose codes covering various transaction types
  • New Conditional Field: A new string field, purposeCodeReason, is now required for the body of the three listed endpoints if and only if purposeCode is set to "other"

What Remains Unchanged

  • Existing Purpose Code Values: All existing purposeCode values continue to function as before without any changes
  • Authentication & Other Parameters: All other API parameters, headers, and authentication methods remain the same
  • Webhook Events: Webhook notification structures are not affected by this change

Migration Guide

For Integrations Using Specific Purpose Codes

If you're already using specific purpose codes (not "other"), no changes are required. Your existing integrations will continue to work seamlessly.

For Integrations Using "other" Purpose Code

  1. Review Transaction Types: Analyze your current transactions using purposeCode: "other" to see if they can be categorized using the new specific purpose codes
  2. Update to Specific Codes: Where possible, replace "other" with the most appropriate specific purpose code from our enhanced list
  3. Add Reason Field: For transactions that truly require purposeCode: "other", add the mandatory purposeCodeReason field

Action Required

  1. Identify Affected Integrations: Review your codebase to find all API calls to the three affected endpoints where you are sending purposeCode: "other"
  2. Consider New Purpose Codes: Review the complete list of purpose codes and update your integration to use more specific codes where applicable
  3. Update Request Payloads: For any remaining usage of purposeCode: "other", modify your integration to include the purposeCodeReason field
  4. Test in Sandbox: Thoroughly test the updated integration in our sandbox environment
  5. Deploy Before Deadline: Deploy your changes to production before August 1st, 2025

Error Handling

After the deadline, if you send purposeCode: "other" without purposeCodeReason, the API will return a 400 Bad Request status code with an error message similar to this:

{
    "message": "Invalid purposeCodeReason. Please provide a clear and specific reason with at least 10 characters, avoiding vague terms.",
    "code": "INVALID_ARGUMENTS"
}

Please ensure your error handling logic is prepared to manage this response.


Support

If you have any questions about this change or need assistance with your integration, please do not hesitate to contact our technical support team via the usual channels.

📋Complete Purpose Code Reference