NAV Navbar
cURL

Version

API version 1.3.7

Documentation version 1.3.7

History

Version Date Name Description
1.0.0 2016/09/19 Dimitar Kostov Initial version
1.1.0 2018/06/10 Dimitar Kostov Added Single and Batch Payouts
1.2.0 2018/08/10 Dimitar Kostov Added eZeePayouts
1.2.1 2019/08/27 Dimitar Kostov Added notification response example
1.2.2 2019/09/03 Diganta Mandal Removed eZeePayouts
1.2.3 2020/03/18 Diganta Mandal Added optional currency parameters into the Transfers
1.2.4 2020/06/03 Diganta Mandal Added required merchant_website parameters into the Transfers
1.2.5 2021/01/22 Diganta Mandal Added accounts as a new endpoint
1.2.6 2021/05/25 Diganta Mandal Added notification IPs
1.2.7 2021/08/09 Diganta Mandal Removed BIllingAddress and CreditCard data types
1.2.8 2021/08/31 Diganta Mandal Added NotificationEcho response example
1.2.9 2022/04/18 Diganta Mandal Change API documentation regarding Forex exchange
1.3.0 2022/06/10 Diganta Mandal Added new parameter on Single Payout request
1.3.1 2022/08/11 Diganta Mandal Added new endpoint for Transfers
1.3.2 2022/09/01 Diganta Mandal Added new staging URL
1.3.3 2023/02/24 Milko Mihailov Added new endpoints for refactored payouts
1.3.4 2023/04/28 Diganta Mandal Added new endpoints for Transactions
1.3.5 2023/09/22 Diganta Mandal Removed staging old endpoint
1.3.6 2023/10/31 Diganta Mandal Added new endpoints for Refunds
1.3.7 2023/11/28 Diganta Mandal Added notification response example for payout

Overview

eZeeWallet API supports creating and listing transfer transactions via HTTPS using JSON.

You can get cURL from https://curl.haxx.se

Authentication

Wallet API uses HTTP Basic Authentication. Each merchant registered with eZeeWallet is provided an API username and password. These credentials are different from the login credentials of merchant employees and can be configured in 'Merchant API Details' tab.

Endpoint paths

Environment Address
Staging https://stg.ezeewallet.com/api
Production https://ezeewallet.com/api

Request and response headers

Requests to eZeeWallet API endpoints must include the following HTTP header:

Content-Type: application/json

By default, all endpoint responses provide data as JSON in the response body and include a Content-Type header:

application/json

Providing parameters

The way you provide parameters to a eZeeWallet API request depends on the HTTP method of the request.

GET requests

For GET requests, you provide parameters in a query string you append to your request's URL. For example, you provide the transaction_id parameter to the ListTransfers endpoint like so:

https://ezeewallet.com/api/transfers?transaction_id=MerchantTx123

{
  "transaction_id": "MerchantTx123",
  "usage": "Purchasing shoes",
  "amount": 10000,
  "currency": "USD",
  "source_wallet_id": "consumer@example.com",
  "source_wallet_pwd": "UGFzc3dvcmQx",
  "return_success_url": "http://example.com/success",
  "return_failure_url": "http://example.com/failure",
  "notification_url": "http://example.com/notification"
}

POST requests

For POST requests, you instead provide parameters as JSON in the body of your request. For example, the body of a request to the CreateTransfer endpoint looks like this:

Working with monetary amounts

Amounts on the API level should be submitted in the minor currency unit for the given currency. The currency field is in ISO 4217 format.

eZeeWallet does support any form of Forex. Per transfer transaction, currency usage is not restricted: the requested currency can be different than currency that is configured for the source wallet and the target wallet.

For example, if a consumer has a EUR wallet and a merchant has only a GBP wallet, a transfer is possible and EZW will take the amount requested in the API call from the user in their currency(EUR) and convert it into the merchant requested currency - GBP on a using specified exchange rate based on merchant contract

