Make a payment API

v4.2.2

/MakeAPayment

POST
https://subdomain.transfermateeducation.com/MakeAPayment

Registers transactions with Transfermate system.

There are two possible payment flows for completing a payment – Direct and Redirect.
The payment flow depends on what payment method was selected by the payer.

Direct Payment Flow
In the Direct Payment Flow, payment instructions are returned which needs to be displayed to the payer in order to complete payment.
Note that certain data and documentation may be required depending on jurisdiction – a secure link will be included in the instructions XML element to allow the payer to upload this information.

Redirect Payment Flow
In the Redirect Payment Flow, a URL is returned to which the payer must be redirected in order to complete the payment.
The element that holds the Redirect URL is called: redirect_url.
You may also provide a URL (status_redirect_url) to which we will redirect the payer after he completes the payment.
We will append the below parameters to the status_redirect_url provided in the API call when we redirect the payer back to your website.

Parameter Name Example Value Description
tm_timestamp 1623755468 Unix timestamp.
tm_payment_status Successful The 3rd party payment status name.
Transfermate will rederect the payer back to your URL only when the third party status is either Successful or Cancelled.
tm_transaction_id 662539 The Payment ID that was generated by the Transfermate system at the time of the payment registration process.
tm_hmac_signature [hmac_signature] HMAC signature.
How to verify the HMAC Signature:
  1. Separate the tm_timestamp, tm_payment_status and tm_transaction_id parameter values with colons “:” and concatenate the Secret Key at the end.
    Example: 1623755468:Successful:662539:!TestSecret123!
  2. Apply the HMAC-SHA256 algorithm to the string produced in Step 1.
    The Computed HMAC should be: 195afba8e74637015e0f777f954e428546c970cb5094d94653129ce9d5439daf
  3. Compare the Computed HMAC against the value in the tm_hmac_signature parameter.
Note that certain data and documentation may be required depending on jurisdiction - a secure link will be generated and returned in the document_upload_url XML element which you need to display to the payer after he is redirected back to your website.

You will have to display the link in the following conditions:
  1. The document_upload_url element in the MakeAPayment response is not empty.
  2. The flow element in the MakeAPayment request is "redirect".
  3. The Payment Status (tm_payment_status) parameter value is "Successful".

Query Params

