NAV Navbar
Logo

Getting Started v1.26.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-demo.wallex.asia.

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. Once the token has expired you will have to authenticate once again to obtain a new token. If you want to obtain a new token while the old token is still active, it is possible to do so.

Signup

Request body:

{
    "firstName": "From",
    "lastName": "Api",
    "email": "from.api2@yopmail.com",
    "password": "veryverysecret",
    "products": "payments, fx",
    "language": "en",
    "country": "SG",
    "accountType": "individual"
}

Response:

{
    "userId": "e8c32abb-6d5a-46fc-98ef-b7f4b36dca86",
    "email": "from.api2@yopmail.com",
    "firstName": "From",
    "lastName": "Api",
    "language": "en",
    "products": "payments, fx",
    "country": "SG",
    "accountType": "individual",
    "accessKeyId": "50afcbd2054d11e79317002618a72855",
    "secretAccessKey": "6D741B8CAA9D224896288FADB8A9DEFD18313A5AD98314D0386660646E92C803"
}

HTTP Request

POST /users/v1/signup

Body Parameters

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

Parameter Description
firstName
required
string Your first name
lastName
required
string Your last name
email
required
string Your email
password
required
string Your password
products
required
string Wallex product values can be payments, collections or fx
language
optional
string Your preferred language en or id, defaults to en
country
required
string Your country, in iso 3166 two letter code, the complete list can be fetched from Country List
accountType
required
string Can be company or individual

Response

Once signup is successful, the user will receive a confirmation email, describing the next steps to follow.

Parameter Description
userId string The user id, in uuid format
accessKeyId string Your access key ID
secretAccessKey string Your secret access key
email string email
firstName string first name
lastName string last name
language string preferred language
products string Wallex product values can be payments, collections or fx
country string Your country, in iso 3166 two letter code. The complete list can be fetched from Country List
accountType string Can be company or individual

Forgot Password

Request body:

{
    "email": "someone@yopmail.com"
}

Response:

{
    "message": "Email sent Please follow the link to change your password."
}

HTTP Request

POST /users/v1/forgot-password

Body Parameters

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

Parameter Description
email
required
string Your email

Response

Once request is success, user will receive the email for and follow the steps there.

Parameter Description
message string message

Resend Confirmation Email

Request body:

{
    "email": "someone@yopmail.com"
}

Response:

{}

HTTP Request

POST /users/v1/signup/resend

Body Parameters

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

Parameter Description
email
required
string Your email

Response

Response will be a blank response, and you should get the confirmation email sent to the email submitted as payload.

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