If a consumer and a merchant both have a EUR wallets only, then an API request for any currency other than EUR will receive a "Currency mismatch" error.

Working with dates

All representations of dates are strings in ISO RFC3339 format (date time 2011-01-11T00:00:00Z).

Paginating results

List endpoints such as ListTransfers might paginate the results they return. This means that instead of returning all results in a single response, these endpoints might return some of the results, along with a attributes for current page, page count, etc in the response body.

{
  "pagination": {
    "total_count": 190,
    "pages_count": 2,
    "page": 2,
    "per_page": 100
  },

  "transfers": [
    {},
    {},
  ]
}

Handling errors

eZeeWallet API endpoints use HTTP protocol status codes to indicate errors.

All eZeeWallet API endpoints include Error object in their response body if any errors occurred during a request. The response body has the following structure:

{
  "error": {
    "code": 407,
    "message": "Currency mismatch",
  }
}

Each error has the following fields:

See Error Codes for list of errors provided by the system

Endpoints

Transfers

CreateTransfer

Example request

{
  "transaction_id": "MerchantTx123",
  "usage": "Purchasing shoes",
  "amount": 10000,
  "currency": "USD",
  "source_wallet_id": "consumer@example.com",
  "source_wallet_pwd": "UGFzc3dvcmQx",
  "return_success_url": "http://example.com/success",
  "return_failure_url": "http://example.com/failure",
  "notification_url": "http://example.com/notification",
  "merchant_website": "www.test.com"
}

POST /transfers

Creates transfer, consumer to merchant wallet

Example response

{
  "transfer": {
    "transaction_id": "MerchantTx123",
    "usage": "Purchasing shoes",
    "amount": 10000,
    "currency": "USD",
    "source_wallet_id": "consumer@example.com",
    "return_success_url": "http://example.com/success",
    "return_failure_url": "http://example.com/failure",
    "status": "approved"
  }
}

Example response for pending async transfer

{
  "transfer": {
    "transaction_id": "MerchantTx123",
    "usage": "Purchasing shoes",
    "amount": 10000,
    "currency": "USD",
    "source_wallet_id": "consumer@example.com",
    "return_success_url": "http://example.com/success",
    "return_failure_url": "http://example.com/failure",
    "status": "pending",
    "redirect_url":"https://ezeewallet.com/en/consumers/top_up/random_unique_id"
  }
}

Example response for failed transfer due to an error

{
  "error": {
    "code": 407,
    "message": "Currency mismatch",
  }
}

Body params

Name Type Required Description
transaction_id string(255) yes Unique transaction id defined by merchant
usage string(255) no Description of the transaction that will be visible to end users
amount integer yes Amount of transaction in minor currency unit
currency string(3) no Currency code in ISO 4217
source_wallet_id string(255) yes Email address of consumer who owns the source wallet
source_wallet_pwd string(255) yes Password of consumer who owns the source wallet, in Base64 encoded form
return_success_url string(65535) yes URL where customer is sent to after successful payment
return_failure_url string(65535) yes URL where customer is sent to after unsuccessful payment
notification_url string(65535) yes URL where notification for transfer is sent
merchant_website string(65535) yes Website URL of the merchant

Response fields

Name Type Description
transfer Transfer The created transfer
error Error Any errors that occurred during the request.

Note that in the case of pending async (consumer does not have balance for the transaction and needs to top up) merchant will receive Notification upon transfer success/error and must respond with NotificationEcho

CreateTransfer New Endpoint

Example request

{
  "merchant_transaction_id": "MerchantTx123",
  "usage": "Purchasing shoes",
  "amount": 10000,
  "currency": "USD",
  "source_wallet_id": "consumer@example.com",
  "source_wallet_pwd": "UGFzc3dvcmQx",
  "return_success_url": "http://example.com/success",
  "return_failure_url": "http://example.com/failure",
  "notification_url": "http://example.com/notification",
  "merchant_website": "www.test.com"
}

POST /transfers_new

