Invoice Payment API
v1.0.0
/InvoicePayment
POST
https://subdomain.transfermateeducation.com/InvoicePayment
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:
-
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! -
Apply the HMAC-SHA256 algorithm to the string produced in Step 1.
The Computed HMAC should be:195afba8e74637015e0f777f954e428546c970cb5094d94653129ce9d5439daf - Compare the Computed HMAC against the value in the tm_hmac_signature parameter.
You will have to display the link in the following conditions:
- The document_upload_url element in the InvoicePayment response is not empty.
- The flow element in the InvoicePayment request is "redirect".
- 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 | ||||||
| invoice_number | INV#123456 | string | 100 | Yes | - | The Invoice Number Allowed characters: All Latin alphanumeric characters Special Characters: # - _ . |
| payment_amount | 1000.00 | float | - | Yes | - | The invoice amount that needs to be converted into the payers local currency. The payer local currency is derived from the country he pays from. (Bank Country Pay From) |
| country_pay_from | US | string | 2 | Yes | - | The country code (ISO 3166-1 alpha-2 code) of the bank 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) |
| payment_purpose | Tuition Fee | string | 255 | Yes | - | The payment purpose. |
| 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 InvoiceFX API call. |
| order_id | ORDER_ID_123 | string | 128 | Yes | - | The value of this parameter must 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 Invoice 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 Invoice 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 Invoice History request. |
| 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. |
| Company Related Parameters | ||||||
| company_name | Interpay Ltd. | string | 100 | Yes | - | Legal name of the company making the payment. |
| company_country | US | string | 2 | Yes | - | Country code (ISO 3166-1 alpha-2 code). The country where the company is registered. |
| company_city | Seattle | string | 50 | Yes | - | The city where the company is registered. |
| company_address | 3419 S 164th St | string | 255 | Yes | - | This is the address at which the company is registered. |
| company_postal_code | 98188 | string | 50 | Yes | - | The postal code of the city where the company is located. |
| company_phone_number | +12062441475 | string | 25 | Yes | - | The company telephone number. |
| company_email | johndoe@example.com | string | 100 | Yes | - | The e-mail address of the company. |
| company_unique_id | UNIQ12345 | string | 255 | No | - |
The unique identifier of the company. This parameter must be unique to each company. The same unique ID can't be used for more than one company. (Can be the same as the company number or email address if it is unique to the company and not used by another company). Allowed characters (case insensitive): -Z 0-9 # @ & \ - _ = : ( ) . ; , { }
|
| company_reg_number | 45.525.373/0001-14 623.456.789-1 |
string | 50 | Conditional | When Country Pay From = BR Country Pay From = CO |
The company registration number / TAX / TIN. Mandatory for:
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-07T10:18: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 + Invoice Number | string | 1 - 100 | The reference number appointed by Transfermate for this payment. It is usually a combination of the subdomain + Invoice 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-07T10:18: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 + Invoice Number | string | 1 - 100 | The reference number appointed by Transfermate for this payment. It is usually a combination of the subdomain + Invoice 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. |