NAV Navbar
Wallex api logo

Getting Started v1.37.0

Introduction

Welcome to the Wallex API ! Our API allows you to programmatically perform conversions, payments and collections, allowing you to automate your payment processes.

Our API is built by developers for developers making it straightforward to integrate with our systems.

Browse through our documentation and log in to our demo system to check out live responses right here in Developer Center and if you still have any questions, please let us know.

You can reach out to us via email at contact@wallextech.com if you need technical support on Wallex API integration.

Credentials

To start using our API you will require certain credentials that we will use to identify and authorise the use of wallex API.

How to get your Credentials

Please reach out to us at contact@wallextech.com to obtain your credentials. You are suppose to get the following credentials from us to start using the API.

Name Description
X-Api-Key Will be used to identify you on consuming the API.
accessKeyId Will need this to obtain the authorisation token which is used to access restricted resources.
secretAccessKey Will need this to obtain the authorisation token which is used to access restricted resources.

Headers

To successfully communicate with Wallex API, you must provide the following headers in your API requests when necessary:

Name Description
X-Api-Key This header must be presented will every API request that you make.
Authorization This header should be presented when accessing restricted resources.

If the X-Api-Key header wasn’t included in any API request you will be returned a 403 Forbidden as the response.

If the Authorization header wasn’t included in a API request that is trying to access a restricted resource you will be returned a 401 Unauthorized with authentication_failed message.

For the Authorization, you should generate the token by calling our Authentication API.

API Call Rate Limits

By default we allow 5 API requests per second and a Total of 432,000 API requests per day. If you need a customised rate limit for your API calls please contact us at contact@wallextech.com describing your request to us.

Wallex Endpoints

All Wallex endpoints are located on a single domain: https://api.wallex.asia. Though you can access our demo endpoints at: https://api.wallex.rocks.

Postman Collection

For your convenience we also provide postman collection to our API. please use the button below to integrate with your postman app

Run in Postman

Authentication API

Authenticate

Request body:

{
    "accessKeyId": "50afcbd2054d11e79317002618a72855",
    "secretAccessKey": "6D741B8CAA9D224896288FADB8A9DEFD18313A5AD98314D0386660646E92C803"
}

Response:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZWNoQHh3YXBwLmNvbSIsInNlc3Npb25faWQiOiI0ODMyNjMyMzBiNmJjMjg0YzNkZTExYjZiNjExOTcyMyIsImlhdCI6MTQ5OTgzMTE5N30=.Q4mYfADHT2d72tZZeKsGxy76QsMq43DbCDSxEJle-Ao="
}

HTTP Request

POST /users/v1/authenticate

Body Parameters

The payload for body should be submitted in application/json format.

Parameter Description
accessKeyId
required
string Your access key ID
secretAccessKey
required
string Your secret access key

Response

Returns a token for use with the API. The token must be added as a HTTP header to all API calls in the HTTP Authorization header when your accessing restricted resources. Please contact Wallex for access key ID and secret access key.

Following is an example of a Authorization header that will be returned to you upon successful authentication.

Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZWNoQHh3YXBwLmNvbSIsInNlc3Npb25faWQiOiI0ODMyNjMyMzBiNmJjMjg0YzNkZTExYjZiNjExOTcyMyIsImlhdCI6MTQ5OTgzMTE5N30=.Q4mYfADHT2d72tZZeKsGxy76QsMq43DbCDSxEJle-Ao=

Token Expiry

The token issued upon successful authentication will only be valid for 8 Hours from the time it was issued. You have to obtain new token once the token expires. However, you can obtain new token when the old token is not expired.

Country List

Response:

[
    {
        "ituTelephoneCode": "+93",
        "iso3166TwoLetterCode": "AF",
        "commonName": "Afghanistan"
    },
    {
        "ituTelephoneCode": "+355",
        "iso3166TwoLetterCode": "AL",
        "commonName": "Albania"
    },
    {
        "ituTelephoneCode": "+213",
        "iso3166TwoLetterCode": "DZ",
        "commonName": "Algeria"
    },
    ....
]

HTTP Request

GET /users/v1/countries

Response

This listing can be used for supporting data in signup request

Parameter Description
ituTelephoneCode string can be used as mobileCountryCode
iso3166TwoLetterCode string can be used as country
commonName string the country name

Logout

Response:

HTTP Request

POST /users/v1/logout

token will be invalidated and will not be usable even if the token is not expired.

Response

HTTP status code 200

Beneficiaries API

A Beneficiary is a company or individual that is targeted be on the receiving end of a Simple Payment. This API allows you to create, delete, and update your beneficiaries. You can also retrieve individual beneficiaries as well as a list of all your beneficiaries.

Beneficiary Requirements

Request body:

{
    "currency": "USD",
    "bankAccountCountry": "SG",
    "beneficiaryCountry": "SG"
}

Response:

{
    "data": [
        {
            "entityType": "individual",
            "address": "^.{1,255}",
            "country": "^[A-z]{2}$",
            "city": "^.{1,255}",
            "firstName": "^.{1,255}",
            "lastName": "^.{1,255}",
            "bankAccount": {
                "currency": "^[A-Z]{3}",
                "bankName": "^.{1,255}",
                "bicSwift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$",
                "country": "^[A-Z]{2}",
                "accountNumber": "^[0-9A-Z]{6,16}$"
            }
        },
        {
            "entityType": "company",
            "address": "^.{1,255}",
            "country": "^[A-z]{2}$",
            "city": "^.{1,255}",
            "companyName": "^.{1,255}",
            "bankAccount": {
                "currency": "^[A-Z]{3}",
                "bankName": "^.{1,255}",
                "bicSwift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$",
                "country": "^[A-Z]{2}",
                "accountNumber": "^[0-9A-Z]{6,16}$"
            }
        }
    ]
}

Returns the required fields and their respective validation rules to create a beneficiary, based on currency, beneficiary country and bank country.

HTTP Request

POST /beneficiaries/v1/requirements

Optional Parameters

Parameter Description
currency
required
string The currency, e.g USD.
bankAccountCountry
required
string The bank account country, e.g SG.
beneficiaryCountry
required
string The beneficiary country, e.g SG.

Create a Beneficiary

Request body:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "country": "SG",
    "bankAccount": {
        "bankName": "Bank Of Singapore",
        "address": "Road 123",
        "currency": "SGD",
        "country": "SG",
        "bankAccountHolderName": "John",
        "accountNumber": "12345678",
        "bicSwift": "UOVBSGSG"
    },
    "intermediaryBank": {
        "bankName": "Bank Name",
        "accountNumber": "87654321",
        "address": "Road 456",
        "bicSwift": "UOVBSGTS"
    },
    "nickname": "JOHN_SG",
    "email": "user@example.com",
    "entityType": "company",
    "city": "Singapore",
    "address": "Road 321",
    "companyName": "Wallex",
    "businessRegistration": "056790815678",
    "nationalIdentificationNumber": "098444416781",
    "region": "KOTA JAKARTA SELATAN",
    "relationship": "NON_RELATED"
}

Response:

{
    "data": {
        "address": "Road 321",
        "businessRegistration": "056790815678",
        "city": "Singapore",
        "companyName": "Wallex",
        "country": "SG",
        "email": "user@example.com",
        "entityType": "company",
        "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
        "nationalIdentificationNumber": "098444416781",
        "nickname": "Wallex - Bank Of Singapore - 12345678",
        "region": "KOTA JAKARTA SELATAN",
        "relationship": "NON_RELATED",
        "type": "bank",
        "bankAccount": {
            "bankName": "Bank Of Singapore",
            "address": "Road 123",
            "currency": "SGD",
            "country": "SG",
            "bankAccountHolderName": "John",
            "accountNumber": "12345678",
            "bicSwift": "UOVBSGSG",
            "iban": null,
            "aba": null,
            "bsbCode": null,
            "sortCode": null,
            "institutionNo": null,
            "bankCode": null,
            "branchName": null,
            "branchCode": null,
            "cnaps": null,
            "clabe": null,
            "routingCode": null
        },
        "intermediaryBank": {
            "bankName": "Bank Name",
            "accountNumber": "87654321",
            "address": "Road 456",
            "bicSwift": "UOVBSGTS"
        }
    }
}

Creates a new beneficiary. The parameter requirements will depend on the beneficiary type (wallex/bank), entity type, currency, beneficiary country and bank country. Please call /beneficiaries/v1/requirements prior to this to know which parameters are required.

HTTP Request

POST /beneficiaries/v1/create

Body Parameters: Beneficiary

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this beneficiary
onBehalfOfUser
optional
string The user id that you acted on for this beneficiary
nickname
optional
string The nickname/alias of the beneficiary
email
optional
string The email of the beneficiary (for email notification purpose)
country
required
string The country of the beneficiary
entityType
required
string The entity type, e.g. company or individual

Possible Body Parameters: Beneficiary

Below parameters are from requirements object root property.

Parameter Description
city
conditional
string The city of the beneficiary, for beneficiaries in Indonesia please refer to the list here for valid city names
address
conditional
string The address of the beneficiary
postcode
conditional
string The postcode of the beneficiary
stateOrProvince
conditional
string The state/province of the beneficiary
firstName
conditional
string The first name of the beneficiary, needed for individual
lastName
conditional
string The last name of the beneficiary, needed for individual
companyName
conditional
string The company name of the beneficiary, needed for company
companyNameInChineseCharacters
conditional
string The company name of the beneficiary in chinese characters, needed for company
businessRegistration
conditional
string The company business registration number, needed for company. Change to identificationNumber
nationalIdentificationNumber
conditional
string The user national identification number, needed for individual. Change to identificationNumber
identificationType
conditional
string The user identification type, the complete list can be get from Identification Type
identificationNumber
conditional
string The user identification number respective to identificationType
region
conditional
string The region of the beneficiary, for beneficiaries in Indonesia please refer to the list here for valid region names
relationship
conditional
string The user relationship to beneficiary, please refer to the list here for valid relationship value

Body Parameters: Bank Account

Parameter Description
country
required
string The country of the bank
currency
required
string The currency of the bank account
bankAccountHolderName
required
string The beneficiary bank account holder name

Possible Body Parameters: Bank Account

Below parameters are from requirements object bankAccount property.

Parameter Description
address
conditional
string The address of the beneficiary bank
accountNumber
conditional
string The bank account number
bankName
conditional
string The beneficiary bank name, for individual CNY to China please refer to the list here for valid bank name value. If you don’t put bankName on payload, the system will populate bank name based on provided BIC/SWIFT code
bankNameInChineseCharacters
conditional
string The beneficiary bank name in chinese characters
bankAccountHolderNameInChineseCharacters
conditional
string The beneficiary bank account holder name in chinese characters
bicSwift
conditional
string The BIC/SWIFT of the bank account
iban
conditional
string The IBAN of the bank account
cnaps
conditional
string The CNAPS of the bank account
clabe
conditional
string The CLABE of the bank account
aba
conditional
string The ABA of the bank account
sortCode
conditional
string The Sort code of the bank account
bsbCode
conditional
string The BSB code of the bank account
bankCode
conditional
string The bank code of the bank account
branchName
conditional
string The branch name of the bank account
branchCode
conditional
string The branch code of the bank account
institutionNo
conditional
string The institution number
ifscCode
conditional
string The routing code for local payments in India
routingCode
conditional
string The routing code of the bank account