Creates transfer, consumer to merchant wallet

Example response

{
  "transfer": {
    "merchant_transaction_id": "MerchantTx123",
    "first_name": "consumer's first name",
    "last_name": "consumer's last name",
    "ezw_reference_id": "abc123",
    "amount": 10000,
    "currency": "USD",
    "source_wallet_id": "consumer@example.com",
    "return_success_url": "http://example.com/success",
    "return_failure_url": "http://example.com/failure",
    "status": "approved"
  }
}

Example response for pending async transfer

{
  "transfer": {
    "merchant_transaction_id": "MerchantTx123",
    "first_name": "consumer's first name",
    "last_name": "consumer's last name",
    "amount": 10000,
    "currency": "USD",
    "source_wallet_id": "consumer@example.com",
    "return_success_url": "http://example.com/success",
    "return_failure_url": "http://example.com/failure",
    "status": "pending",
    "redirect_url":"https://ezeewallet.com/en/consumers/top_up/random_unique_id"
  }
}

Example response for failed transfer due to an error

{
  "error": {
    "code": 407,
    "message": "Currency mismatch",
  }
}

Body params

Name Type Required Description
merchant_transaction_id string(255) yes Unique transaction id defined by merchant
usage string(255) no Description of the transaction that will be visible to end users
amount integer yes Amount of transaction in minor currency unit
currency string(3) no Currency code in ISO 4217
source_wallet_id string(255) yes Email address of consumer who owns the source wallet
source_wallet_pwd string(255) yes Password of consumer who owns the source wallet, in Base64 encoded form
return_success_url string(65535) yes URL where customer is sent to after successful payment
return_failure_url string(65535) yes URL where customer is sent to after unsuccessful payment
notification_url string(65535) yes URL where notification for transfer is sent
merchant_website string(65535) yes Website URL of the merchant

Response fields

Name Type Description
merchant_transaction_id string Unique transaction id defined by merchant
amount integer Amount of transaction in minor currency unit
currency string Currency code in ISO 4217
status string Status of the transfer transaction: approved or pending_async
source_wallet_id string Email address of consumer who owns the source wallet
return_success_url string URL where the consumer must be redirected to deposit money if the status is pending async
return_failure_url string URL where the consumer must be redirected to deposit money if the status is pending async
redirect_url string URL where the consumer must be redirected to deposit money if the status is pending async
first_name string Consumer's first name
last_name string Consumer's last name
ezw_reference_id string Unique transaction id in eZeeWallet transaction history
error Error Any errors that occurred during the request.

Status of the transaction in the response as follows:

The customer will be prompted to log in to their account and deposit the difference. Once the deposit is finalised, you will receive a Notification to the notification URL specified in your request upon transfer success or error and merchant must respond to us via NotificationEcho.

Notifications Possible statuses for the notification sent to merchant:

ListTransfers

GET /transfers?ezw_reference_id=value

GET /transfers?start_date=value&end_date=value

Example response

{
  "total_count": 1,
  "pages_count": 1,
  "per_page": 30,
  "page": "1",
  "transfers": [
    {
      "ezw_reference_id": "1062431493",
      "merchant_transaction_id": "m_tr_id1681110756",
      "currency": "EUR",
      "consumer_email": "testezeewallet+demo@gmail.com",
      "return_success_url": "http://example.com/success",
      "return_failure_url": "http://example.com/failure",
      "status": "approved",
      "amount": 6000
    }
  ]
}

Body params

Name Type Requried Description
param_name string(255) yes ezw_reference_id or start_date and end_date

Response fields

Name Type Description
pagination Pagination pagination options object
transfers TransferNew Array of returned transfers
error Error Any error that occurred during the request.

Status of the transaction in the response as follows:

Refunds

CreateRefund

Example request

{
  "merchant_transaction_id": "MerchantTx123",
  "ezw_reference_id": "SampleTx123",
  "usage": "Purchasing shoes",
  "amount": 10000,
  "currency": "USD",
  "notification_url": "http://example.com/notification"
}

