Introduction
Welcome to MCT Pay Payment API technical support center.
The MCT Pay API is designed to be flexible and give you control in how and when you convert currencies, make payments and manage your accounts.
We recommend you read through the API Documentation in full to familiarise yourself with the features and workflows associated with the product. Demo account access can also be provided to you, and the Client ID and API key can be generated within User Management> API Key in the Web Application.
For any assistance through the integration, your MCT Pay Business Development Account Manager and your allocated Technical Engineer will be able to help guide you.
Getting Started
An example workflow is set out below for guidance on how the MCT Pay API operates in practice.
In this example, we want to make a SGD1,000 payment in SGD to a beneficiary in Singapore, funded by an available account balance in SGD.
1. Authentication
To begin you will need to obtain an access token to allow you to reach all other API endpoints. Using your unique Client ID and API key (these can be found in the API menu in the MCT Pay Web Application), you can call MCT Pay service centre to assign an access token.
2. Get Transaction Details
After conducting a transaction, you may wish to query any transactions you have available in your MCT Pay account.
3. Create a Payment QR Code
When creating a payment Qrcode, you can have the source currency (SGD in this example). The response will return all requisite details on the transaction, including the amount due to MCT Pay for settlement and the cut-off date and time that those funds must be delivered to MCT Pay in cleared funds.
4. Refunds
The Refund API allows you to refund a completed Payment Ini back to the Payment Method used by your customer. The refund amount can be equal to or less than the amount specified in the original Payment Ini.
Multiple Refunds can be created against a Payment Attempt until the full amount is refunded.
Data Types
This section describes the data types and formats used consistently in the API.
| DATA TYPES | |
|---|---|
| Dates string |
Dates (without time/timezone information) in YYYY-MM-DD format. Sample use cases: conversion_date, payment_date |
| Timestamps string |
Date and time with timezone information in YYYY-MM-DDTHH:mm:ssZ format. Sample use cases: settlement_cutoff_time, created_at, last_updated_at |
| Country Codes string |
Two-letter ISO 3166-2 country code. |
| Currency Codes string |
Three-letter ISO 3166-2 country code. |
| EXAMPLE VALUES | |
|---|---|
| Date | 2022-05-25 |
| Timestamp | 2022-05-25T16:30:00+1100 |
| Country Code | SG |
| Currency Code | SGD |
Errors
MCT Pay uses conventional HTTP response codes to indicate the success or failure of an API request. Typically a status code in the 2xx range indicates success, status codes in the 4xx range indicate an error that has been triggered due to the information provided (for example; a parameter does not meet the validation requirements or was not provided), and status codes in the 5xx range indicate an error with our servers.
When we send an error response, the body will generally contain the following fields:
| RESPONSE BODY ATTRIBUTES | |
|---|---|
| code string |
Error code (please refer to reference table) |
| source string |
Name of the request parameter that caused the error |
| message string |
Description of the error |
| HTTP status codes | |
|---|---|
| 200 | OK - The request was processed successfully |
| 201 | Created - The request was processed successfully |
| 400 | Bad request - The request contains missing parameters, is in an incorrect shape, or failed another validation test |
| 401 | Unauthorized - Please verify that the authentication token is provided and is valid |
| 404 | Not found - The requested endpoint does not exist |
| 500 | Server error - Something went wrong on our end; please let us know if you are receiving this error |
| Error codes | |
| already_exists | The entity requested to be created already exists |
| amount_above_limit | The amount requested exceeds the maximum payment or conversion limit |
| amount_above_payment_method_limit | The amount requested exceeds the maximum limit for this payment method and country |
| amount_below_limit | The amount requested falls below the minimum payment or conversion limit |
| can_not_be_edited | The payment is being processed and therefore can no longer be edited |
| conversion_create_failed | The conversion was not created for an unknown reason, for example due to a third-party error |
| credentials_expired | The authorization credentials have expired; new credentials should be requested |
| credentials_invalid | The authorization credentials are not valid or have been invalidated; new credentials should be requested |
| field_required | A mandatory field in the request is missing |
| invalid_argument | A provided argument has an incorrect type or failed a validation test |
| invalid_currency_pair | The currency pair not valid; such as when the buy_currency is equal to the sell_currency |
| invalid_payment_date | The payment date cannot be chosen because it falls on a holiday/non-business day of at least one of the countries involved |
| invalid_conversion_date | The conversion date cannot be chosen because it falls on a holiday/non-business day of at least one of the countries involved |
| service_unavailable | The requested service is currently unavailable due to operating hours limitations, or because a third-party service is temporarily unavailable |
| term_agreement_is_required | Agreement to the terms of service is required and must be provided as a true boolean |
| too_many_requests | Too many requests are received too quickly |
| unsupported_country_code | Payments to (or payments from) the requested country is currently not supported |
| unsupported_currency | Conversion to (or conversion from) from the requested currency is currently not supported |
| unsupported_payment_method | The payment method chosen is not available for the selected beneficiary bank country and payment currency |