Body Parameters: Intermediary Bank

if there’s a need to pass in intermediaryBank object please refer to the following parameters.

Parameter Description
bankName
optional
string The intermediary bank name
accountNumber
optional
string The intermediary bank account number
address
optional
string The address of the intermediary bank
bicSwift
optional
string The BIC/SWIFT Code of the intermediary bank

Error Code List

Error
beneficiary_intermediary_swiftbic_code_required
beneficiary_intermediary_bankname_required
bank_account_currency_required
bank_account_is_required
beneficiary_type_required
beneficiary_type_invalid
entity_type_is_required
country_is_required
country_invalid
currency_is_required
currency_invalid_format
bank_country_is_subject_to_sanction
beneficiary_account_black_listed
bic_swift_code_invalid_country
invalid_bic_swift
invalid_bank_name
iban_must_have_two_characters_at_the_beginning
iban_country_must_match_with_bank_country_id
invalid_email_address
invalid_beneficiary_address
invalid_beneficiary_address_format
invalid_beneficiary_address_in_chinese_characters
invalid_beneficiary_address_in_chinese_characters_format
invalid_account_number
invalid_account_number_format
invalid_bank_address
invalid_bank_address_format
invalid_bank_name
invalid_bank_name_format
invalid_bank_name_in_chinese_characters
invalid_bank_name_in_chinese_characters_format
invalid_beneficiary_city
invalid_beneficiary_city_format
invalid_beneficiary_city_in_chinese_characters
invalid_beneficiary_city_in_chinese_characters_format
invalid_routing_code
invalid_routing_code_format
invalid_branch_name
invalid_branch_name_format
invalid_ifsc
invalid_ifsc_format
invalid_bic_swift
invalid_bic_swift_format
invalid_bank_account_holder_name
invalid_bank_account_holder_name_format
invalid_bank_account_holder_name_in_chinese_characters
invalid_bank_account_holder_name_in_chinese_characters_format
invalid_iban
invalid_iban_format
invalid_beneficiary_postcode
invalid_beneficiary_postcode_format
invalid_beneficiary_company_name
invalid_beneficiary_company_name_format
invalid_beneficiary_company_name_in_chinese_characters
invalid_beneficiary_company_name_in_chinese_characters_format
invalid_beneficiary_first_name
invalid_beneficiary_first_name_format
invalid_beneficiary_last_name
invalid_beneficiary_last_name_format
invalid_national_identification_number
invalid_national_identification_number_format
invalid_intermediary_bank_account_number
invalid_intermediary_bank_account_number_format
invalid_intermediary_bank_name
invalid_intermediary_bank_name_format
invalid_intermediary_bank_address
invalid_intermediary_bank_address_format
invalid_intermediary_bank_swiftbic_code
invalid_intermediary_bank_swiftbic_code_format
invalid_mobile_number
invalid_mobile_number_format
invalid_business_registration
invalid_business_registration_format
invalid_identification_type
invalid_identification_type_format
invalid_identification_value
invalid_identification_value_format
invalid_relationship
invalid_relationship_format
beneficiary_validation_not_existence
user_is_not_approved
region_not_exist
state_not_exist
city_not_exist
city_not_match_with_related_cities_data

Retrieve a Beneficiary

Response:

{
    "data": {
        "address": "Road 321",
        "businessRegistration": "056790815678",
        "city": "Singapore",
        "companyName": "Wallex",
        "country": "SG",
        "email": "user@example.com",
        "entityType": "company",
        "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
        "nationalIdentificationNumber": "098444416781",
        "nickname": "JOHN_SG",
        "region": null,
        "relationship": "NON_RELATED",
        "type": "bank",
        "bankAccount": {
            "bankName": "Bank Of Singapore",
            "address": "Road 123",
            "currency": "SGD",
            "country": "SG",
            "bankAccountHolderName": "John",
            "accountNumber": "12345678",
            "bicSwift": "UOVBSGSG",
            "iban": null,
            "aba": null,
            "bsbCode": null,
            "sortCode": null,
            "institutionNo": null,
            "bankCode": null,
            "branchName": null,
            "branchCode": null,
            "cnaps": null,
            "clabe": null
        },
        "intermediaryBank": {
            "bankName": "Bank Name",
            "accountNumber": "87654321",
            "address": null,
            "bicSwift": "UOVBSGTS"
        }
    }
}

Returns the specified beneficiary of the current user.

HTTP Request

GET /beneficiaries/v1/item/:beneficiaryId

Path Parameters

Parameter Description
beneficiaryId
required
string The ID of the beneficiary

Query Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this beneficiary
onBehalfOfUser
optional
string The user id that you acted on for this beneficiary

Delete a Beneficiary

Response:

{
    "data": {
        "address": "Road 321",
        "businessRegistration": "056790815678",
        "city": "Singapore",
        "companyName": "Wallex",
        "country": "SG",
        "email": "user@example.com",
        "entityType": "company",
        "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
        "nationalIdentificationNumber": "098444416781",
        "nickname": "JOHN_SG",
        "region": null,
        "relationship": "NON_RELATED",
        "type": "bank",
        "bankAccount": {
            "bankName": "Bank Of Singapore",
            "address": "Road 123",
            "currency": "SGD",
            "country": "SG",
            "bankAccountHolderName": "John",
            "accountNumber": "12345678",
            "bicSwift": "UOVBSGSG",
            "iban": null,
            "aba": null,
            "bsbCode": null,
            "sortCode": null,
            "institutionNo": null,
            "bankCode": null,
            "branchName": null,
            "branchCode": null,
            "cnaps": null,
            "clabe": null
        },
        "intermediaryBank": {
            "bankName": "Bank Name",
            "accountNumber": "87654321",
            "address": null,
            "bicSwift": "UOVBSGTS"
        }
    }
}

Deletes the beneficiary and returns the specified beneficiary object for the last time.

HTTP Request

DELETE /beneficiaries/v1/item/:beneficiaryId

Path Parameters

Parameter Description
beneficiaryId
required
string The ID of the beneficiary

Query Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this beneficiary
onBehalfOfUser
optional
string The user id that you acted on for this beneficiary

Get All Beneficiaries

Request:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "pagination": {
        "page": 1
    }
}

Response:

{
    "data": [
        {
            "address": "Road 321",
            "businessRegistration": "056790815678",
            "city": "Singapore",
            "companyName": "Wallex",
            "country": "SG",
            "email": "user@example.com",
            "entityType": "company",
            "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
            "nickname": "JOHN_SG",
            "region": null,
            "relationship": "NON_RELATED",
            "type": "bank",
            "bankAccount": {
                "bankName": "Bank Of Singapore",
                "address": "Road 123",
                "currency": "SGD",
                "country": "SG",
                "bankAccountHolderName": "John",
                "accountNumber": "12345678",
                "bicSwift": "UOVBSGSG",
                "iban": null,
                "aba": null,
                "bsbCode": null,
                "sortCode": null,
                "institutionNo": null,
                "bankCode": null,
                "branchName": null,
                "branchCode": null,
                "cnaps": null,
                "clabe": null
            }
        },
        {
            "address": "Road 321",
            "businessRegistration": "056790815678",
            "city": "Singapore",
            "companyName": "Wallex",
            "country": "SG",
            "email": "user@example.com",
            "entityType": "company",
            "beneficiaryId": "41111ab2-b738-11e8-a999-0201da8d0509",
            "nickname": "JOHN_SG",
            "region": null,
            "relationship": "NON_RELATED",
            "type": "bank",
            "paymentTypes": "priority",
            "bankAccount": {
                "bankName": "Bank Of Singapore",
                "address": "Road 123",
                "currency": "SGD",
                "country": "SG",
                "bankAccountHolderName": "John",
                "accountNumber": "12345678",
                "bicSwift": "UOVBSGSG",
                "iban": null,
                "aba": null,
                "bsbCode": null,
                "sortCode": null,
                "institutionNo": null,
                "bankCode": null,
                "branchName": null,
                "branchCode": null,
                "cnaps": null,
                "clabe": null
            },
            "intermediaryBank": {
                "bankName": "Bank Name",
                "accountNumber": "87654321",
                "address": null,
                "bicSwift": "UOVBSGTS"
            }
        }
    ],
    "pagination": {
        "itemCount": 2,
        "page": 1,
        "perPage": 100,
        "search": [],
        "totalEntries": 2,
        "totalPages": 1
    }
}

Returns all the beneficiaries of the currency users, in an array of beneficiary objects.

HTTP Request

POST /beneficiaries/v1/find

Body Parameters

Parameter Description
pagination[page]
optional
number page number
onBehalfOfAccount
optional
string The account id that you acted on for this beneficiary
onBehalfOfUser
optional
string The user id that you acted on for this beneficiary

Get China Bank Name List

Response:

{
    "data": [
        {
            "name": "Agricultural Bank of China",
            "value": "中国农业银行 - ABC (Agricultural Bank of China)",
            "shortName": "ABC",
            "swiftCode": "ABOCCNBJ",
            "chineseName": "中国农业银行"
        },
        {
            "name": "Bank of China",
            "value": "中国银行 - BOC (Bank of China)",
            "shortName": "BOC",
            "swiftCode": "BKCHCNBJ",
            "chineseName": "中国银行"
        },
        {
            "name": "Industrial and Commercial Bank of China",
            "value": "中国工商银行 - ICBC (Industrial and Commercial Bank of China)",
            "shortName": "ICBC",
            "swiftCode": "ICBKCNBJ",
            "chineseName": "中国工商银行"
        },
    ]
}

Returns all the China bank lists. Used for individual beneficiary bank name validation in CNY to China

HTTP Request

GET /beneficiaries/v1/china-bank-name-list

Response

Property Description
name string The bank name in alphabet character
chineseName string The bank name in chinese character
value string The bank name in alphabet and chinese character, need to pass this value as the bank name when creating CNY individual beneficiary to China
shortName string The bank short name
swiftCode string The bank swift code

Get Swift Validation

Response:

{
    "data": {
        "city": "SINGAPORE",
        "bankName": "DBS BANK LTD.",
        "swiftCode": "DBSSSGSGXXX"
    }
}

Returns bank information to validate swift code.

HTTP Request

GET /beneficiaries/v1/swift-validation/:swiftCode

Response

Property Description
city string The city of bank
bankName string The name of bank
swiftCode string The swift code of bank

Listing States

Request body:

{
    "countryId": "ID"
}

Response:

{
    "data": [
        {
            "countryId": "ID",
            "stateId": "ID-11",
            "value": "Nanggroe Aceh Darussalam"
        },
        {
            "countryId": "ID",
            "stateId": "ID-12",
            "value": "Sumatera Utara"
        },
        {
            "countryId": "ID",
            "stateId": "ID-13",
            "value": "Sumatera Barat"
        },
        ...
    ]
}

Returns states lists by country.

HTTP Request

POST /beneficiaries/v1/states

Body Parameters

Parameter Description
countryId
required
string The ID of country

Response

Property Description
countryId string The ID of country
stateId string The ID of state
value string The name of state, need to pass this value as the stateOrProvince or region when creating beneficiary