Beneficiaries API

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": {
                "bicSwift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$",
                "accountNumber": "^\\d{6,16}$"
            }
        },
        {
            "entityType": "company",
            "address": "^.{1,255}",
            "country": "^[A-z]{2}$",
            "city": "^.{1,255}",
            "companyName": "^.{1,255}",
            "bankAccount": {
                "bicSwift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$",
                "accountNumber": "^\\d{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:

{
    "country": "SG",
    "bankAccount": {
        "bankName": "Bank Of Singapore",
        "address": "Road 123",
        "currency": "SGD",
        "country": "SG",
        "bankAccountHolderName": "John",
        "accountNumber": "12345678",
        "bicSwift": "UOVBSGSG"
    },
    "nickname": "JOHN_SG",
    "email": "user@example.com",
    "entityType": "company",
    "city": "Singapore",
    "address": "Road 321",
    "companyName": "Wallex",
    "businessRegistration": "056790815678",
    "nationalIdentificationNumber": "098444416781",
    "region": "KOTA JAKARTA SELATAN"
}

Response:

{
    "data": {
        "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
        "email": "user@example.com",
        "nickname": "JOHN_SG",
        "type": "bank",
        "country": "SG",
        "city": "Singapore",
        "address": "Road 321",
        "companyName": "Wallex",
        "entityType": "company",
        "updatedAt": "2018-09-13T09:19:51.057",
        "bankAccount": {
            "bankId": "2ae14d70-b736-11e8-a999-0201da8d0509",
            "accountNumber": "12345678",
            "bankName": "Bank Of Singapore",
            "bankAccountHolderName": "John",
            "currency": "SGD",
            "country": "SG",
            "address": "Road 123",
            "bicSwift": "UOVBSGSG",
            "updatedAt": "2018-09-13T09:19:51.000"
        },
        "userId": 1
    }
}

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
nickname
required
string The nickname/alias of the beneficiary
email
required
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
required
string The city of the beneficiary
address
required
string The address of the beneficiary
postcode
required
string The postcode of the beneficiary
stateOrProvince
required
string The state/province of the beneficiary
firstName
required
string The first name of the beneficiary, needed for individual
lastName
required
string The last name of the beneficiary, needed for individual
companyName
required
string The company name of the beneficiary, needed for company
businessRegistration
required
string the company business registration number, needed for company
nationalIdentificationNumber
required
string the user national identification number, needed for individual
region
required
string The region of the beneficiary, needed for indonesian beneficiary

Body Parameters: Bank Account

Parameter Description
country
required
string The country of the bank
currency
required
string The currency of the bank account
bankName
required
string The beneficiary bank name
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
required
string The address of the beneficiary bank
accountNumber
required
string The bank account number
bicSwift
required
string The BIC/SWIFT of the bank account
iban
required
string The IBAN of the bank account
cnaps
required
string The CNAPS of the bank account
clabe
required
string The CLABE of the bank account
aba
required
string The ABA of the bank account
sortCode
required
string The Sort code of the bank account
bsbCode
required
string The BSB code of the bank account
bankCode
required
string The bank code of the bank account
branchCode
required
string The branch code of the bank account
institutionNo
required
string The institution number

Retrieve a Beneficiary

Response:

{
    "data": {
        "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
        "email": "user@example.com",
        "nickname": "JOHN_SG",
        "type": "bank",
        "country": "SG",
        "city": "Singapore",
        "address": "Road 321",
        "companyName": "Wallex",
        "entityType": "company",
        "updatedAt": "2018-09-13T09:19:51.057",
        "bankAccount": {
            "bankId": "2ae14d70-b736-11e8-a999-0201da8d0509",
            "accountNumber": "12345678",
            "bankName": "Bank Of Singapore",
            "bankAccountHolderName": "John",
            "currency": "SGD",
            "country": "SG",
            "address": "Road 123",
            "iban": null,
            "bicSwift": "UOVBSGSG",
            "aba": null,
            "bsbCode": null,
            "sortCode": null,
            "institutionNo": null,
            "bankCode": null,
            "branchCode": null,
            "cnaps": null,
            "clabe": null,
            "updatedAt": "2018-09-13T09:19:51.000"
        },
        "userId": 1
    }
}

Returns the specified beneficiary of the current user.

HTTP Request

GET /beneficiaries/v1/item/:beneficiaryId

Query Parameters

Parameter Description
beneficiaryId
required
string The ID of the beneficiary

Delete a Beneficiary

Response:

{
    "data": {
        "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
        "email": "user@example.com",
        "nickname": "JOHN_SG",
        "type": "bank",
        "country": "SG",
        "city": "Singapore",
        "address": "Road 321",
        "companyName": "Wallex",
        "firstName": null,
        "lastName": null,
        "entityType": "company",
        "updatedAt": "2018-09-13T09:19:51.057",
        "postcode": null,
        "stateOrProvince": null,
        "bankAccount": {
            "bankId": "2ae14d70-b736-11e8-a999-0201da8d0509",
            "accountNumber": "12345678",
            "bankName": "Bank Of Singapore",
            "bankAccountHolderName": "John",
            "currency": "SGD",
            "country": "SG",
            "address": "Road 123",
            "iban": null,
            "bicSwift": "UOVBSGSG",
            "aba": null,
            "bsbCode": null,
            "sortCode": null,
            "institutionNo": null,
            "bankCode": null,
            "branchCode": null,
            "cnaps": null,
            "clabe": null,
            "updatedAt": "2018-09-13T09:19:51.000"
        },
        "userId": 1
    }
}

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

HTTP Request

DELETE /beneficiaries/v1/item/:beneficiaryId

Query Parameters

Parameter Description
beneficiaryId
required
string The ID of the beneficiary

Get All Beneficiaries

Response:

{
    "data": [
        {
            "beneficiaryId": "2ae51d82-b736-11e8-a999-0201da8d0509",
            "email": "user@example.com",
            "nickname": "JOHN_SG",
            "type": "bank",
            "country": "SG",
            "city": "Singapore",
            "address": "Road 321",
            "companyName": "Wallex",
            "firstName": null,
            "lastName": null,
            "entityType": "company",
            "updatedAt": "2018-09-13T09:19:51.057",
            "postcode": null,
            "stateOrProvince": null,
            "bankAccount": {
                "bankId": "2ae14d70-b736-11e8-a999-0201da8d0509",
                "accountNumber": "12345678",
                "bankName": "Bank Of Singapore",
                "bankAccountHolderName": "John",
                "currency": "SGD",
                "country": "SG",
                "address": "Road 123",
                "iban": null,
                "bicSwift": "UOVBSGSG",
                "aba": null,
                "bsbCode": null,
                "sortCode": null,
                "institutionNo": null,
                "bankCode": null,
                "branchCode": null,
                "cnaps": null,
                "clabe": null,
                "updatedAt": "2018-09-13T09:19:51.000"
            },
            "userId": 1
        },
        {
            "beneficiaryId": "41111ab2-b738-11e8-a999-0201da8d0509",
            "email": "user@example.com",
            "nickname": "JOHN_SG",
            "type": "bank",
            "country": "SG",
            "city": "Singapore",
            "address": "Road 321",
            "companyName": "Wallex",
            "firstName": null,
            "lastName": null,
            "entityType": "company",
            "updatedAt": "2018-09-13T09:34:47.249",
            "postcode": null,
            "stateOrProvince": null,
            "paymentTypes": "priority",
            "bankAccount": {
                "bankId": "410e8a77-b738-11e8-a999-0201da8d0509",
                "accountNumber": "12345678",
                "bankName": "Bank Of Singapore",
                "bankAccountHolderName": "John",
                "currency": "SGD",
                "country": "SG",
                "address": "Road 123",
                "iban": null,
                "bicSwift": "UOVBSGSG",
                "aba": null,
                "bsbCode": null,
                "sortCode": null,
                "institutionNo": null,
                "bankCode": null,
                "branchCode": null,
                "cnaps": null,
                "clabe": null,
                "updatedAt": "2018-09-13T09:34:47.000"
            },
            "userId": 1
        }
    ]
}

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

HTTP Request

POST /beneficiaries/v1/find

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": "IDRSGD",
        "bid": 0.000096,
        "ask": 0.000097
    }
}