POST /refunds

Creates refund, merchant wallet to consumer wallet

Example response

{
  "refund": {
    "merchant_transaction_id": "MerchantTx123",
    "ezw_reference_id": "SampleTx123",
    "amount": 10000,
    "currency": "USD",
    "notification_url": "http://example.com/notification",
    "status": "approved"
  }
}

Body params

Name Type Required Description
merchant_transaction_id string(255) yes Unique transaction id defined by merchant
ezw_reference_id string(255) yes Unique transaction id in eZeeWallet transaction history of the transfer
usage string(255) no Description of the transaction that will be visible to end users
amount integer yes Amount of transaction in minor currency unit
currency string(3) yes Currency code in ISO 4217
notification_url string(65535) no URL where notification for refund is sent

Response fields

Name Type Description
refund Refund The created refund
error Error Any errors that occurred during the request.

Transactions

List Transactions

GET /transaction?ezw_reference_id=value

Example response for transaction type - transfer:

{
  "ezw_reference_id": "1062431493",
  "status": "approved",
  "type": "transfer"
}

Example response for transaction type - payout:

{
  "ezw_reference_id": "1062431493",
  "status": "approved",
  "type": "payout"
}

Body params

Name Type Requried Description
param_name string(255) yes ezw_reference_id, retuned with the initial transaction

Response fields

Name Type Description
ezw_reference_id string Unique transaction id in eZeeWallet transaction history
status string Status of the transfer transaction: approved or pending or declined
type string Transaction type: transfer or payout
error Error Any error that occurred during the request.

Status of the transaction in the response as follows:

Single Payouts

Create Single Payout

POST /single_payouts

Creates single payout, merchant wallet to consumer wallet

Example request

{
  "email": "consumer@emp.com",
  "amount": 100,
  "currency": "USD",
  "merchant_reference": "abc123",
  "notification_url": "http://example.com/notification"
}

Example response

{
  "unique_id": 2,
  "status": "succeeded",
  "merchant_reference": "abc123"
}

Body params

Name Type Required Description
email string(255) yes Email address of consumer that will receive the amount
amount integer yes Amount of payout in minor currency unit
currency string(3) yes Currency code in ISO 4217
merchant_reference string(255) no Merchant reference identifier
notification_url string(65535) no URL where notification for payout is sent

Response fields

Name Type Description
payout SinglePayout The created payout
error Error Any errors that occurred during the request.

Single Payouts New Endpoint

Create Single Payout

POST /single_payouts_new

Creates single payout, merchant wallet to consumer wallet

Example request

{
  "email": "consumer@emp.com",
  "amount": 100,
  "currency": "USD",
  "merchant_reference": "abc123",
  "notification_url": "http://example.com/notification"
}

Example response

{
  "ezw_reference_id": "1010312223",
  "status": "pending",
  "merchant_reference": "abc123"
}

Body params

Name Type Required Description
email string(255) yes Email address of consumer that will receive the amount
amount integer yes Amount of payout in minor currency unit
currency string(3) yes Currency code in ISO 4217
merchant_reference string(255) no Merchant reference identifier
notification_url string(65535) no URL where notification for payout is sent

Response fields

Name Type Description
payout SinglePayoutNew The created payout
error Error Any errors that occurred during the request.

Batch Payouts

Create Batch Payout

Example request

{
  "payout_requests": [
    {
      "email": "consumer1@emerchantpay.com",
      "amount": 100,
      "currency": "USD",
      "merchant_reference": "abc123"
    },
    {
      "email": "consumer2@emerchantpay.com",
      "amount": 200,
      "currency": "EUR",
      "merchant_reference": "abc124"
    },
    {
      "email": "consumer2@emerchantpay.com",
      "amount": 350,
      "currency": "GBP",
      "merchant_reference": "abc125"
    }
  ]
}

Example response

{
  "unique_id": 5,
  "status": "pending"
}

POST /batch_payouts