Listing Cities

Request body:

{
    "stateId": "ID-11"
}

Response:

{
    "data": [
        {
            "stateId": "ID-11",
            "value": "Kabupaten Simeulue"
        },
        {
            "stateId": "ID-11",
            "value": "Kabupaten Aceh Singkil"
        },
        {
            "stateId": "ID-11",
            "value": "Kabupaten Aceh Selatan"
        },
        ...
    ]
}

Returns cities lists by states.

HTTP Request

POST /beneficiaries/v1/cities

Body Parameters

Parameter Description
stateId
required
string The ID of state

Response

Property Description
stateId string The ID of state
value string The name of city, need to pass this value as the city when creating beneficiary

Identification Type

This listing can be used for identification type in payload

Identification Type Meaning
COMPANY_REGISTRATION_NUMBER Company / Business Registration Number
INTERNATIONAL_PASSPORT International Passport
NATIONAL_ID National ID
TAX_ID Tax ID

Currencies API

Rates: Retrieve Single Rates

This will provide you with one single currency pair and the respective rates that are supported by Wallex. These rates are refreshed every minute.

Response:

{
    "data": {
        "currencyPair": "SGDIDR",
        "bid": 11622,
        "ask": 11659,
        "inverse": {
            "currencyPair": "IDRSGD",
            "bid": 0.00008577,
            "ask": 0.00008604
        }
    }
}

HTTP Request

GET /currencies/v1/rates/:currencyPair

Path Parameters

Parameter Description
currencyPair
required
string The currency pair to retrieve, i.e. “SGDIDR”.

Currencies: Retrieve All Supported Currencies

This will provide you with all the currencies that are supported by Wallex.

Response:

{
    "data": [
        {
            "code": "AED",
            "decimalPlaces": 2,
            "name": "United Arab Emirates Dirham"
        },
        {
            "code": "AUD",
            "decimalPlaces": 2,
            "name": "Australian Dollar"
        }
    ]
}

HTTP Request

GET /currencies/v1/supported

Currencies: Supported Currency Pairs

This will provide you with all the currency pairs that are supported by Wallex.

Response:

[
    "AUDBDT",
    "AUDCAD",
    "AUDCHF",
    "AUDCNY",
    "AUDEUR",
    "AUDGBP",
    "AUDHKD",
    "AUDIDR",
    "AUDINR",
    "AUDJPY",
    "AUDKHR",
]

HTTP Request

GET /currencies/v1/pairs

Conversions API

Get a Conversion Quote

Get a quote/rates for a given currency pair, with specific amount and buy/sell side.

Request body:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "buyCurrency": "IDR",
    "sellCurrency": "SGD",
    "fixedSide": "buy",
    "amount": 1000
}

Response:

{
    "data": {
        "currencyPair": "SGDIDR",
        "buyCurrency": "IDR",
        "sellCurrency": "SGD",
        "buyAmount": 1000,
        "sellAmount": 0.1,
        "rate": 10876,
        "fixedSide": "buy",
        "totalAmount": 0.1,
        "expiresAt": "2023-05-19T02:00:51Z",
        "quoteId": "319cbdea-611c-4054-bcc1-694cbcd2114a",
        "totalFees": 0
    }
}

HTTP Request

POST /conversions/v1/quote

Body Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this conversion
onBehalfOfUser
optional
string The user id that you acted on for this conversion
buyCurrency
required
string Your buy currency, i.e. “IDR”
sellCurrency
required
string Your sell currency, i.e. “SGD”
fixedSide
required
string Which side to fixed, “buy” or “sell”
amount
required
numberThe amount to convert, i.e. 1000

Response

Property Description
settlementCutOffTime
deprecated
string settlement cut off time
currencyPair string currency pair
buyCurrency string conversion buy currency
sellCurrency string conversion sell currency
buyAmount number buy amount
sellAmount number sell amount
rate number rate
fixedSide string fixed side
totalFees number fee amount
expiresAt string The maximum time for this quote is available to use
totalAmount number total amount
quoteId string quote id

Create a Conversion

Request body:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "quoteId": "319cbdea-611c-4054-bcc1-694cbcd2114a",
    "referenceId": "X-123",
    "uniqueReferenceId": true
}

Response:

{
    "data": {
        "conversionId": "137d4263-5ad7-4d94-9ab3-cd6c98f9b680",
        "referenceId": "X-123",
        "status": "awaiting_funds",
        "currencyPair": "SGDIDR",
        "buyCurrency": "IDR",
        "sellCurrency": "SGD",
        "fixedSide": "buy",
        "buyAmount": 1000,
        "sellAmount": 0.1,
        "totalAmount": 0.1,
        "rate": 10876,
        "createdAt": "2018-09-20T03:23:23Z",
        "totalFees": 0,
        "fundingCutoffTime": "2018-09-20T15:23:23Z"
    }
}

Creates a conversion.

HTTP Request

POST /conversions/v1/create

Body Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this conversion
onBehalfOfUser
optional
string The user id that you acted on for this conversion
quoteId
required
string The quote Id from /quote endpoint
referenceId
optional
string Identifier / description of the transaction in your system
uniqueReferenceId
optional
boolean Check unique identifier / description of the transaction in your system

Response

Property Description
id
deprecated
string conversion id. Change to conversionId
conversionId string conversion id
username
deprecated
string conversion user name
conversionDate
deprecated
string conversion date
referenceId string reference id
status string conversion status
currencyPair string The currency pair to retrieve, i.e. “IDRSGD”.
buyCurrency string conversion buy currency
sellCurrency string conversion sell currency
fixedSide string fixed side
buyAmount number buy amount
sellAmount number sell amount
totalAmount number total amount
rate number conversion rate
createdAt string date the conversion created
totalFees number fee amount
fundingCutoffTime string date the funding cut off time

Listing Conversions

Request body:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "startDate": "2019-05-07T08:59:49Z",
    "endDate": "2021-06-07T08:59:49Z",
    "referenceId": "X-123",
    "pagination": {
        "page": 1
    }
}

Response body:

{
    "data": [
        {
            "conversionId": "47bcb20f-56ad-4b38-a897-a9e300ff7840",
            "referenceId": "X-123",
            "status": "awaiting_funds",
            "currencyPair": "EURSGD",
            "buyCurrency": "EUR",
            "sellCurrency": "SGD",
            "fixedSide": "buy",
            "buyAmount": 1000,
            "sellAmount": 0.1,
            "totalAmount": 0.1,
            "rate": 10876,
            "createdAt": "2018-12-20T16:31:44Z",
            "totalFees": 0,
            "fundingCutoffTime": "2018-12-21T04:31:44Z"
        },
        {
            "conversionId": "1dcc1524-bf27-4916-8c90-c4a1b15ec879",
            "referenceId": "X-123",
            "status": "completed",
            "currencyPair": "EURSGD",
            "buyCurrency": "EUR",
            "sellCurrency": "SGD",
            "fixedSide": "buy",
            "buyAmount": 1000,
            "sellAmount": 0.1,
            "totalAmount": 0.1,
            "rate": 10876,
            "createdAt": "2018-12-20T16:31:44Z",
            "totalFees": 0,
            "fundingCutoffTime": "2018-12-21T04:31:44Z"
        }
    ],
    "pagination": {
        "itemCount": 2,
        "page": 1,
        "perPage": 100,
        "search": [],
        "totalEntries": 2,
        "totalPages": 1
    }
}

HTTP Request

POST /conversions/v1/find

Body Parameters

Parameter Description
pagination[page]
optional
number page number
onBehalfOfAccount
optional
string The account id that you acted on for this conversion
onBehalfOfUser
optional
string The user id that you acted on for this conversion
startDate
optional
string filtering records greater than or equal to startDate
example: 2019-05-07T08:59:49Z
this dates is treated as UTC time
endDate
optional
string filtering records less than endDate
example: 2019-05-07T08:59:49Z
this dates is treated as UTC time
referenceId
optional
string filtering records by referenceId
status
optional
string filtering records by status

Response

Property Description
id
deprecated
string conversion id. Change to conversionId
conversionId string conversion id
username
deprecated
string conversion user name
conversionDate
deprecated
string conversion date
referenceId string reference id
status string conversion status
currencyPair string The currency pair to retrieve, i.e. “IDRSGD”.
buyCurrency string conversion buy currency
sellCurrency string conversion sell currency
fixedSide string fixed side
buyAmount number buy amount
sellAmount number sell amount
totalAmount number total amount
rate number conversion rate
createdAt string date the conversion created
totalFees number fee amount
fundingCutoffTime string date the funding cut off time

Retrieve a Conversion

Response body:

{
    "data": {
        "conversionId": "137d4263-5ad7-4d94-9ab3-cd6c98f9b680",
        "referenceId": "X-123",
        "status": "completed",
        "currencyPair": "SGDIDR",
        "buyCurrency": "IDR",
        "sellCurrency": "SGD",
        "fixedSide": "buy",
        "buyAmount": 1000,
        "sellAmount": 0.1,
        "totalAmount": 0.1,
        "rate": 10876,
        "createdAt": "2018-09-20T03:23:23Z",
        "totalFees": 0,
        "fundingCutoffTime": "2018-09-20T15:23:23Z"
    }
}

HTTP Request

get /conversions/v1/item/:conversionId

Path Parameters

Parameter Description
conversionId
required
string The ID of the conversion

Query Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this conversion
onBehalfOfUser
optional
string The user id that you acted on for this conversion

Response

Property Description
id
deprecated
string conversion id. Change to conversionId
conversionId string conversion id
username
deprecated
string conversion user name
conversionDate
deprecated
string conversion date
referenceId string reference id
status string conversion status
currencyPair string The currency pair to retrieve, i.e. “IDRSGD”.
buyCurrency string conversion buy currency
sellCurrency string conversion sell currency
fixedSide string fixed side
buyAmount number buy amount
sellAmount number sell amount
totalAmount number total amount
rate number conversion rate
createdAt string date the conversion created
totalFees number fee amount
fundingCutoffTime string date the funding cut off time

Conversion Fund

Request:

{
    "conversionId": "137d4263-5ad7-4d94-9ab3-cd6c98f9b680",
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be"
}

Response:

{
    "data": {
        "conversionId": "137d4263-5ad7-4d94-9ab3-cd6c98f9b680",
        "referenceId": "X-123",
        "status": "completed",
        "currencyPair": "SGDIDR",
        "buyCurrency": "IDR",
        "sellCurrency": "SGD",
        "fixedSide": "buy",
        "buyAmount": 1000,
        "sellAmount": 0.1,
        "totalAmount": 0.1,
        "rate": 10876,
        "createdAt": "2018-09-20T03:23:23Z",
        "totalFees": 0,
        "fundingCutoffTime": "2018-09-20T15:23:23Z"
    }
}

Fund the conversion using balance available on your Wallex wallet

HTTP Request

POST /conversions/v1/fund

Body Parameters

Property Description
conversionId string The ID of the conversion
onBehalfOfAccount
optional
string The account id that you acted on for this conversion
onBehalfOfUser
optional
string The user id that you acted on for this conversion

Response