HTTP Request

GET /currencies/v1/rates/:currencyPair

Query Parameters

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

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

Conversions API

Get a Conversion Quote

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

Request body:

{
    "buyCurrency": "IDR",
    "sellCurrency": "SGD",
    "fixedSide": "buy",
    "amount": 1000
}

Response:

{
    "data": {
        "currencyPair": "SGDIDR",
        "buyCurrency": "IDR",
        "sellCurrency": "SGD",
        "buyAmount": 1000,
        "sellAmount": 0.1,
        "fixedSide": "buy",
        "rate": 10876,
        "totalAmount": 0.1,
        "settlementCutOffTime": "2018-09-21T03:23:15Z",
        "quoteId": "319cbdea-611c-4054-bcc1-694cbcd2114a",
        "totalFees": 0
    }
}

HTTP Request

POST /conversions/v1/quote

Body Parameters

Parameter Description
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
currencyPair string currency pair
buyCurrency string conversion buy currency
sellCurrency string conversion sell currency
buyAmount number buy amount
sellAmount number sell amount
fixedSide string fixed side
rate number rate
totalFees number fee amount
totalAmount number total amount
settlementCutOffTime string settlement cut off time
quoteId string quote id

Create a Conversion

Request body:

{
    "quoteId": "319cbdea-611c-4054-bcc1-694cbcd2114a",
    "reason": "Some reason"
}