Creates batch payout, merchant wallet to consumer wallet

Body params

Name Type Requried Description
payout_requests PayoutRequest[] Yes Array of payout request objects

Response fields

Name Type Description
batch_payout BatchPayout The created payout
error Error Any errors that occurred during the request.

Batch Payouts New Endpoint

Create Batch Payout

Example request

{
  "payout_requests": [
    {
      "email": "consumer1@emerchantpay.com",
      "amount": 100,
      "currency": "USD",
      "merchant_reference": "abc123"
    },
    {
      "email": "consumer2@emerchantpay.com",
      "amount": 200,
      "currency": "EUR",
      "merchant_reference": "abc124"
    },
    {
      "email": "consumer2@emerchantpay.com",
      "amount": 350,
      "currency": "GBP",
      "merchant_reference": "abc125"
    }
  ]
}

Example response

{
  "unique_ids": [
      {
          "email": "consumer1@emerchantpay.com",
          "amount": 100,
          "currency": "EUR",
          "merchant_reference": "abc123"
      },
      {
          "email": "consumer2@emerchantpay.com",
          "amount": 200,
          "currency": "EUR",
          "merchant_reference": "abc124"
      },
      {
          "email": "consumer2@emerchantpay.com",
          "amount": 350,
          "currency": "EUR",
          "merchant_reference": "abc125"
      }
    ],
    "status": "pending"
}

POST /batch_payouts_new

Creates batch payout, merchant wallet to consumer wallet

Body params

Name Type Requried Description
payout_requests PayoutRequest[] Yes Array of payout request objects

Response fields

Name Type Description
batch_payout BatchPayoutNew The created payout
error Error Any errors that occurred during the request.

Accounts

Get Account Data

Example request

{
  "email": "john.doe@example.com"
}

Example response

{
  "wallet_account_number": 1,
  "verification_status": "verified",
  "account_status": "active"
}

GET /account

Gets consumer account data by email

Body params

Name Type Requried Description
email string Yes Email of consumer

Data Types

Transfer

Name Type Description
transaction_id string Unique transfer transaction id defined by merchant
amount integer Amount of transfer transaction in minor currency unit
currency string Currency code in ISO 4217
status string Status of the transfer transaction: approved or pending_async
source_wallet_id string Email address of consumer who owns the source wallet
return_success_url string URL where the consumer must be redirected to deposit money if the status is pending async
return_failure_url string URL where the consumer must be redirected to deposit money if the status is pending async
redirect_url string URL where the consumer must be redirected to deposit money if the status is pending async

TransferNew

Name Type Description
ezw_reference_id string Unique id defined by eZeeWallet for later use
merchant_transaction_id string Unique transfer transaction id defined by merchant
currency string Currency code in ISO 4217
consumer_email string Email address of consumer who owns the source wallet
return_success_url string URL where the consumer must be redirected to deposit money if the status is pending async
return_failure_url string URL where the consumer must be redirected to deposit money if the status is pending async
status string Status of the transfer transaction: approved or pending or declined
amount integer Amount of transfer transaction in minor currency unit

Refund

Name Type Description
merchant_transaction_id string Unique transaction id defined by merchant
ezw_reference_id string Unique transaction id in eZeeWallet transaction history
amount integer Amount of refund in minor currency unit
currency string Currency code in ISO 4217
notification_url string URL where notification for refund is sent
status string Status of the refund transaction: approved or declined

PayoutRequest

Name Type Description
email string(255) Email address of consumer that will receive the amount
amount integer Amount of payout in minor currency unit
currency string(3) Currency code in ISO 4217
merchant_reference string(255) Merchant reference identifier

SinglePayout

Name Type Description
unique_id string Unique id defined by eZeeWallet for later use
status string Status of the transfer transaction: succeeded or failed
merchant_reference string Merchant reference identifier

SinglePayoutNew

Name Type Description
ezw_reference_id string Unique id defined by eZeeWallet for later use
status string Status of the transfer transaction: approved or pending
merchant_reference string Merchant reference identifier