Property Description
id
deprecated
string conversion id. Change to conversionId
conversionId string conversion id
username
deprecated
string conversion user name
conversionDate
deprecated
string conversion date
referenceId string reference id
status string conversion status
currencyPair string The currency pair to retrieve, i.e. “IDRSGD”.
buyCurrency string conversion buy currency
sellCurrency string conversion sell currency
fixedSide string fixed side
buyAmount number buy amount
sellAmount number sell amount
totalAmount number total amount
rate number conversion rate
createdAt string date the conversion created
totalFees number fee amount
fundingCutoffTime string date the funding cut off time

Conversion Status Notification

Allows partner to subscribe Conversion Status transactions. Wallex webhook designated by the send notification shortly after the events occur on Wallex. For more information on how to use Conversion Status Notification and its features, check out on our Webhook Notification.

Payload:

{
    "resource": "conversion",
    "resourceId": "e26fda80-c845-11e8-8910-8541dfd4ff96",
    "accountId": "94ceead2-bb46-4dda-a34a-b3ee88d7c17f",
    "status": "completed"
}

Payload

Property Description
resource string The resource of conversion
resourceId string The ID of resource
accountId string The ID of account
status string The status of conversion

Status values:

Simple Payments API

Supported Local Payments Currencies

Get list of supported local currencies, the array values is a combination from currency and beneficiary receiver country. AUD-AU means Australian Dollar for Australian beneficiaries

Response:

{
    "data": [
        "AUD-AU",
        "CAD-CA",
        "CZK-CZ",
        "DKK-DK",
        "EUR-FI",
        "EUR-AT",
        "EUR-PT",
        "EUR-BE"
    ]
}

HTTP Request

GET /simple-payments/v1/supported-local-currencies

Available Payment Channels

Get list of available payment channel, the array values give you information of supported channel, limit of each payment channel on each settlement process. If your amount exceed our limit it will create split settlement transaction.

Request body:

{
  "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
  "beneficiaryId": "c66c34d7-9212-4ca9-9195-4beb4c360a2d",
  "amount": 1000000
}

Response:

{
  "data": [
    {
      "settlementChannel": "LOCAL",
      "limit": 200000,
      "splitSettlement": true
    },
    {
      "settlementChannel": "SWIFT-SHA",
      "limit": null,
      "splitSettlement": false
    },
    {
      "settlementChannel": "SWIFT-OUR",
      "limit": null,
      "splitSettlement": false
    }
  ]
}

HTTP Request

POST /simple-payments/v1/available-channels

Body Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this payment
onBehalfOfUser
optional
string The user id that you acted on for this payment
beneficiaryId
required
string The beneficiary id to process this payment
amount
required
number The amount to pay, i.e. 1000.

Response

Property Description
settlementChannel string The settlement channel
limit number The limit of settlement channel
splitSettlement boolean Indicate to split settlement if using this settlement channel

Get a Simple Payment Quote

Get a quote/rates for a simple payment with given currency pair, and amount. If beneficiary ID is provided, charges will be calculated accordingly.

Request body:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "beneficiaryId": "c66c34d7-9212-4ca9-9195-4beb4c360a2d",
    "sellCurrency": "USD",
    "buyCurrency": "SGD",
    "amount": 1000,
    "partner": {
        "fee": 2,
        "markup": 0.01
    },
    "paymentChannel": "SWIFT-OUR"
}

Response:

{
    "data": {
        "currencyPair": "USDSGD",
        "buyCurrency": "SGD",
        "sellCurrency": "USD",
        "buyAmount": 1000,
        "sellAmount": 781.92,
        "fixedSide": "buy",
        "rate": 1.2789,
        "beneficiaryId": "ccb11375-91b8-46c5-8685-ede6781028bd",
        "partnerRate": "1.2918",
        "partnerBuyAmount": "1000",
        "partnerSellAmount": "774.11",
        "partnerPaymentFee": 3,
        "expiresAt": "2020-08-24T03:46:14Z",
        "quoteId": "e0399f4c-a42d-493c-a04d-c3ca71c86395",
        "conversionFee": 7.82,
        "paymentFee": 2,
        "totalFee": 9.82,
        "totalAmount": 794.74,
        "paymentChannel": "SWIFT-OUR",
        "bankCharges": 2,
        "supportingDocumentsRequired": false
    }
}

HTTP Request

POST /simple-payments/v1/quote

Body Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this payment
onBehalfOfUser
optional
string The user id that you acted on for this payment
beneficiaryId
required
string or null the beneficiary id to do simple payment later in the simple payment request
beneficiaryId used here must match the simple payment request using this quote.
sellCurrency
required
string Your sell currency, i.e. “SGD”
buyCurrency
required
string Your buy currency, i.e. “IDR”
amount
required
number The amount to pay, i.e. 1000.
fixedSide
optional
string which side of currency your amount we should keep. we will calculate the other side (default as buy if not present)
partner
optional
Object of fee and markup which used to add custom partner fee and markup, if not set, will find into custom partner fee and markup configuration for certain partner.

This params or fee/markup configuration only applied to ultimate partner

the fee value unit is following sellCurrency example: fee 2 means 2 SGD if sellCurrency SGD

the markup value is in pecentage unit
paymentChannel
optional
string possible values are LOCAL, SWIFT-SHA, SWIFT-OUR and INTERNAL. if not set, then channel will be decided by Wallex.
When the system identifies that the beneficiary is an account registered in Wallex, it will override and automatically set the channel as INTERNAL, regardless of the specified value.
includeFee
optional
boolean Indicates if include fee for calculate totalAmount (default as true if not present)

Response

Property Description
currencyPair string The currency pair
buyCurrency string The client buy currency
sellCurrency string The client sell currency
buyAmount number The client buy amount
sellAmount number The client sell amount
fixedSide string The fixed side
rate number The client rate
beneficiaryId string The ID of the beneficiary
partnerRate number This field has value consist clientRate added with markup value from partner params or from markup configuration
partnerBuyAmount number When fixed side is buy, the value will be same with clientBuyAmount

When fixed side is sell, the value will higher than clientBuyAmount
partnerSellAmount number When fixed side is sell, the value will be same with clientSellAmount

When fixed side is buy, the value will be lower than clientSellAmount
partnerPaymentFee number This field has value that reflected to partner profit or value that wallex need to charge to partner
midMarketRate
deprecated
number The mid market rate
feeRate
deprecated
number The wallex fee rate
expiresAt string The maximum time for this quote is available to use
quoteId string The quote ID
conversionFee number The conversion fee
conversionFeeRate
deprecated
number The conversion fee rate
paymentFee number The payment fee
totalFee number Total fee
paymentFeeRate
deprecated
number The payment fee rate
totalFeeRate
deprecated
number The total fee rate
totalAmount number Total amount
paymentChannel string The payment channel
bankCharges number Bank charges amount (applied if using SWIFT-OUR), calculated in sellCurrency
conversionDate
deprecated
string The conversion date
setlementCutOffTime
deprecated
string The settlement cut off time
supportingDocumentsRequired boolean Indicates if supporting documents are required or not for the transaction

Error Code List

Error
sell_currency_cannot_be_null
buy_currency_cannot_be_null
amount_cannot_be_null
fixed_side_not_valid
payment_channel_not_valid
charge_type_is_required
charge_type_is_not_valid
beneficiary_non_existent
beneficiary_mismatch
sell_or_buy_currency_doesnt_support_decimal_places
rate_non_existent
bank_country_is_prohibited
insufficient_amount_against_fee

Request Upload URL

To request an url for uploading files to simple payment

HTTP Request

POST /simple-payments/v1/get-upload-url

Request body:

{
    "fileName": "invoice.pdf",
    "contentLength": 12000,
    "contentType": "application/pdf"
}

Response:

{
    "data": {
        "uploadUrl": "https://wallex-files-dev.s3.ap-southeast-1.amazonaws.com/wallex/1/a7a11768-303f-4e56-934c-c53e649603f8/invoice.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIA36PECD57ZT7DNHHK%2F20190402%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20190402T100353Z&X-Amz-Expires=900&X-Amz-Security-Token=FQoGZXIvYXdzEPf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDE0YbCXMucNWNffJ5yL3ASrrrUZQ%2Fd5nPtKHaaF%2FSJj%2FzcKiFo7JU9qAwKz928gZnneBSTIR1E6ekaMCVHobYurQI7B2lo6UflYfciFUmAiUd%2B1hX0hwFpOqsWASpYBgXOtb52uq8wfU%2BSkzmGPAxk%2BEOLQzqOxV%2BQ9K9S3NhBAqzgotivrS9lmhkP4AK7PAD7P5Du1aX%2BB0YwXt0DZ3TF3OJFeWk2FsMkcnKLey2h6DxgJ18fi6N60uakX6zF1hC4GjQ44wAkjgvtgEmc7OsEfACC2ZewxXa2x2%2F6TRxmBxipM4e2vkQl%2BWsCsaYQVrnNguVW%2F6M2u59ywxFJeO3vF1K%2FrkVkAohOqL5QU%3D&X-Amz-SignedHeaders=host%3Bx-amz-storage-class&X-Amz-Signature=5619defcde541c696e153c40da7f0509219d98ff9308054e9e5fd04054697710",
        "fileId": "a7a11768-303f-4e56-934c-c53e649603f8"
    }
}

Body Parameters

Parameter Description
fileName
required
string File name to be uploaded
contentType
optional
string MIME type of file name to be uploaded. Available values:

image/jpg
image/jpeg
image/png
image/svg
application/pdf
contentLength
optional
number File size in bytes (Maximum size 10 Mb)

Response

Property Description
uploadUrl string The URL of uploaded file
fileId string The ID of uploaded file

File upload

To upload the files using url generated from wallex please follow this configuration.

HTTP Request

PUT https://urlgeneratedfromwallex.com

Header Value
x-amz-storage-class
required
string STANDARD
Content-Type
required
string MIME type of the file to be uploaded. Available values:

image/jpg
image/jpeg
image/png
image/svg
application/pdf

Body

the file need to be uploaded directly as binary

Create a Simple Payment

Request body:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "fundingSource": "SALARY_WAGES",
    "paymentReference": "Payment Reference",
    "quoteId": "5595393c-9294-4a60-a1e7-97fb4981b9a3",
    "purposeOfTransfer": "GDDS",
    "files": [
        "d37673e3-341f-453f-9fa9-521e4ba21c2d",
    ],
    "referenceId": "PFEE TEST",
    "uniqueReferenceId": true
}

Response:

{
    "data": {
        "simplePaymentId": "3909da4e-26c4-4b31-924f-f9c8b4f471a4",
        "totalAmount": 1010,
        "status": "awaiting_funds",
        "buyAmount": 5049.97,
        "buyCurrency": "CNY",
        "sellAmount": 1005.15,
        "sellCurrency": "SGD",
        "currencyPair": "SGDCNY",
        "fixedSide": "buy",
        "rate": 5.0241,
        "totalFee": 4.85,
        "createdAt": "2020-09-01T07:38:27Z",
        "completedAt": null,
        "reference": "200901-SIM-3909DA4E",
        "referenceId": "PFEE TEST",
        "paymentReference": "DWMW003067",
        "paymentChannel": "SWIFT-OUR",
        "failureReason": null,
        "fundingSource": "SALARY_WAGES",
        "purposeOfTransfer": "GDDS",
        "beneficiary": {
            "address": "Road 321",
            "city": "Singapore",
            "country": "SG",
            "email": "user@example.com",
            "firstName": null,
            "beneficiaryId": "ccb11375-91b8-46c5-8685-ede6781028bd",
            "lastName": null,
            "nickname": "JOHN_SG",
            "type": "bank",
            "bankAccount": {
                "accountNumber": "987654321",
                "bankAccountHolderName": "John",
                "bicSwift": "UOVBSGSG",
                "country": "SG",
                "currency": "SGD"
            }
        },
        "fundingReference": "K4XRJK",
        "fundingCutoffTime": "2020-09-01T19:38:27Z"
    }
}

Creates a new simple payment. Please call /simple-payments/v1/quote prior to this call to get the quote ID.

HTTP Request

POST /simple-payments/v1/create

Body Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this payment
onBehalfOfUser
optional
string The user id that you acted on for this payment
fundingSource
required
string The source of funding, the complete list can be get from Funding Source
paymentReference
required
string The reference for the payment
quoteId
required
string The quote Id from /quote endpoint
purposeOfTransfer
required
string The purpose of transfer, the complete list can be get from Purpose of Transfer
purposeOfTransferDescription
optional
string Additional info of purpose code
files
conditional
array Array of file id to be included in the simple payment, files are required if supportingDocumentsRequired is true when getting Simple Payment Quote
referenceId
optional
string Identifier / description of the transaction in your system
uniqueReferenceId
optional
boolean Check unique identifier / description of the transaction in your system
senderUserId
optional
string The sender user id for this payment
fundingMethod
optional
string Available values:
- BANK_TRANSFER
- PAYNOW
fundingBankAccountNumber
optional
string Numeric value only,
Only required when fundingMethod is BANK_TRANSFER
fundingCountry
optional
string Country to fund the simple payment, required for Indonesia beneficiary
invoiceDate
conditional
string Invoice date format: DD-MM-YYYY
required for payment INR for business-related purpose
invoiceNumber
conditional
string Invoice number format: alphanumeric values only (no special characters). Max 30 characters length.
required for payment INR for business-related purpose

Response

Property Description
simplePaymentId string The ID of simple payment
totalAmount number The amount of payment
status string The status of payment
buyAmount number Amount of buy
buyCurrency string The buy currency
sellAmount number Amount of sell
sellCurrency string The sell currency
currencyPair string The currency pair of payment
fixedSide string The fixed side
rate number The client rate of payment
totalFee number Total fee
beneficiaryName
deprecated
string The beneficiary name
createdAt string The date simple payment created
completedAt string The date simple payment completed
settlementDate
deprecated
string The date simple payment settled
reference string The reference of simple payment
referenceId string reference id
paymentReference string The payment reference
paymentChannel string The payment channel
paymentDate
deprecated
string The payment date
failureReason string The failure reason
fundingSource string The source of funding
purposeOfTransfer string The purpose of transaction
beneficiary object The beneficiary info
fundingReference string 6 digit code for your reference to fund the simple payment
fundingCutoffTime string Date the funding cut off time
fundingCountry string Country to fund the simple payment

Error Code List

Error
simple_payment_user_not_approved
quoteUuid_is_missing
paymentReference_is_missing
fundingSource_is_missing
purposeCode_is_missing
simple_payment_quote_not_exists
beneficiary_non_existent
purpose_code_non_existent
purpose_code_description_required
simple_payment_reference_id_already_exist
funding_bank_account_number_should_be_a_number
funding_country_required
funding_country_invalid
bank_country_is_prohibited
beneficiary_mismatch

Retrieve a Simple Payment

Response:

{
    "data": {
        "simplePaymentId": "3909da4e-26c4-4b31-924f-f9c8b4f471a4",
        "totalAmount": 1010,
        "status": "awaiting_funds",
        "buyAmount": 5049.97,
        "buyCurrency": "CNY",
        "sellAmount": 1005.15,
        "sellCurrency": "SGD",
        "currencyPair": "SGDCNY",
        "fixedSide": "buy",
        "rate": 5.0241,
        "totalFee": 4.85,
        "createdAt": "2020-09-01T07:38:27Z",
        "completedAt": null,
        "reference": "200901-SIM-3909DA4E",
        "referenceId": "PFEE TEST",
        "paymentReference": "DWMW003067",
        "paymentChannel": "SWIFT-OUR",
        "failureReason": null,
        "fundingSource": "SALARY_WAGES",
        "purposeOfTransfer": "GDDS",
        "beneficiary": {
            "address": "Road 321",
            "city": "Singapore",
            "country": "SG",
            "email": "user@example.com",
            "firstName": null,
            "beneficiaryId": "ccb11375-91b8-46c5-8685-ede6781028bd",
            "lastName": null,
            "nickname": "JOHN_SG",
            "type": "bank",
            "bankAccount": {
                "accountNumber": "987654321",
                "bankAccountHolderName": "John",
                "bicSwift": "UOVBSGSG",
                "country": "SG",
                "currency": "SGD"
            }
        },
        "fundingReference": "K4XRJK",
        "fundingCutoffTime": "2020-09-01T19:38:27Z"
    }
}

Returns the specified simple payment of the current user.

HTTP Request

GET /simple-payments/v1/item/:simplePaymentId

Path Parameters

Parameter Description
simplePaymentId
required
string The ID of the simple payment

Query Parameters

Property Description
onBehalfOfAccount
optional
string The account id that you acted on for this payment
onBehalfOfUser
optional
string The user id that you acted on for this payment

Response

Property Description
simplePaymentId string The ID of simple payment
totalAmount number The amount of payment
status string The status of payment
buyAmount number Amount of buy
buyCurrency string The buy currency
sellAmount number Amount of sell
sellCurrency string The sell currency
currencyPair string The currency pair of payment
fixedSide string The fixed side
rate number The client rate of payment
totalFee number Total fee
beneficiaryName
deprecated
string The beneficiary name
createdAt string The date simple payment created
completedAt string The date simple payment completed
settlementDate
deprecated
string The date simple payment settled
reference string The reference of simple payment
referenceId string reference id
paymentReference string The payment reference
paymentChannel string The payment channel
paymentDate
deprecated
string The payment date
failureReason string The failure reason
fundingSource string The source of funding
purposeOfTransfer string The purpose of transaction
beneficiary object The beneficiary info
fundingReference string 6 digit code for your reference to fund the simple payment
fundingCutoffTime string date the funding cut off time

Get All Simple Payments

Request:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "startDate": "2019-05-07T08:59:49Z",
    "endDate": "2021-06-07T08:59:49Z",
    "referenceId": "X-123",
    "status": [
      "awaiting_funds"
    ],
    "pagination": {
        "page": 1
    }
}

Response:

{
    "data": [
        {
            "simplePaymentId": "a510e853-b7dd-11e8-a999-0201da8d0509",
            "totalAmount": 3202.09,
            "status": "awaiting_funds",
            "buyAmount": 2000,
            "buyCurrency": "EUR",
            "sellAmount": 3185.8,
            "sellCurrency": "SGD",
            "currencyPair": "EURSGD",
            "fixedSide": "buy",
            "rate": 1.5929,
            "totalFee": 16.29,
            "createdAt": "2018-08-31T15:30:23Z",
            "completedAt": null,
            "reference": "180831-SIM-C6D59BD1",
            "referenceId": "X-123",
            "paymentReference": "Payemnt Reference",
            "paymentChannel": "SWIFT-OUR",
            "failureReason": null,
            "fundingSource": "SALARY_WAGES",
            "purposeOfTransfer": "GDDS",
            "beneficiary": {
                "address": "Road 321",
                "city": "Singapore",
                "country": "SG",
                "email": "user@example.com",
                "firstName": null,
                "beneficiaryId": "ccb11375-91b8-46c5-8685-ede6781028bd",
                "lastName": null,
                "nickname": "JOHN_SG",
                "type": "bank",
                "bankAccount": {
                    "accountNumber": "987654321",
                    "bankAccountHolderName": "John",
                    "bicSwift": "UOVBSGSG",
                    "country": "SG",
                    "currency": "SGD"
                }
            },
            "fundingReference": "F3UBY8",
            "fundingCutoffTime": "2018-09-01T03:30:23Z"
        },
        {
            "simplePaymentId": "a510e853-b7dd-11e8-a999-0201da8d0509",
            "totalAmount": 3202.09,
            "status": "awaiting_funds",
            "buyAmount": 2000,
            "buyCurrency": "EUR",
            "sellAmount": 3185.8,
            "sellCurrency": "SGD",
            "currencyPair": "EURSGD",
            "fixedSide": "buy",
            "rate": 1.5929,
            "totalFee": 16.29,
            "createdAt": "2018-08-31T15:30:23Z",
            "completedAt": null,
            "reference": "180831-SIM-C6D59BD1",
            "referenceId": "X-123",
            "paymentReference": "Payemnt Reference",
            "paymentChannel": "SWIFT-OUR",
            "failureReason": null,
            "fundingSource": "SALARY_WAGES",
            "purposeOfTransfer": "GDDS",
            "beneficiary": {
                "address": "Road 321",
                "city": "Singapore",
                "country": "SG",
                "email": "user@example.com",
                "firstName": null,
                "beneficiaryId": "ccb11375-91b8-46c5-8685-ede6781028bd",
                "lastName": null,
                "nickname": "JOHN_SG",
                "type": "bank",
                "bankAccount": {
                    "accountNumber": "987654321",
                    "bankAccountHolderName": "John",
                    "bicSwift": "UOVBSGSG",
                    "country": "SG",
                    "currency": "SGD"
                }
            },
            "fundingReference": "F3UBY8",
            "fundingCutoffTime": "2018-09-01T03:30:23Z"
        }
    ],
    "pagination": {
        "itemCount": 2,
        "page": 1,
        "perPage": 100,
        "search": [],
        "totalEntries": 2,
        "totalPages": 1
    }
}

Returns all the simple payments of the currency users, in an array of simple payment objects.

HTTP Request

POST /simple-payments/v1/find

Body Parameters

Parameter Description
pagination[page]
optional
number page number
onBehalfOfAccount
optional
string The account id that you acted on for this payment
onBehalfOfUser
optional
string The user id that you acted on for this payment
startDate
optional
string filtering records greater than or equal to startDate
example: 2019-05-07T08:59:49Z
this dates is treated as UTC time
endDate
optional
string filtering records less than endDate
example: 2019-05-07T08:59:49Z
this dates is treated as UTC time
referenceId
optional
string filtering records by referenceId
status
optional
array filtering records by status.
available value: awaiting_funds, processing, completed, rejected, failed

Response