Response:

{
    "data": {
        "id": "87993037bc8411e8a9990201da8d0509",
        "shortReference": "20180920-IUSBZG",
        "settlementDate": "2018-09-21T00:00:00.000Z",
        "conversionDate": "2018-09-21T00:00:00.000",
        "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:23.000Z",
        "updatedAt": "2018-09-20T03:23:23.000Z",
        "totalFees": 0,
        "referenceId": "X-123"
    }
}

Creates a conversion.

HTTP Request

POST /conversions/v1/create

Body Parameters

Parameter Description
quoteId
required
string The quote Id from /quote endpoint
referenceId
optional
string Identifier / description of the transaction in your system

Response

Property Description
id string conversion id
shortReference string conversion short reference
settlementDate string conversion settlement date
conversionDate string conversion date
status string conversion status
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
creationAt string date the conversion created
updatedAt string date the conversion updated
totalFees number fee amount
referenceId string reference id

Listing Conversions

Request body:

{
    "startDate": "2019-05-07T08:59:49Z",
    "endDate": "2021-06-07T08:59:49Z",
    "referenceId": "X-123"
}

Response body:

{
    "data": [
        {
            "id": "afa4f00a043111e999ce065f88b5bfa2",
            "reference": "20181220-YXQKWS",
            "settlementDate": "2018-12-24T14:00:00Z",
            "conversionDate": "2018-12-21T00:00:00Z",
            "status": "awaiting_funds",
            "currencyPair": "EURSGD",
            "buyCurrency": "EUR",
            "sellCurrency": "SGD",
            "fixedSide": "buy",
            "buyAmount": 1000,
            "sellAmount": 1597.8,
            "totalAmount": 1605.47,
            "totalFees": 45.41,
            "rate": 1.5978,
            "createdAt": "2018-12-20T16:31:44Z",
            "updatedAt": "2018-12-20T16:31:44Z",
            "referenceId": "X-123"
        },
        {
            "id": "d564a35208f711e999ce065f88b5bfa2",
            "reference": "20181226-RJCFTZ",
            "settlementDate": "2018-12-31T14:00:00Z",
            "conversionDate": "2018-12-27T00:00:00Z",
            "status": "awaiting_funds",
            "currencyPair": "EURSGD",
            "buyCurrency": "EUR",
            "sellCurrency": "SGD",
            "fixedSide": "buy",
            "buyAmount": 1000,
            "sellAmount": 1597.8,
            "totalAmount": 0,
            "rate": 1.5978,
            "totalFees": 45.41,
            "createdAt": "2018-12-26T18:20:12Z",
            "updatedAt": "2018-12-26T18:20:12Z",
            "referenceId": "X-123"
        }
    ]
}

HTTP Request

POST /conversions/v1/find

Body Parameters

Parameter Description
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

Response

Property Description
reference string reference code
settlementDate string settlement date
conversionDate string conversion date
status string conversion status
currencyPair string currency pair
buyCurrency string buy currency
sellCurrency string sell currency
fixedSide string fixed side
buyAmount number buy amount
sellAmount number sell amount
totalAmount number total amount
rate number conversion rate
createdAt string when conversion created
updatedAt string when conversion updated
totalFees number fee amount
referenceId string reference id

Retrieve a Conversion

Response body:

{
    "data": {
            "id": "d564a35208f711e999ce065f88b5bfa2",
            "reference": "20181226-RJCFTZ",
            "settlementDate": "2018-12-31T14:00:00Z",
            "conversionDate": "2018-12-27T00:00:00Z",
            "status": "awaiting_funds",
            "currencyPair": "EURSGD",
            "buyCurrency": "EUR",
            "sellCurrency": "SGD",
            "fixedSide": "buy",
            "buyAmount": 1000,
            "sellAmount": 1597.8,
            "totalAmount": 0,
            "rate": 1.5978,
            "totalFees": 45.41,
            "createdAt": "2018-12-26T18:20:12Z",
            "updatedAt": "2018-12-26T18:20:12Z",
            "referenceId": "X-123"
        }
}