BatchPayout

Name Type Description
unique_id string Unique id defined by eZeeWallet for later use
status string Status of the transfer transaction: pending or failed

BatchPayoutNew

Name Type Description
unique_id array Array of ConsumerData
status string Status of the payout: pending or failed

ConsumerData

Name Type Description
email string(255) Email address of consumer that will receive the amount
amount integer Amount of payout in minor currency unit
currency string(3) Currency code in ISO 4217
merchant_reference string(255) Merchant reference identifier

Error

Name Type Description
code string machine parsable error code
message string human-readable message with a simple description of the error

Pagination

Name Type Description
total_count integer total count of the returned objects
pages_count integer count of the pages
page integer current page
per_page integer number of returned objects per page

Notification

Name Type Description
transaction_id string Unique transfer transaction id defined by merchant
unique_id string Unique id defined by eZeeWallet for later use
status string Status of the transfer transaction request
signature string The signature of the notification used to verify the notification

Status can be: approved or declined. The signature is a mean of security to ensure that eZeeWallet is really the sender of the notification. It is generated by concatenating the transaction id of the transaction with the merchant name and generating a SHA1 Hash (Hex) of the string:

SHA1 Hash (Hex) of <transaction_id><merchant api_username>

Example:

transaction_id = 123456789abcdefg

merchant api_username = 0987654321xyz

signature -> 9ec1df9a7013f6a5b952b9d3f12d620475d37c86

Example response for payout

{
  "ezw_reference_id": "SampleTx123",
  "merchant_reference": "abc123",
  "unique_id" : "123456789abcdefg",
  "status" : "approved",
  "signature" : "9ec1df9a7013f6a5b952b9d3f12d620475d37c86"
}

Example response

{
  "transaction_id" : "123456789abcdefg",
  "status" : "approved",
  "signature" : "9ec1df9a7013f6a5b952b9d3f12d620475d37c86"
}

Whitelist below IPs for getting notification:

NotificationEcho

Name Type Description
unique_id string Unique transfer transaction id defined by merchant

Example response

{
  "unique_id" : "123456789abcdefg"
}

Errors

eZeeWallet API attempts to return appropriate HTTP status codes for every request and returns errors with HTTP status, human readable error message and machine parsable error code and description in JSON format

Code HTTP Status Message
401 400 Bad Request Parameters are missing or invalid
402 400 Bad Request Invalid credentials for source wallet account
403 400 Bad Request Transaction disallowed for source wallet account
404 400 Bad Request Merchant wallet is disabled
405 400 Bad Request Target wallet account not found
406 400 Bad Request Transaction disallowed for target wallet account
407 400 Bad Request Currency mismatch
408 400 Bad Request Transaction ID already processed
409 400 Bad Request Required top up amount is higher than the maximum deposit amount
410 400 Bad Request Transaction disallowed between wallets with different industry types
412 400 Bad Request Payouts for this account have been suspended
413 400 Bad Request One of the payout amounts is of an invalid format
414 400 Bad Request Insufficient balance in source wallet account to make a payout
415 400 Bad Request Exceeded threshold limit for payouts
416 400 Bad Request Record not found
417 400 Bad Request Could not approve a timed out credit payout request
418 400 Bad Request Could not approve a failed credit payout request
419 400 Bad Request Could not approve a declined credit payout request
420 400 Bad Request Credit payout request already approved
421 400 Bad Request Credit payout request already declined
422 400 Bad Request Merchant is not allowed to process transaction for this consumer\'s country
423 400 Bad Request Source wallet account not found
424 400 Bad Request One of the payout currencies mismatched to the currency of source wallets
425 400 Bad Request Payout currency mismatched to the currency of source wallets
426 400 Bad Request Target wallet currency is different than the currency of the payout
427 400 Bad Request Payout amount is in an invalid format
500 500 Internal Server Error Request Transfer failed due to internal error