Parameter ID Example Value Data Type Max Char. Length / Range Required Condition Description
Account Related Parameters
username_loginto [username] string 255 Yes - API Username
password_loginto [password] string 255 Yes - API Password
bank_account_id 13004 (USD) integer - Yes - The Bank Account ID The Base Currency for the FX conversion will be derived from the Settlement Bank Account Details provided in the account setup stage.
Payment Related Parameters
payment_amount 1000.00 float - Yes - The amount that needs to be converted into the payers local currency. The payer local currency is derived from the country he pays from. (Country Pay From)
country_pay_from US string 2 Yes - The country code (ISO 3166-1 alpha-2 code) from which the payer is making the payment. You can call the Countries API to get a list with all country codes.
state US-WA string 6 Conditional When
Country Pay From is set to "US", "AU" or "CA" (USA, Australia or Canada)		 The ISO 3166-2 subdivision (state) code.
Reference:
USA: https://en.wikipedia.org/wiki/ISO_3166-2:US
Australia: https://en.wikipedia.org/wiki/ISO_3166-2:AU
Canada: https://en.wikipedia.org/wiki/ISO_3166-2:CA
Required if the conditions are met (see the Condition column)
india_fee_exceed 0 integer 0 - 1 Conditional When
Country Pay From is set to "IN" (India)		 Set to 1 if the payer is going to exceed the US$ 250,000 foreign exchange limit otherwise set to 0.
Usually this is a drop-down field containing three options:
"Please Select", "Yes" and "No".
The label of the field should say:
"Will you exceed the US $250,000 foreign exchange limit in the calendar year 01 April -31 March"
Required if the conditions are met (see the Condition column)
payment_purpose Tuition Fee string 255 Yes - The payment purpose.
Tuition Fee, Accommodation Fee etc.
payment_method 0 integer 0 - 100 Yes - This parameter indicates what payment method is to be used.
The values are as per the payment method IDs returned in the FXConversion API call.
edu_institute_name New York Institute of Technology string 255 Yes - The educational institute name.
order_id ORDER_ID_123 string 128 No - This parameter is related to the Webhook Notification Service.
If you want to receive webhook notifications on payment status change, you should provide this parameter.
It has to be unique per each payment.
Allowed characters:
All Latin alphanumeric characters
Special Characters: # @ & - _ = : ( ) . ; , { }
request_id REQUEST_ID_123 string 255 No - You can use this parameter to set an arbitrary Request ID which can be used to filter the payments in the Payment History request.
adi_id Example string 255 No - Free text filed in which you can store additional information. You will be able to filter the payments using this parameter in the Payment History request.
org_id Example string 255 No - Free text filed in which you can store additional information. You will be able to filter the payments using this parameter in the Payment History request.
location Location string 255 No - This parameter can be used to pass the recipient’s location to us.
status_redirect_url URL string 500 No - The URL where Transfermate will return the payer to once the payment is completed on Transfermate side.
This is only relevant if the Payment Method Flow is Redirect.
Please note that if you don't provide this URL, the payer will remain on the Transfermate website and you will receive the payment status via Webhook Push Notification.
webhook_url URL string 500 No - If this parameter is provided, Transfermate will ignore your Default Webhook URL and will send the webhook status notification to this URL. This parameter overrides the Default Webhook URL only for the current payment.
Payer Related Parameters
who_is_making_the_payment Parent of Student string 255 Yes - Student, Parent of Student, Student's Relative, Student's Agent, etc.
payer_name John Doe string 100 Yes - The payer's full name
payer_chinese_name 刘伟 string 50 Conditional When
Country Pay From is set to "CN" (China)		 The Payer Chinese name (Surname and Given Name) must be provided for all Chinese payments.
The name consists of only Chinese characters and must be longer than 1 character.
No spaces are allowed.
See https://en.wikipedia.org/wiki/Han_unification for validation purposes.
Required if the conditions are met (see the Condition column)
payer_nationality US string 2 Yes - Country code (ISO 3166-1 alpha-2 code).
You can call the Countries API to get a list with all country codes.
payer_city Seattle string 50 Yes - Payer City.
payer_address 3419 S 164th St string 255 Yes - The payer address.
payer_postal_code 98188 string 50 Yes - Payer Postal Code/ZIP.
payer_phone_number +12062441475 string 50 Yes - The payer’s phone number.
payer_email johndoe@example.com string 100 Yes - The payer's email address.
payer_unique_id UNIQ12345 string 255 No - This parameter can be used to set your own payer identification number (ID).
You can use this parameter to filter the payments in the Payment History request.
payer_document 078-05-1120 string 100 Conditional When
Country Pay From matches the Country ID in the reference doc.		 Payer Identification Number
Ref. Doc.:
https://transfermateeducation.com/example/api/4.2/references/payer-identification-number//