HTTP Request

get /conversions/v1/item/:conversionId?reference=true

Query Parameters

Parameter Description
conversionId
required
string The ID of the conversiom
reference
optional
boolean mark the conversionId field as referenceId not conversionId if exist

Response

Property Description
reference string reference code
settlementDate string settlement date
conversionDate string conversion date
status string conversion status
currencyPair string currency pair
buyCurrency string buy currency
sellCurrency string sell currency
fixedSide string fixed side
buyAmount number buy amount
sellAmount number sell amount
totalAmount number total amount
rate number conversion rate
createdAt string when conversion created
updatedAt string when conversion updated
totalFees number fee amount
referenceId string reference id

Conversion Status Notification

Update your conversion status when the requirements are met or unmet

Payload:

{
    "resource": "conversion",
    "status": "processing",
    "conversionId": "e26fda80-c845-11e8-8910-8541dfd4ff96"
}

Payload

Property Description
resource string The resource of conversion
conversionId string The ID of conversion
status string The status of conversion

Status values:

Simple Payments API

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:

{
    "buyCurrency": "IDR",
    "sellCurrency": "SGD",
    "amount": 1000,
    "beneficiaryId": "b195da54-bd4f-11e8-a999-0201da8d0509",
    "fixedSide": "sell"
}

Response:

{
    "data": {
        "deliveryDate": "2018-09-27",
        "currencyPair": "SGDIDR",
        "buyCurrency": "IDR",
        "sellCurrency": "SGD",
        "buyAmount": 1000,
        "sellAmount": 0.1,
        "fixedSide": "buy",
        "rate": 10898,
        "feeRate": 0,
        "totalAmount": 0.1,
        "setlementCutOffTime": "2018-09-26T00:35:45Z",
        "quoteId": "5595393c-9294-4a60-a1e7-97fb4981b9a3",
        "conversionDate": "2018-09-27",
        "conversionFee": 0,
        "paymentFee": 0,
        "totalFee": 0,
        "conversionFeeRate": 0,
        "paymentFeeRate": 0,
        "totalFeeRate": 0,
        "expiresAt": "2018-09-27T00:35:45Z"
    }
}

HTTP Request

POST /simple-payments/v1/quote

Body Parameters

Parameter Description
buyCurrency
required
string Your buy currency, i.e. “IDR”
sellCurrency
required
string Your sell currency, i.e. “SGD”
amount
required
number The amount to pay, i.e. 1000
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.
fixedSide
optional
string which side of currency your amount we should keep. we will calculate the other side (default as sell if not present)

Response

Property Description
deliveryDate string The quote delivery date
currencyPair string The currency pair
buyCurrency string The buy currency
sellCurrency string The sell currency
buyAmount number Amount of buy
sellAmount number Amount of sell
fixedSide string The fixed side
rate number The rate
feeRate number The fee rate
totalAmount number Total amount
setlementCutOffTime string The settlement cut off time
quoteId string The quote ID
conversionDate string The conversion date
conversionFee number The conversion fee
paymentFee number The payment fee
totalFee number Total fee
conversionFeeRate number The conversion fee rate
paymentFeeRate number The payment fee rate
totalFeeRate number The total fee rate
expiresAt string The maximum time for this quote is available to use

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"
}

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

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 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 a Simple Payment

Request body:

{
    "fundingSource": "SALARY_WAGES",
    "paymentReference": "Payment Reference",
    "quoteId": "5595393c-9294-4a60-a1e7-97fb4981b9a3",
    "purposeOfTransfer": "OTH",
    "purposeOfTransferDescription": "Your own custom purpose",
    "files": [
        "d37673e3-341f-453f-9fa9-521e4ba21c2d",
    ]
}

Response:

{
    "data": {
        "simplePaymentId": "03d81ec1-c05b-11e8-a999-0201da8d0509",
        "totalAmount": 0.1,
        "status": "awaiting_funds",
        "buyAmount": 1000,
        "buyCurrency": "IDR",
        "sellAmount": 0.1,
        "sellCurrency": "SGD",
        "currencyPair": "SGDIDR",
        "rate": 10898,
        "conversionFee": 0,
        "paymentFee": 0,
        "totalFee": 0,
        "conversionFeeRate": 0,
        "paymentFeeRate": 0,
        "totalFeeRate": 0,
        "createdAt": "2018-09-25T00:36:17.000",
        "completedAt": null,
        "updatedAt": "2018-09-25T00:36:17.000",
        "settlementDate": "2018-09-26T00:00:00.000",
        "username": "user@wallextech.com",
        "userId": 1,
        "reference": "180925-SIM-03D82001",
        "paymentReference": "Payment Reference",
        "paymentDate": "2018-09-27T00:00:00.000",
        "failureReason": null,
        "fundingSource": "SALARY_WAGES",
        "comment": null,
        "paymentMode": "manual",
        "ownerName": "API User",
        "beneficiary": {
             "email": "user@example.com",
             "nickname": "JOHN_SG",
             "type": "bank",
             "country": "SG",
             "city": "Singapore",
             "address": "Road 321",
             "companyName": "Wallex",
             "entityType": "company",
             "updatedAt": "2018-09-13T09:19:51.057",
             "paymentTypes": "priority",
             "bankAccount": {
                 "accountNumber": "12345678",
                 "bankName": "Bank Of Singapore",
                 "bankAccountHolderName": "John",
                 "currency": "SGD",
                 "country": "SG",
                 "address": "Road 123",
                 "bicSwift": "UOVBSGSG",
                 "updatedAt": "2018-09-13T09:19:51.000"
             },
             "userId": 1
            },
            "referenceId": "X-123"
    }
}

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
fundingSource
required
string The source of funding.
paymentReference
required
string The reference for the payment
quoteId
required
string The quote Id from /quote endpoint
purposeOfTransfer
required
string The purpose of transaction use Purpose of transfer values on the table below
purposeOfTransferDescription
optional
stringadditional info of purpose code only required when purposeOfTransfer is OTH
files
required
array Array of file id to be included in the simple payment.
referenceId
optional
string Identifier / description of the transaction in your system
senderUserId
optional
string The user id that you acted on for this payment

Funding source values:

Purpose of transfer values:

Code Description
FAM Family Support/Living Expenses
SAV Saving/Investments
COM Goods and Services Payment/Commercial Transaction
TRA Travel Expenses
EDU Education/School Fee
REN Rent/Mortgage
AID Emergency/Medical Aid
PAY Employee Payroll/Employee Expenses
OTH Other
purposeOfTransferDescription field is required when purposeOfTransfer is OTH

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
rate number The rate of payment
conversionFee number The conversion fee
paymentFee number The payment fee
totalFee number Total fee
conversionFeeRate number The conversion fee rate
paymentFeeRate number The payment fee rate
totalFeeRate number Total fee rate
beneficiaryId string The ID of beneficiary
beneficiaryName string The name of beneficiary
createdAt string The date simple payment created
completedAt string The date simple payment completed
updatedAt string The date simple payment last updated
settlementDate string The date simple payment settled
username string The email of user who created the simple payment
userId number The ID of user
reference string The reference for the simple payment
paymentReference string The payment reference
paymentDate string The payment date
failureReason string The failure reason
fundingSource string The source of funding
comment string The comment
paymentMode string The payment mode
ownerName string The name of user who created the simple payment
referenceId string reference id
fundingReference string 6 digit code for your reference to fund the simple payment
senderUserId string The sender user id

Retrieve a Simple Payment

Response:

{
    "data": {
        "simplePaymentId": "03d81ec1-c05b-11e8-a999-0201da8d0509",
        "totalAmount": 0.1,
        "status": "awaiting_funds",
        "buyAmount": 1000,
        "buyCurrency": "IDR",
        "sellAmount": 0.1,
        "sellCurrency": "SGD",
        "currencyPair": "SGDIDR",
        "rate": 10898,
        "conversionFee": 0,
        "paymentFee": 0,
        "totalFee": 0,
        "conversionFeeRate": 0,
        "paymentFeeRate": 0,
        "totalFeeRate": 0,
        "beneficiaryId": "b195da54-bd4f-11e8-a999-0201da8d0509",
        "beneficiaryName": "JOHN_SG",
        "createdAt": "2018-09-25T00:36:17.000",
        "completedAt": null,
        "updatedAt": "2018-09-25T00:36:17.000",
        "settlementDate": "2018-09-26T00:00:00.000",
        "username": "user@wallextech.com",
        "userId": 1,
        "reference": "180925-SIM-03D82001",
        "paymentReference": "Payment Reference",
        "paymentDate": "2018-09-27T00:00:00.000",
        "failureReason": null,
        "fundingSource": "SALARY_WAGES",
        "comment": null,
        "paymentMode": "manual",
        "ownerName": "API User",
        "referenceId": "X-123",
        "fundingReference": "F3UBY8"
    }
}

Returns the specified simple payment of the current user.

HTTP Request

GET /simple-payments/v1/item/:simplePaymentId?reference=true

Query Parameters

Parameter Description
simplePaymentId
required
string The ID of the simple payment
reference
optional
boolean mark the simplePaymentId field as referenceId not simplePaymentId if exist

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
rate number The rate of payment
conversionFee number The conversion fee
paymentFee number The payment fee
totalFee number Total fee
conversionFeeRate number The conversion fee rate
paymentFeeRate number The payment fee rate
totalFeeRate number Total fee rate
beneficiaryId string The ID of beneficiary
beneficiaryName string The name of beneficiary
createdAt string The date simple payment created
completedAt string The date simple payment completed
updatedAt string The date simple payment last updated
settlementDate string The date simple payment settled
username string The email of user who created the simple payment
userId number The ID of user
reference string The reference for the simple payment
paymentReference string The payment reference
paymentDate string The payment date
failureReason string The failure reason
fundingSource string The source of funding
comment string The comment
paymentMode string The payment mode
ownerName string The name of user who created the simple payment
referenceId string reference id
fundingReference string 6 digit code for your reference to fund the simple payment

Get All Simple Payments

Request:

{
    "startDate": "2019-05-07T08:59:49Z",
    "endDate": "2021-06-07T08:59:49Z",
    "referenceId": "X-123"
}

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",
            "rate": 1.5929,
            "conversionFee": 15.29184,
            "paymentFee": 1,
            "totalFee": 16.29,
            "conversionFeeRate": 0.0048,
            "paymentFeeRate": 0.00031389,
            "totalFeeRate": 0.00511332,
            "beneficiaryId": "735a04bc-ad32-11e8-a999-0201da8d0509",
            "beneficiaryName": "EUR Bank",
            "createdAt": "2018-08-31T15:30:23.000",
            "completedAt": null,
            "updatedAt": "2018-09-14T05:18:41.000",
            "settlementDate": "2018-09-01T07:30:00.000",
            "username": "user@wallextech.com",
            "userId": 1,
            "reference": "180831-SIM-C6D59BD1",
            "paymentReference": "Payemnt Reference",
            "paymentDate": "2018-09-04T00:00:00.000",
            "failureReason": null,
            "fundingSource": "SALARY_WAGES",
            "comment": null,
            "paymentMode": "manual",
            "ownerName": "API User",
            "referenceId": "X-123",
            "fundingReference": "F3UBY8"
        },
        {
            "simplePaymentId": "a510e89b-b7dd-11e8-a999-0201da8d0509",
            "totalAmount": 3202.09,
            "status": "awaiting_funds",
            "buyAmount": 2000,
            "buyCurrency": "EUR",
            "sellAmount": 3185.8,
            "sellCurrency": "SGD",
            "currencyPair": "EURSGD",
            "rate": 1.5929,
            "conversionFee": 15.29184,
            "paymentFee": 1,
            "totalFee": 16.29,
            "conversionFeeRate": 0.0048,
            "paymentFeeRate": 0.00031389,
            "totalFeeRate": 0.00511332,
            "beneficiaryId": "735a04bc-ad32-11e8-a999-0201da8d0509",
            "beneficiaryName": "EUR Bank",
            "createdAt": "2018-08-31T15:30:34.000",
            "completedAt": null,
            "updatedAt": "2018-09-14T05:18:41.000",
            "settlementDate": "2018-09-01T07:30:00.000",
            "username": "user@wallextech.com",
            "userId": 1,
            "reference": "180831-SIM-CDB93C30",
            "paymentReference": "Payent Reference",
            "paymentDate": "2018-09-04T00:00:00.000",
            "failureReason": null,
            "fundingSource": "SALARY_WAGES",
            "comment": null,
            "paymentMode": "manual",
            "ownerName": "API User",
            "referenceId": "X-1234",
            "fundingReference": "F3UBY8"
        }
    ]
}

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
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

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
rate number The rate of payment
conversionFee number The conversion fee
paymentFee number The payment fee
totalFee number Total fee
conversionFeeRate number The conversion fee rate
paymentFeeRate number The payment fee rate
totalFeeRate number Total fee rate
beneficiaryId string The ID of beneficiary
beneficiaryName string The name of beneficiary
createdAt string The date simple payment created
completedAt string The date simple payment completed
updatedAt string The date simple payment last updated
settlementDate string The date simple payment settled
username string The email of user who created the simple payment
userId number The ID of user
reference string The reference for the simple payment
paymentReference string The payment reference
paymentDate string The payment date
failureReason string The failure reason
fundingSource string The source of funding
comment string The comment
paymentMode string The payment mode
ownerName string The name of user who created the simple payment
referenceId string reference id