Property Description
data array Array of simple payments
simplePaymentId string The ID of simple payment
totalAmount number The amount of payment
status string The status of payment
buyAmount number Amount of buy
buyCurrency string The buy currency
sellAmount number Amount of sell
sellCurrency string The sell currency
currencyPair string The currency pair of payment
fixedSide string The fixed side
rate number The client rate of payment
totalFee number Total fee
beneficiaryName
deprecated
string The beneficiary name
createdAt string The date simple payment created
completedAt string The date simple payment completed
settlementDate
deprecated
string The date simple payment settled
reference string The reference of simple payment
referenceId string reference id
paymentReference string The payment reference
paymentChannel string The payment channel
paymentDate
deprecated
string The payment date
failureReason string The failure reason
fundingSource string The source of funding
purposeOfTransfer string The purpose of transaction
beneficiary object The beneficiary info
fundingReference string 6 digit code for your reference to fund the simple payment
fundingCutoffTime string date the funding cut off time

Simple Payment Fund

Request:

{
    "simplePaymentId": "48c2c36a-d193-450f-9228-a2b425c6ca20",
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be"
}

Response:

{
    "data": {
        "simplePaymentId": "a510e853-b7dd-11e8-a999-0201da8d0509",
        "totalAmount": 0.1,
        "status": "processing",
        "buyAmount": 1000,
        "buyCurrency": "IDR",
        "sellAmount": 0.1,
        "sellCurrency": "SGD",
        "currencyPair": "SGDIDR",
        "fixedSide": "buy",
        "rate": 10898,
        "totalFee": 0,
        "createdAt": "2018-09-25T00:36:17Z",
        "completedAt": null,
        "reference": "180925-SIM-03D82001",
        "referenceId": "X-123",
        "paymentReference": "Payment Reference",
        "paymentChannel": "SWIFT-OUR",
        "failureReason": null,
        "fundingSource": "SALARY_WAGES",
        "purposeOfTransfer": "GDDS",
        "beneficiary": {
            "address": "Road 321",
            "city": "Singapore",
            "country": "SG",
            "email": "user@example.com",
            "firstName": null,
            "beneficiaryId": "ccb11375-91b8-46c5-8685-ede6781028bd",
            "lastName": null,
            "nickname": "JOHN_SG",
            "type": "bank",
            "bankAccount": {
                "accountNumber": "987654321",
                "bankAccountHolderName": "John",
                "bicSwift": "UOVBSGSG",
                "country": "SG",
                "currency": "SGD"
            }
        },
        "fundingReference": "F3UBY8",
        "fundingCutoffTime": "2018-09-25T12:36:17Z"
    }
}

Fund the simple payment using balance available on your Wallex wallet

HTTP Request

POST /simple-payments/v1/fund

Body Parameters

Property Description
simplePaymentId string id of simple payments to be funded

Query Parameters

Property Description
onBehalfOfAccount
optional
string The account id that you acted on for this payment
onBehalfOfUser
optional
string The user id that you acted on for this payment

Response

Property Description
simplePaymentId string The ID of simple payment
totalAmount number The amount of payment
status string The status of payment
buyAmount number Amount of buy
buyCurrency string The buy currency
sellAmount number Amount of sell
sellCurrency string The sell currency
currencyPair string The currency pair of payment
fixedSide string The fixed side
rate number The client rate of payment
totalFee number Total fee
beneficiaryName
deprecated
string The beneficiary name
createdAt string The date simple payment created
completedAt string The date simple payment completed
settlementDate
deprecated
string The date simple payment settled
reference string The reference of simple payment
referenceId string reference id
paymentReference string The payment reference
paymentChannel string The payment channel
paymentDate
deprecated
string The payment date
failureReason string The failure reason
fundingSource string The source of funding
purposeOfTransfer string The purpose of transaction
beneficiary object The beneficiary info
fundingReference string 6 digit code for your reference to fund the simple payment
fundingCutoffTime string date the funding cut off time

Error Code List

Error
simple_payment_user_not_approved
simple_payments_not_found
status_invalid
beneficiary_non_existent
bank_account_non_existent
beneficiary_provider_non_existent
currency_information_is_missing
balance_non_existent
insufficient_funds
max_negative_amount_exceeded

Retrieve Proof of Payment Document

Response:

{
  "data": [
    {
      "documentType": "invoice",
      "url": "https://urlgeneratedfromwallex.com"
    },
    {
      "documentType": "mt103",
      "url": "https://urlgeneratedfromwallex.com"
    },
    {
      "documentType": "payment-confirmation",
      "url": "https://urlgeneratedfromwallex.com"
    }
  ]
}

Call this API to retrieve the proof of a completed payment in the form of an invoice, mt103 and payment-confirmation document .

HTTP Request

GET /simple-payments/v1/item/:simplePaymentId/get-proof-of-payment

Path Parameters

Parameter Description
simplePaymentId
required
string The id of the simple payment

Query Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this payment
onBehalfOfUser
optional
string The user id that you acted on for this payment
documentType
optional
string The type of the document. Possible values: invoice, mt103, payment-confirmation

Response

Property Description
documentType string The type of the document
url string The URL to download the document file. The URL is valid only for 5 minutes.

Error Code List

Error
simple_payments_non_existent
simple_payments_get_paymentProof_failed
retrieve_documents_failed

Funding Source

This listing can be used for funding source in payload

Funding Source Meaning
SALARY_WAGES Salary Wages
INVESTMENTS Invesments
PERSONAL_SAVINGS Personal Savings
PERSONAL_WEALTH Personal Wealth
RETIREMENT_FUNDS Retirement Funds
FAMILY_FRIEND_CO_WORKER Family , Friend and Co-worker
BUSINESS_OWNER_OR_SHAREHOLDER Business Owner or Shareholder
LOAN_FACILITY Loan Facility
COMPANY_BANK_ACCOUNT Company Bank Account
THIRD_PARTY Third Party
PERSONAL_ACCOUNT Personal Account
OTHER Other

Purpose of Transfer

Request body:

{
    "buyCurrency": "CNY",
    "beneficiaryBankCountry": "CN",
    "beneficiaryEntityType": "individual",
    "paymentChannel": "LOCAL"
}

Response:

{
    "data": [
        {
            "code": "GDDS",
            "description": "Purchase Sale Of Goods"
        },
        {
            "code": "SCVE",
            "description": "Purchase Sale Of Services"
        },
        {
            "code": "SUPP",
            "description": "Supplier Payment"
        },
        {
            "code": "WX01",
            "description": "Family Support/Living Expenses"
        },
        {
            "code": "WX04",
            "description": "Friends"
        },
        {
            "code": "PAYR",
            "description": "Payroll"
        }
    ]
}

This listing can be used for purpose of transfer in payload.

HTTP Request

POST /simple-payments/v1/purpose-of-transfer

Path Parameters

Parameter Description
buyCurrency
required
string The payment buy currency
beneficiaryBankCountry
required
string The beneficiary bank country
beneficiaryEntityType
required
string The beneficiary entity type, e.g. company or individual
originSenderEntityType
optional
string The origin sender entity type, e.g. company or individual
paymentChannel
required
string The payment channel, possible values are LOCAL, SWIFT-SHA, SWIFT-OUR and INTERNAL

Specific Cases

There are some scenarios where the purpose code list is limited. Other than below cases, typically you will see the full list of available purpose codes.

Buy Currency Conditions Notes
CNY - buyCurrency: CNY
- beneficiaryBankCountry: CN
- beneficiaryEntityType: individual
- paymentChannel: local
MYR - buyCurrency: MYR
- beneficiaryBankCountry: MY
- originSenderEntityType: individual/company
- beneficiaryEntityType: individual/company
- paymentChannel: local
The available Purpose code list depends on the beneficiary type and sender type
KRW - buyCurrency: KRW
- beneficiaryBankCountry: KR
- paymentChannel: local/swift
INR - buyCurrency: INR
- beneficiaryBankCountry: IN
- beneficiaryEntityType: individual/company
- paymentChannel: local
The available Purpose code list depends on the beneficiary type

Response

Property Description
code string The purpose of transfer code
description string The purpose of transfer description

Simple Payment Status Notification

Allows partner to subscribe Simple Payment Status transactions. Wallex webhook designated by the send notification shortly after the events occur on Wallex. For more information on how to use Simple Payment Status Notification and its features, check out on our Webhook Notification.

Payload:

{
    "resource": "simple_payment",
    "resourceId": "e26fda80-c845-11e8-8910-8541dfd4ff96",
    "accountId": "94ceead2-bb46-4dda-a34a-b3ee88d7c17f",
    "status": "processing",
    "reason": null
}

Payload

Property Description
resource string The resource of payments
resourceId string The ID of resource
accountId string The ID of account
status string The status of payment
reason string The reason of rejected and failed status

Status values:

Balances API

Get All Balances

Request:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "pagination": {
        "page": 1
    }
}

Response:

{
    "data": [
        {
            "id": "2fcb0f63-1d31-11e9-9f08-06655537f802",
            "amount": 0,
            "currency": "SGD",
            "currencyName": "Singapore Dollar"
        },
        {
            "id": "2fcbe920-1d31-11e9-9f08-06655537f802",
            "amount": 100,
            "currency": "USD",
            "currencyName": "US Dollar"
        },
        {
            "id": "2fccb0da-1d31-11e9-9f08-06655537f802",
            "amount": 110,
            "currency": "JPY",
            "currencyName": "Japanese Yen"
        },
        {
            "id": "2fcd7c29-1d31-11e9-9f08-06655537f802",
            "amount": 0,
            "currency": "IDR",
            "currencyName": "Indonesian Rupiah"
        }
    ],
    "pagination": {
        "itemCount": 4,
        "page": 1,
        "perPage": 100,
        "search": [],
        "totalEntries": 4,
        "totalPages": 1
    }
}

Get all balances

POST /balances/v1/find

Query Parameters

Parameter Description
pagination[page]
optional
number page number
onBehalfOfAccount
optional
string The account id that you acted on for this balance
onBehalfOfUser
optional
string The user id that you acted on for this balance

Response Body

Parameter Description
id string balance id
amount number current balance
currency string currency code
currencyName string currency name

Get Balances by Currency

Response:

{
    "data": {
        "id": "04b07631-708b-11e9-99ce-065f88b5bfa2",
        "amount": 622487034,
        "currency": "IDR",
        "currencyName": "Indonesian Rupia"
    }
}

Get your current balances by currency

HTTP Request

GET /balances/v1/item/:currency

URL Parameters

Parameter Description
currency
required
string currency code, i.e. “IDR”

Query Parameters

Parameter Description
onBehalfOfAccount
optional
string The account id that you acted on for this balance
onBehalfOfUser
optional
string The user id that you acted on for this balance

Response Body

Parameter Description
id string balance id
amount number current balance
currency string currency code
currencyName string currency name

Get Balances History

Request:

{
    "onBehalfOfAccount": "70f1722d-b997-44c2-a2e8-691c1090d1be",
    "startDate": "2014-07-21T17:00:00Z",
    "endDate": "2019-07-23T02:39:00Z",
    "pagination": {
        "page": 1
    }
}

Response:

{
    "data": [
        {
            "id": "8fa76a1db55011e78ce406141bd54fa5",
            "balanceId": "513080fe-89e3-11e6-9e92-026b39b3bdb9",
            "amountBefore": 12409921.23,
            "amountAfter": 12409757.81,
            "currency": "SGD",
            "totalAmount": 0,
            "transactionId": "70f1722d-b997-44c2-a2e8-691c1090d1be",
            "transactionType": "conversion",
            "date": "2017-10-20T04:38:47Z"
        }
    ],
    "pagination": {
        "itemCount": 1,
        "page": 1,
        "perPage": 100,
        "search": [],
        "totalEntries": 1,
        "totalPages": 1
    }
}

