API Update: Mandatory `purposeCodeReason` for 'other' Purpose Code

To enhance transaction clarity and improve regulatory compliance, we are introducing a mandatory purposeCodeReason field for specific API requests. This change will affect all endpoints where purposeCode is set to other.

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

Affected API Endpoints

This change applies to the following three API endpoints:

1. Create Fiat Payin / Onramp Order

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 to provide a brief explanation for the transaction's purpose.

Updated Example Request:

curl --request POST \
     --url [https://sandbox-api.transfi.com/v2/orders/deposit](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](https://www.example.com)",
  "sourceUrl": "[https://www.example.com](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](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](http://www.example.com)",
  "sourceUrl": "[http://www.example.com](http://www.example.com)"
}
'

3. Create Fiat Payout / Offramp 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](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 a clear reason 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: It removes ambiguity for transactions that do not fit standard categories, reducing the need for manual follow-ups.

Changes Introduced

• 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

• ExistingpurposeCode Values: All other purposeCode values (e.g., expense_or_medical_reimbursement, salary_payout) 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.

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. Update Request Payloads: Modify your integration to include the purposeCodeReason field in the request body whenever purposeCode is "other". This may involve updating your UI to capture this reason from the user if applicable.
3. Test in Sandbox: Thoroughly test the updated integration in our sandbox environment to ensure your requests are successful and handle the new field correctly.
4. Deploy Before Deadline: Deploy your changes to production before July 1st, 2025, to avoid any disruption of service.

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.