NAV Navbar
cURL

Version

API version 1.2.2

Documentation version 1.2.2

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

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://staging.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 unique_id parameter to the ListTransfers endpoint like so:

https://ezeewallet.com/api/transfers?unique_id=1234567890

{
  "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 not support any form of Forex. Per transfer transaction, currency usage is restricted: the requested currency must match the currency that is configured for the source wallet and the target wallet. For example, if a consumer has a USD wallet and a merchant has only a GBP wallet, a transfer is not possible, resulting in a "Currency mismatch" error for any currency in the API request. If a consumer and a merchant both have a USD wallet only, then an API request for any currency other than USD 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,
  "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 /transfers

Creates transfer, consumer to merchant wallet

Example response

{
  "transfer": {
    "unique_id": "random_unique_id",
    "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": {
    "unique_id": "random_unique_id",
    "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
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

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

ListTransfers

GET /transfers?unique_id=value

GET /transfers?transaction_id=value

GET /transfers?start_date=value&end_date=value

Example response

{
  "pagination": {
    "total_count": 1,
    "pages_count": 1,
    "per_page": 30,
    "page": "1"
  },
  "transfers": [
    {
      "unique_id": "f3a5870ab96f514f0e28983fb88a9c4eed2a366a",
      "transaction_id": "40",
      "amount": 10000,
      "currency": "USD",
      "status": "pending",
      "source_wallet_id": "dimitar.kostov@emerchantpay.com",
      "return_success_url": "http://example.com/success",
      "return_failure_url": "http://example.com/failure"
    }
  ]
}

Body params

Name Type requried Description
param_name string(255) yes unique_id, transaction_id or start_date and end_date

Response fields

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

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

Example response

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

Body params

Name Type Requried Description
payout_request PayoutRequest Yes Payout request object

Response fields

Name Type Description
payout SinglePayout 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.

Data Types

Transfer

Name Type Description
unique_id string Unique id defined by eZeeWallet for later use
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 status is pending async
return_failure_url string URL where the consumer must be redirected to deposit money if status is pending async
redirect_url string URL where the consumer must be redirected to deposit money if status is pending async

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

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

BillingAddress

Name Type Description
first_name string First name of the consumer
last_name string Last name of the consumer
address1 string First line of the address
city string City
zip_code string Zip code
country string Country

CreditCard

Name Type Description
holder string Name of the holder
number string First six and last four numbers on the card
expiration_month string Expiration month of the card
expiration_year string Expiration year of the card

Error

Name Type Description
code string machine parsable error code
message string human-readable message with 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 notifcation

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 unique id of the transaction with merchant name and generating a SHA1 Hash (Hex) of the string:

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

Example:

unique_id = 123456789abcdefg

merchant api_username = 0987654321xyz

signature -> 9ec1df9a7013f6a5b952b9d3f12d620475d37c86

Example response

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

NotificationEcho

Name Type Description
unique_id string Unique id defined by eZeeWallet for later use

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
407 400 Bad Request One of the payout currencies mismatched to the currency of source wallets
407 400 Bad Request Payout currency mismatched to the currency of source wallets
407 400 Bad Request Target wallet currency is different than the currency of the payout
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
413 400 Bad Request Payout amount is in 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
500 500 Internal Server Error Request Transfer failed due to internal error