POST /balances/v1/history

Body Parameters

Parameter Description
pagination[page]
optional
number page number
onBehalfOfAccount
optional
string The account id that you acted on for this balance
onBehalfOfUser
optional
string The user id that you acted on for this balance
startDate
optional
string filtering records greater than or equal to startDate
example: 2019-05-07T08:59:49Z
this dates is treated as UTC time
endDate
optional
string filtering records less than endDate
example: 2019-05-07T08:59:49Z
this dates is treated as UTC time

Response Body

Parameter Description
id string history id
amountBefore number amount before
amountAfter number amount after
currency string currency
transactionId number transaction id that affected the balance
transactionType string transaction type that affected the balance
date string transaction date that affected the balance
balanceId string balance id
totalAmount number total amount

Virtual Accounts API

Create a VA Request

Request body:

{
    "name": "My VA Name",
    "provider": "BNI",
    "currency": "IDR",
    "description": "Some description...",
    "type": "fixed",
    "amount": 10000,
    "expiryDuration": 24,
    "approveAsync": true
}

Response:

{
    "data": {
        "updatedAt": "2018-10-05T02:25:11.208Z",
        "createdByName": "API User",
        "status": "pending",
        "description": "Some description...",
        "updatedByName": "API User",
        "type": "fixed",
        "requestId": "e26fda80-c845-11e8-8910-8541dfd4ff96",
        "provider": "BNI",
        "userId": 1,
        "expiryDuration": 24,
        "currency": "IDR",
        "createdBy": 1,
        "amount": 10000,
        "updatedBy": 1,
        "userFullname": "API User",
        "createdAt": "2018-10-05T02:25:11.208Z",
        "name": "My VA name",
        "virtualAccountNo": "Creating...",
        "approveAsync": true
    }
}

Creates a VA request.

HTTP Request

POST /virtual-accounts/v1/requests/create

Body Parameters

Parameter Description
name
required
string Alias for the VA ( only number, alphabet and space character accepted )
provider
required
string The provider/bank of the VA, i.e. “BNI”
currency
required
string The currency for the VA
description
required
string The description for the VA
type
required
string The type of the VA, i.e “open”
approveAsync
optional
boolean Asynchronously requesting the Virtual Account Number. Need to Retrieve a VA Request to get the Virtual Account Number. Default to false

Required Parameters when Type is fixed

Parameter Description
amount
required
number The amount for the fixed VA
expiryDuration
required
number The expiry duration for the fixed VA, from 1 - 48

Provider values:

Type values:

Amount values:

Response

Property Description
updatedAt string Shows the timestamp where this data last updated
createdByName string Name of user who created the VA
status string Status of the VA, i.e “pending”
description string Description of the VA
updatedByName string Name of user who updated the VA
type string Type of the VA, i.e “fixed”
requestId string The VA request ID to retrieve, i.e. “0d6cece0-3ec2-11e8-8fc4-9dce3cfaab40”
provider string The provider/bank of the VA, i.e. “BNI”
userId number ID of user who create VA
expiryDuration number The expiry duration of the fixed VA, from 1 - 48
currency string The currency of the VA
createdBy number ID of user who created the VA
amount number The amount of the fixed VA
updatedBy number ID of user who updated the VA
userFullname string Full name of user who created the VA
createdAt string Shows the timestamp where this data created
name string Alias of the VA

Webhook Notifications

Overview

We support notifications via webhook on various actions on your Virtual Account for seamless integration, i.e. when a deposit is received. To activate your webhook notification, please provide the endpoint to us.

Payload:

{
    "action": "request",
    "status": "approved",
    "requestId": "e26fda80-c845-11e8-8910-8541dfd4ff96",
    "virtualAccountRequestId": "e26fda80-c845-11e8-8910-8541dfd4ff96"
}

VA Request Approval, Cancel, Reject

Parameter Description
action string Your action type
status string The status of the action
requestId string The request ID of the action
virtualAccountRequestId string The request ID of the action (deprecated)

Status values:

Payload:

{
    "action": "deposit",
    "status": "completed",
    "transactionId": "1e072ed0-161d-11e8-99ff-0d9315f57f5f",
    "masterAccountId": "ba5b3e81-f1eb-11e7-ba97-9f3389ceb7a3",
    "virtualAccountId": "e26fda80-c845-11e8-8910-8541dfd4ff96",
    "virtualAccountNumber": "8251180223144501",
    "virtualAccountNo": "8251180223144501",
    "sourceAmount": 10000000
}

Incoming Deposit

Parameter Description
action string Your action type
status string The status of the action
transactionId string The deposit transaction ID
masterAccountId string The master account ID
virtualAccountId string The virtual account ID
virtualAccountNumber string The virtual account number
virtualAccountNo string The virtual account number (deprecated)
sourceAmount number The deposited amount

Webhook Setup

You can find out real-time information about deposits that enter your account. By entering the endpoint on the Webhook feature that we have provided. We will use these endpoints to send real-time information about the deposits that enter your account.

Here’s how to install the webhook :

  1. Enter into your Virtual Account.
  2. In the menu panel on the left side of the page, select the menu My Accounts.
  3. Select an account that will be installed by pressing the View button. After that you will enter into account details. My Accounts
  4. On the account details page. Make sure you are on the Details tab. Inside the tab you will see a section titled Webhook.
  5. Click the Add button to add a new Webhook. Account Detail
  6. On the Add Webhook page you can add Endpoints and Headers.

    • Endpoint (Required)
      The URL address used to receive information/notifications. This endpoint will be called by Wallex for notification information.
    • Header (Optional)
      Used if the endpoint requires Headers.

  7. After completing the fields that have been provided. Click the Add button to add the new Webhook. Add Webhook
  8. After that you can return to the account details page to see the Webhook that you have created. Webhook Created

Retrieve a VA Request

Response:

{
    "data": {
        "updatedAt": "2018-10-05T02:48:57.788Z",
        "createdByName": "API User",
        "description": "Some description...",
        "status": "approved",
        "updatedByName": "Admin User",
        "virtualAccountNo": "8251181005094801",
        "type": "fixed",
        "requestId": "e26fda80-c845-11e8-8910-8541dfd4ff96",
        "provider": "BNI",
        "userId": 1,
        "approvedBy": 2,
        "virtualAccountId": "e26fda80-c845-11e8-8910-8541dfd4ff96",
        "approvedAt": "2018-10-05T02:48:54.030Z",
        "expiryDuration": 24,
        "currency": "IDR",
        "createdBy": 1,
        "amount": 10000,
        "updatedBy": 2,
        "userFullname": "API User",
        "approvedByName": "Admin User",
        "createdAt": "2018-10-05T02:25:11.208Z",
        "name": "My VA Name"
    }
}

Returns the specified request of a virtual account.

HTTP Request

GET /virtual-accounts/v1/requests/item/:requestId

Path Parameters

Parameter Description
requestId
required
string The VA request ID to retrieve, i.e. “0d6cece0-3ec2-11e8-8fc4-9dce3cfaab40”

Response

Property Description
updatedAt string Shows the timestamp where this data last updated
createdByName string Name of user who created the VA
description string Description of the VA
status string Status of the VA, i.e “approved”
updatedByName string Name of admin who updated the VA
virtualAccountNo string The virtual account number
type string Type of the VA, i.e “fixed”
requestId string The VA request ID to retrieve, i.e. “0d6cece0-3ec2-11e8-8fc4-9dce3cfaab40”
provider string The provider/bank of the VA, i.e. “BNI”
userId number ID of user who created the VA
approvedBy number ID of admin who approved the VA
virtualAccountId string ID of Virtual Account Number
approvedAt string Show the timestamp when the VA Approved
expiryDuration number The expiry duration of the fixed VA, from 1 - 48
currency string Currency of the VA
createdBy number ID of user who created the VA
amount number The amount of the fixed VA
updatedBy number ID of user who updated the VA
userFullname string Full name of user who created the VA
approvedByName string Name of admin who approved the VA
createdAt string Shows the timestamp when this data created
name string Alias of the VA

Get Withdrawal Quote

Request:

{
    "amount": 1000000,
    "sellCurrency": "IDR",
    "buyCurrency": "USD"
}

Response:

{
    "data": {
        "updatedAt": "2019-03-12T02:00:08.117Z",
        "createdByName": "John Doe",
        "buyCurrency": "USD",
        "fee": {},
        "quotedAt": "2019-03-12T02:00:08.113",
        "quoteId": "8fca9030-446a-11e9-ad64-bf62cddf0b51",
        "updatedByName": "John Doe",
        "accountId": 913,
        "expiredAt": "2019-03-12T02:05:08.113",
        "sellCurrency": "IDR",
        "buyAmount": 69.44,
        "rate": 14400,
        "sellAmount": 1000000,
        "createdBy": 913,
        "rateId": "9681bd49-175b-444f-8de4-5518733a4cba",
        "updatedBy": 913,
        "createdAt": "2019-03-12T02:00:08.117Z"
    }
}

Request withdrawal quote, where the quoteId will be used when creating withdrawal request.

HTTP Request

POST /virtual-accounts/v1/withdrawals/get-quote

Body Parameters

Parameter Description
amount
required
number Withdrawal amount
sellCurrency
required
string Withdrawal sell currency
buyCurrency
required
string Withdrawal buy currency

Response

Property Description
updatedAt string Shows the timestamp where this data last updated
createdByName string Name of the user who created the withdrawal
buyCurrency string Withdrawal buy currency
fee object Withdrawal fee details
quotedAt string Timestamp where the withdrawal quote is created
quoteId string Quote Id to be used during create withdrawal
updatedByName string Name of the user who updated the withdrawal
accountId number ID of the account who created the withdrawal
expiredAt string Timestamp where the quote is expired
sellCurrency string Withdrawal sell currency
buyAmount number Withdrawal buy amount
rate number Rate of the withdrawal
sellAmount number Withdrawal sell amount
createdBy number ID of user who created the withdrawal
rateId string Rate id of the withdrawal
updatedBy number ID of user who updated the withdrawal
createdAt string Shows the timestamp where this data created

Get Upload URL

Request:

{
    "fileName": "secretfile.pdf",
    "contentLength": 1200,
    "contentType": "application/pdf"
}

Response:

{
    "data": {
        "uploadUrl": "https://somerandomurl.com",
        "fileId": "20e28a81-fc9e-4835-90db-96c3a61829b4"
    }
}

Perform request to get upload url to upload files for withdrawal.

HTTP Request

POST /virtual-accounts/v1/withdrawals/get-upload-url

Body Parameters

Parameter Description
fileName
required
string file name to be uploaded ie. “invoice.jpg”
contentType
required
string Mime type of file name to be uploaded
contentLength
required
number File size in bytes

Response

Property Description
uploadUrl string URL of uploaded file
fileId string ID of uploaded file

Uploading a file

To upload the files using url generated from wallex please follow this configuration

HTTP Request

PUT https://urlgeneratedfromwallex.com