Required if the conditions are met (see the condition column)
Student Related Parameters
student_name Jane Doe string 100 Yes - The full name of the student
student_chinese_name 张秀英 string 50 Conditional When
Country Pay From is set to "CN" (China)		 The Student Chinese name (Surname and Given Name) must be provided for all Chinese payments.
The name consists of only Chinese characters and must be longer than 1 character.
No spaces are allowed.
See https://en.wikipedia.org/wiki/Han_unification for validation purposes.
Required if the conditions are met (see the Condition column)
student_country US string 2 Yes - Country code (ISO 3166-1 alpha-2 code).
You can call the Countries API to get a list with all country codes.
student_city Los Angeles string 50 Yes - The student’s city of residence.
student_address 5723 Morgan Ave string 255 Yes - The student's residence address.
student_postal_code 90011 string 50 Yes - Student’s Postal/Zip code.
student_phone_number +1323111111 string 50 Yes - The student’s phone number.
student_dob 2000-04-23 date 10 Yes - The date of birth of the student.
Format: YYYY-MM-DD
student_number STN-1234 string 50 Yes - The Student ID number issued by the educational body or any other identification number that can prove relationship between the student and the educational institute.
student_email janedoe@example.com string 100 Yes - The tudent’s email address.
student_unique_id UNIQ54321 string 255 No - This parameter can be used to set your own student identification number (ID). You can use this parameter to filter the payments in the Payment History request.
student_document 078-05-1120 string 100 Conditional When Country Pay From matches the Country ID in the reference doc. Student Identification Number
Ref. Doc.:
https://transfermateeducation.com/example/api/4.2/references/student-identification-number/
Required if the conditions are met (see the Condition column)

Response Examples

XML Response Breakdown

Field Name Field Type Parent Element Return Value Data Type Max Length / Range Description
root Element - - - - The root/parent element.
operation Element root - - - Contains the operation related information.
type Element operation Payments string 8 The Request Type.
result Element operation ok, failure string 7 The Request Status result.

ok - The request was successful and you can continue paring the XML response. Please note that, error_code, error_message and field_id elements are not returned if the result is "ok".

failure - There was an error and you should not parse the XML response any further. The error_code, error_message and field_id elements will be returned in the operation element, which can be used to determine what caused the error.
error_code Element operation Integer Number integer 0 - 10000 The error code.
error_message Element operation String - Error Message string 255 The error message.
field_id Element operation String - Field Name string 50 The field_id contains the parameter name which is causing the error.
datetime Element operation YYYY-MM-DDThh:mm:ss+TZ string 30 The date & time of the response in ISO 8601 format.
Example: 2025-02-07T11:15:14+00:00
payment Element root - - - Payment wrapper element
id Element payment Integer Number integer - The Payment / Transaction ID appointed by Transfermate for this payment.
type Element payment Payment Method Name string 50 The Payment Method name/type.
flow Element payment direct string 6 The Payment Method flow
logo Element payment URL string 100 The Payment Method logo
redirect_url Element payment - string 0 Empty for direct payment flow
ref_number Element payment PREFIX + Student Number string 1 - 100 The reference number appointed by Transfermate for this payment.
It is usually a combination of the subdomain + Student Number.
Example: TEST-XML-SERVICE12345678
source_amount Element payment decimal number float - The source/base amount for conversion.
source_currency Element payment ISO 4217 currency code string 3 The source/base currency.
The base currency depends on the provided Bank Account ID.
converted_amount Element payment decimal number float - The converted amount.
converted_currency Element payment ISO 4217 currency code string 3 The converted currency.
The converted currency depends on the Country Pay From parameter.
fx_rate Element payment decimal number float - The Exchange Rate.
For same currency payments, the value is fixed to "1".
taxes_total_amount Element payment decimal number float - Sum of all taxes.
document_upload_url Element payment URL string 300 A dedicated document upload link for the current payment.
In the Direct payment flow, the upload link will be included in the payment instructions.
In the Redirect flow, you need to display the upload URL and ask the payer to upload the required documents once he is redirected back to your end.
taxes Element payment - - - Contains all charges/taxes applied to the current Payment Method.
Please note that if there aren't applied charges/taxes, the taxes element will be empty and the @total attribute will be set to "0".
total Attribute taxes Integer Number integer 0 - 10 The total number of applied taxes/charges.
tax Element taxes - - - Tax wrapper element.
name Element taxes String - Tax Name string 50 Short tax name.
amount Element taxes decimal number float - The tax amount.
percentage Element taxes decimal number float 0 - 100 If the tax is a fixed amount rather than a percentage on the converted amount, the percentage element value will be set to 0.
description Element taxes String - Tax Description string 1000 Contains additional information about the tax.
bank_account_details Element payment - - - Bank account details wrapper element.
Please note that this element and its child elements are Deprecated in API version 4.2 and will be removed completely in future versions.
The Bank Account Details are now part of the instructions element.
instructions Element payment HTML text ranges between 500 - 10,000 characters The payment instructions and bank account information that needs to be displayed to the payer when the payment method flow is "direct".
Please note that the length of the payment instructions will vary and may exceed the Max Length value.
IMPORTANT: Please do not make any changes to the instructions which are provided through the API as a response,.

