API Reference
Log In
API Reference

Purpose Codes

A payment purpose code is used to specify the intention behind a financial transaction. They are a regulatory requirement for some countries, to aid involved banking parties in tracking and classifying payments for compliance purposes.

Payment purpose codes must be supplied by the user for fx transfers to the following countries and currency combinations:

  • Malaysia (MY) - MYR payments
  • China (CN) - CNY payments
  • Bahrain (BH) - All currency payments
  • United Arab Emirates (AE) - All currency payments
  • India (IN) - INR payments

When presented with a list of potential purpose codes, the end user should select the available code which most closely reflects the intended nature of their transaction.

If there is no possible purpose code applicable to the transaction, this would indicate the transaction falls outside of expected account usage and we would therefore be unable to support the transfer.

List of Payment Purpose Codes

Crezco provides the same standardised list of payment purpose codes for all of the noted countries above. These purpose codes are (in alphabetical order):

  • BusinessAndAdvisoryServices - Business & Advisory Services
  • Construction - Construction
  • DirectEmployeeSalaries - Direct Employee Salaries (N.B: please see ‘Transactions to India’ section below)
  • Expenses - Expenses
  • Insurance - Insurance
  • IntellectualProperty - Intellectual Property
  • IntercompanyTransfer - Inter-company Transfer
  • InvestmentActivity - Investment Activity
  • PayingForGoods - Paying for goods
  • RealEstateAndProperty - Real Estate & Property

In terms of ordering the purpose code list, we would recommend alphabetically for efficient navigation. You might also consider ordering the list with your customers' most commonly used codes first.

We would also strongly recommend that you present the codes to the user verbatim as presented above. This ensures the purpose code applied to the payment is accurate and closely reflective of the selected description.


Additional Requirements for Transactions to India

Due to regulatory requirements from banking parties involved in INR transfers, transactions to India are subject to some additional requirements:

  1. Customers are required to supply two additional fields alongside their purpose code - an invoice number and invoice date
  • The invoice number must be between 1-30 characters in length
    • This should be the number present on the relevant invoice
    • The invoice number will be sent with the payment for compliance purposes
  • The invoice date should be should be in ISO 8601 format - YYYY-MM-DD

  1. Direct Employee Salaries is not a supported code for payments to India. We are therefore unable to support any INR transfers of this nature

    • Transactions related to outsourced resource costs should fall under the ‘Business & Advisory Services' purpose code, rather than ‘Direct Employee Salaries’
    • Crezco will tell you upfront in the API which codes are available for the given country and currency combination

Additional Requirements for Transactions to China

Due to regulatory requirements from banking parties involved in CNY transfers:

  • CNY payments to China can only be made to organisations. Payments to individuals are not currently permitted
  • CNY payments to all other countries do not have this restriction, and can be made to beneficiaries who are individuals or organisations

UX Recommendations

A payment purpose code functions to specify payment intention on a transaction-specific level. Crezco would therefore recommend that purpose code selection occurs at the point of bill creation ('New Bill') or when reviewing the bill before entering the payment flow ('Make Payment' screen).

Payment purpose code selection could also occur at the Contact Creation level, given that many XBP customers will be making recurring payments of the same nature to the same supplier. However, given the function of a purpose code the following would also need to be considered:

  • Customers must have the opportunity to review and amend the purpose code when creating or reviewing a bill, to account for the scenario that the transaction intention has changed since contact creation
  • For payments to India - customers will likely have an updated invoice number and invoice date with each new bill. Customers should therefore be prompted to update the invoice number and date when creating or reviewing a bill
    • If invoice date and invoice number are fields that already exists on the bill, you could consider inputting this automatically on behalf of the user instead of supplying additional fields