Header Value
x-amz-storage-class
required
string STANDARD
Content-Type
required
string application/pdf , image/png, image/jpeg (or can use other content type matched with files that uploaded)

Body

the file need to be uploaded directly as binary

Create Withdrawal

Request:

{
    "quoteId": "8fca9030-446a-11e9-ad64-bf62cddf0b51",
    "masterAccountId": "7a12e190-fd32-11e8-b848-5754f8c6c555",
    "bankAccountId": "8ef70490-2070-11e9-b26b-a9a34c5ea555",
    "fileIds": [
        "1d0cb5db-f13c-495a-88e6-4ba721d91167"
    ]
}

Response:

{
    "data": {
        "updatedAt": "2019-03-12T02:00:42.653Z",
        "createdByName": "John Doe",
        "buyCurrency": "USD",
        "masterAccountId": "7a12e190-fd32-11e8-b848-5754f8c6c555",
        "status": "pending",
        "updatedByName": "John Doe",
        "withdrawalId": "a4607dc0-446a-11e9-abfa-a155474d7bf0",
        "userId": 913,
        "masterAccountlabel": "MASTER ACCOUNT (IDR)",
        "sellCurrency": "IDR",
        "buyAmount": 69.44,
        "rate": 14400,
        "sellAmount": 1000000,
        "fileIds": [
        "1d0cb5db-f13c-495a-88e6-4ba721d91167"
        ],
        "createdBy": 913,
        "updatedBy": 913,
        "userFullName": "John Doe",
        "createdAt": "2019-03-12T02:00:42.653Z"
    }
}

Perform withdrawal request from master account.

HTTP Request

POST /virtual-accounts/v1/withdrawals/create

Body Parameters

Parameter Description
quoteId
required
string Withdrawal quoteId which holds the details about withdrawal instruction such as sell currency, buy currency, buy amount, sell amount, and rate
masterAccountId
required
string Master account id for withdrawal to be performed
bankAccountId
required
string Beneficiary’s bank account id for withdrawal to be performed
fileIds
required
can be null/empty
array Array of file ids to be included in the withdrawal

Response

Property Description
updatedAt string Shows the timestamp where this data last updated
createdByName string Name of the user who belong to this withdrawal
buyCurrency string Withdrawal buy currency
masterAccountId string Master account id of withdrawal
status string Status of withdrawal, i.e “Completed”
updatedByName string Name of the user who updated the withdrawal
userId number ID of user who created the withdrawal
withdrawalId string ID of withdrawal
masterAccountlabel string Master account of withdrawal
sellCurrency string Withdrawal sell currency
buyAmount number Buy amount of withdrawal
rate number Rate of withdrawal
sellAmount number Sell amount of withdrawal
fileIds array Array of file ids that included in the withdrawal
createdBy number ID of user who created the withdrawal
updatedBy number ID of user who updated the withdrawal
userFullName string Full name of user who belong to this withdrawal
createdAt string Shows the timestamp where this data created

Retrieve a VA Transaction

Response:

{
    "data": {
        "updatedAt": "2018-02-20T09:04:54.872Z",
        "fee": {
            "type": "percentage",
            "value": 10,
            "amount": 200000,
            "minFee": 10000
        },
        "referenceId": "1d1e5570-161d-11e8-9cfa-77598ef92a6e",
        "masterAccountId": "ba5b3e81-f1eb-11e7-ba97-9f3389ceb7a3",
        "status": "Completed",
        "description": "Source amount: 2000000, Fee: 200000, Deposited amount: 1800000",
        "updatedByName": "API User",
        "sourceAmount": 2000000,
        "virtualAccountNumber": "8251180105144001",
        "transactionId": "1e072ed0-161d-11e8-99ff-0d9315f57f5f",
        "action": "Deposit",
        "transactionDate": "2018-02-20T09:04:43.000Z",
        "userId": 1,
        "virtualAccountId": "c18d9720-f1eb-11e7-b2da-3d66eb4f8022",
        "currency": "IDR",
        "createdBy": 1,
        "amount": 1800000,
        "updatedBy": 1,
        "userFullName": "API User",
        "createdAt": "2018-02-20T09:04:54.872Z",
        "customerName": "Default Active Request"
    }
}

Returns the specified transaction details of a virtual account.

HTTP Request

GET /virtual-accounts/v1/transactions/item/:transactionId

Path Parameters

Parameter Description
transactionId
required
string The transaction ID to retrieve, i.e. “1e072ed0-161d-11e8-99ff-0d9315f57f5f”

Response

Property Description
data array Array of VA transactions object
updatedAt string Shows the timestamp where this data last updated
fee object Shows the current transaction fee
fee.type string Shows the current transaction fee type (percentage or decimal)
fee.value number Shows the current transaction fee amount based on the fee type
fee.amount number Shows the current transaction calculated fee and used in transaction
fee.minFee number Shows the current transaction minimum fee applied
referenceId string Reference ID related to action property. if action is Deposit then this referenceId is referenced to depositId.
masterAccountId string Master account ID used in the current transaction
status string Status of current transaction
description string Descriptive text about current transaction
updatedByName string Name of the user responsible for latest action happened to this transaction
sourceAmount number Actual amount from user
virtualAccountNumber string VA number used in transaction
transactionId string Unique ID generated to the current transaction for future reference
action string Action type performed in the current transaction (Deposit / Withdrawal)
transactionDate string Shows current date and time when the transaction happened
userId number ID of user who owned the transaction
virtualAccountId string VA reference ID used in transaction
currency string Currency used in current transaction
createdBy number ID of user who created the transaction
amount number nett amount of the current transaction (after fees applied)
updatedBy number ID of user who updated the transaction
userFullName string Full name of user who belong to this transaction
createdAt string Shows the timestamp where this data created
customerName string Shows the customer name for this transaction

Get All VA Transactions

This will provide you with all the transactions for a specific virtual account.

Request body:

{
    "virtualAccountId": "c18d9720-f1eb-11e7-b2da-3d66eb4f8022"
}

Response:

{
    "data": [
        {
            "updatedAt": "2018-02-20T09:04:54.872Z",
            "fee": {
                "type": "percentage",
                "value": 10,
                "amount": 200000,
                "minFee": 10000
            },
            "referenceId": "1d1e5570-161d-11e8-9cfa-77598ef92a6e",
            "masterAccountId": "ba5b3e81-f1eb-11e7-ba97-9f3389ceb7a3",
            "status": "Completed",
            "description": "Source amount: 2000000, Fee: 200000, Deposited amount: 1800000",
            "updatedByName": "API User",
            "sourceAmount": 2000000,
            "virtualAccountNumber": "8251180105144001",
            "transactionId": "1e072ed0-161d-11e8-99ff-0d9315f57f5f",
            "action": "Deposit",
            "transactionDate": "2018-02-20T09:04:43.000Z",
            "userId": 1,
            "virtualAccountId": "c18d9720-f1eb-11e7-b2da-3d66eb4f8022",
            "currency": "IDR",
            "createdBy": 1,
            "amount": 1800000,
            "updatedBy": 1,
            "userFullName": "API User",
            "createdAt": "2018-02-20T09:04:54.872Z",
            "customerName": "Default Active Request"
        },
        {
            "updatedAt": "2018-02-07T23:11:38.017Z",
            "fee": {
                "type": "percentage",
                "value": 10,
                "amount": 10000,
                "minFee": 5000
            },
            "referenceId": "3e9a6330-0c5c-11e8-a27c-8f4cea37d7ad",
            "masterAccountId": "ba5b3e81-f1eb-11e7-ba97-9f3389ceb7a3",
            "status": "Completed",
            "description": "Source amount: 100000, Fee: 10000, Deposited amount: 90000",
            "updatedByName": "API User",
            "sourceAmount": 100000,
            "virtualAccountNumber": "8251180105144001",
            "transactionId": "3fb06710-0c5c-11e8-8664-c1511e9d8895",
            "action": "Deposit",
            "transactionDate": "2018-02-07T23:11:25.000Z",
            "userId": 1,
            "virtualAccountId": "c18d9720-f1eb-11e7-b2da-3d66eb4f8022",
            "currency": "IDR",
            "createdBy": 1,
            "amount": 90000,
            "updatedBy": 1,
            "userFullName": "API User",
            "createdAt": "2018-02-07T23:11:38.017Z",
            "customerName": "Default Active Request"
        }
    ]
}

HTTP Request

POST /virtual-accounts/v1/transactions/find

Body Parameters

Parameter Description
virtualAccountId
required
string The virtual account ID, i.e. “c18d9720-f1eb-11e7-b2da-3d66eb4f8022”

Response

Property Description
data array Array of VA transactions object
updatedAt string Shows the timestamp where this data last updated
fee object Shows the current transaction fee
fee.type string Shows the current transaction fee type (percentage or decimal)
fee.value number Shows the current transaction fee amount based on the fee type
fee.amount number Shows the current transaction calculated fee and used in transaction
fee.minFee number Shows the current transaction minimum fee applied
referenceId string Reference ID related to action property. if action is Deposit then this referenceId is referenced to depositId.
masterAccountId string Master account ID used in the current transaction
status string Status of current transaction
description string Descriptive text about current transaction
updatedByName string Name of the user responsible for latest action happened to this transaction
sourceAmount number Actual amount from user
virtualAccountNumber string VA number used in transaction
transactionId string Unique ID generated to the current transaction for future reference
action string Action type performed in the current transaction (Deposit / Withdrawal)
transactionDate string Shows current date and time when the transaction happened
userId number ID of user who owned the transaction
virtualAccountId string VA reference ID used in transaction
currency string Currency used in current transaction
createdBy number ID of user who created the transaction
amount number nett amount of the current transaction (after fees applied)
updatedBy number ID of user who updated the transaction
userFullName string Full name of user who belong to this transaction
createdAt string Shows the timestamp where this data created
customerName string Shows the customer name for this transaction

Simulating a Deposit

You can try out deposit using urls below:

Errors

Error Code Reference

Following is the error code reference for Wallex API

Error Code Meaning
400 Bad Request – Please check your request
401 Unauthorized – Your Authorisation header is not present or it has already expired
403 Forbidden – You may have missed out the X-Api-Key in your request header
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Error Message

Following is the error message reference for Wallex API

Response:

{
    "error_code":"token_expired",
    "message":"Token Expired",
    "errors": [
        {
            "error_code":"token_expired",
            "message":"Token Expired"
        }
    ]
}

Payload

Property Description
error_code string The code of error
message string The message of error
errors string The array from errors

Changelog

vNext

v1.37.13

v1.37.12

v1.37.11

v1.37.10

v1.37.0

v1.36.0

v1.35.0

v1.34.0

v1.33.0

v1.32.0

v1.31.0

v1.30.0

v1.29.0

v1.28.0

v1.27.0

v1.26.0

v1.25.0

v1.24.0

v1.23.0

v1.22.0

v1.21.0

v1.20.0

v1.19.0

v1.18.0

v1.17.0

v1.16.0

v1.15.0

v1.14.0

v1.13.0

v1.12.0

v1.11.0

v1.10.0

v1.9.0

v1.8.0

v1.7.0

v1.6.0

v1.5.0

v1.4.0

v1.3.0

v1.2.0

v1.1.0