Field Name Field Type Parent Element Return Value Data Type Max Length / Range Description
root Element - - - - The root/parent element.
operation Element root - - - Contains the operation related information.
type Element operation Payments string 8 The Request Type.
result Element operation ok, failure string 7 The Request Status result.

ok - The request was successful and you can continue paring the XML response. Please note that, error_code, error_message and field_id elements are not returned if the result is "ok".

failure - There was an error and you should not parse the XML response any further. The error_code, error_message and field_id elements will be returned in the operation element, which can be used to determine what caused the error.
error_code Element operation Integer Number integer 0 - 10000 The error code.
error_message Element operation String - Error Message string 255 The error message.
field_id Element operation String - Field Name string 50 The field_id contains the parameter name which is causing the error.
datetime Element operation YYYY-MM-DDThh:mm:ss+TZ string 30 The date & time of the response in ISO 8601 format.
Example: 2025-02-07T11:15:14+00:00
payment Element root - - - Payment wrapper element
id Element payment Integer Number integer - The Payment / Transaction ID appointed by Transfermate for this payment.
type Element payment Payment Method Name string 50 The Payment Method name/type.
flow Element payment redirect string 8 The Payment Method flow
logo Element payment URL string 100 The Payment Method logo
redirect_url Element payment URL string 300 The URL to which you must redirect the payer to complete the payment.
Available only if the flow element value is "redirect".
ref_number Element payment PREFIX + Student Number string 1 - 100 The reference number appointed by Transfermate for this payment.
It is usually a combination of the subdomain + Student Number.
Example: TEST-XML-SERVICE12345678
source_amount Element payment decimal number float - The source/base amount for conversion.
source_currency Element payment ISO 4217 currency code string 3 The source/base currency.
The base currency depends on the provided Bank Account ID.
converted_amount Element payment decimal number float - The converted amount.
converted_currency Element payment ISO 4217 currency code string 3 The converted currency.
The converted currency depends on the Country Pay From parameter.
fx_rate Element payment decimal number float - The Exchange Rate.
For same currency payments, the value is fixed to "1".
taxes_total_amount Element payment decimal number float - Sum of all taxes.
document_upload_url Element payment URL string 300 A dedicated document upload link for the current payment.
In the Direct payment flow, the upload link will be included in the payment instructions.
In the Redirect flow, you need to display the upload URL and ask the payer to upload the required documents once he is redirected back to your end.
taxes Element payment - - - Contains all charges/taxes applied to the current Payment Method.
Please note that if there aren't applied charges/taxes, the taxes element will be empty and the @total attribute will be set to "0".
total Attribute taxes Integer Number integer 0 - 10 The total number of applied taxes/charges.
tax Element taxes - - - Tax wrapper element.
name Element taxes String - Tax Name string 50 Short tax name.
amount Element taxes decimal number float - The tax amount.
percentage Element taxes decimal number float 0 - 100 If the tax is a fixed amount rather than a percentage on the converted amount, the percentage element value will be set to 0.
description Element taxes String - Tax Description string 1000 Contains additional information about the tax.
bank_account_details Element payment - string 0 Empty for the redirect flow. Deprecated.
instructions Element payment - string 0 Empty for the redirect flow.