List Purpose Codes

POST Returns the list of purpose codes for the specified country.

HTTP Request

POST /purpose-codes/v1/find

Request body:

{
    "country": "ID"
}

Response:

{
  "data": [
    {
      "purposeCodeId": "2303b8a2-a86e-11e9-b419-408d5c4bd252",
      "code": "FAM",
      "description": "Family Support/Living Expenses",
      "country": "ID"
    },
    {
      "purposeCodeId": "230ae738-a86e-11e9-b419-408d5c4bd252",
      "code": "SAV",
      "description": "Saving/Investments",
      "country": "ID"
    }
  ]
}

Body Parameters

Parameter Description
country The country to list the purpose codes from

Response

Property Type Description
purposeCodeId string The ID of this purpose code entry
code string The code of this purpose code entry
description string The description of this purpose code entry

Simple Payment Status Notification

Update your payment status when the requirements are met or unmet

Payload:

{
    "resource": "simple_payment",
    "status": "processing",
    "resourceId": "e26fda80-c845-11e8-8910-8541dfd4ff96"
}

Payload

Property Description
resource string The resource of payments
resourceId string The ID of resource
status string The status of payment

Status values:

Balances API

Get All Balances

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"
        }
    ]
}

Get all balances

GET /balances/v1/find

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”

Response Body

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

Get Balances by ID

Response:

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

Get your current balances by balance id

HTTP Request

GET /balances/v1/item/:balanceId

URL Parameters

Parameter Description
balanceId
required
string balance id

Response Body

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

Get Balances History

Request:

{
    "startDate": "2014-07-21T17:00:00Z",
    "endDate": "2019-07-23T02:39:00Z"
}

Response:

{
    "data": [
        {
            "id": "8fa76a1db55011e78ce406141bd54fa5",
            "balanceId": "513080fe-89e3-11e6-9e92-026b39b3bdb9",
            "amountBefore": 12409921.23,
            "amountAfter": 12409757.81,
            "currency": "SGD",
            "totalAmount": 0,
            "transactionId": null,
            "transactionType": "",
            "date": "2017-10-20T04:38:47Z"
        }
    ]
}

POST /balances/v1/history

Body Parameters

Parameter Description
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

Query 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"
}

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”

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

Query 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.

Changelog

vNext

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