EZPIN Vendors API Documentation

In this document you can find all requirements for EZPIN API to access products catalog and issue an order for digital gift card types.

Customers with the proper credentials can access EZPIN API endpoints using an access token (see Authentication).

Use HTTPS protocol for all requests.

Authentication

API endpoints are only accessible to customers who have credentials (a client ID and client secret) provided by EZPIN. Approved customers can access the various endpoint resources using an access token.

This access token grants access to the API for a specified amount of time. You pass the access token in the Authorization header of any subsequent requests to API endpoints.

Expected Behavior

The following are common requests to the API, along with expected results (see Status Codes and Error Messages for more information).

Status Code	Type	Response Format
HTTP 200	`Success`	`Related JSON Response`
HTTP 400	`Fail`	`An Error Message in detail key of a JSON Object along with a code describing detail for code handling`
HTTP 401	`Unauthorized`	`Usually if token signature get expired.`

Error code explanation

While using EZPin Vendor API you may face a HTTP 400 error which has a code inside JSON response. Following table could help you figure out the problem programmatically.

Code	Description
600	`Action not allowed`
601	`Barcode not found`
602	`Product not found`
603	`Card is not ready`
604	`Barcode format is wrong`
605	`Price is not permitted`
606	`Pending. In process`
607	`Activated before`
608	`Related store not found`
609	`Order is not ready`
610	`Insufficient balance`
611	`Cost calculation problem`
612	`Wrong product price`
613	`Pre order is not allowed`
614	`Not enough card is available`
615	`No access to API`
616	`Pin or store is required for this action`
617	`Pin or store is wrong for this action`
618	`Set order proccess faced a problem`
619	`Different currencies`
620	`Reserved`
621	`Digital rollback`
622	`SEND_ADDRESS_NEED`
623	`Type Error`
624	`Too many items to SMS`
625	`Too many items to Whatsapp`
626	`CSV or Text only`
627	`Duplicate card`
628	`Import card error`

Authentication NOTICE

Used retrieven token in header: Authorization: Bearer {token}

Base URL

All URLs referenced in the API documentation have the following base:

https://api.ezpaypin.com/vendors/v1/

This REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

API Endpoints

you can find endpoints as below.

Generate Token

An access token provides access to the EZpin API for a specified amount of time. When the access token expires, clients must obtain another one.

POST /auth/token/

Request

Parameter	Type	Position	#	Description
client_id	`string`	`Body`	`Required`	Client ID provided by EZpin
secret_key	`string`	`Body`	`Required`	Secret key provided by EZpin

Response

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfaWQiOj",
  "expire": 1579799052
}

Get Account Balance

Returns account balance of various currencies.

GET /balance/

Request

Parameter	Type	Position	#	Description

Response

[
  {
      "currency": {
          "id": 1,
          "country": "USA",
          "currency": "Dollars",
          "symbol": "$",
          "code": "USD"
      },
      "balance": 29961003.35
  },
  {
      "currency": {
          "id": 22,
          "country": "Canada",
          "currency": "Dollars",
          "symbol": "CAD$",
          "code": "CAD"
      },
      "balance": 231.85
  },
  {
      "currency": {
          "id": 38,
          "country": "Europe",
          "currency": "Euro",
          "symbol": "€",
          "code": "EUR"
      },
      "balance": 99770.33
  },
  {
      "currency": {
          "id": 123,
          "country": "United Kingdom",
          "currency": "Pounds",
          "symbol": "£",
          "code": "GBP"
      },
      "balance": 77.25
  }
]

Catalog List

Gets a list of all catalogs. When pre-order is true. you can create order when product out of stock or product is not enough. When the pre-order set is false, you order digital cards for immediate use at the point of sale. An immediate order is limited to a total of five digital cards.

GET /catalogs/

Request

Parameter	Type	Position	#	Description
limit	`integer`	`Query Param`	`Optional`	Number of items in list
offset	`integer`	`Query Param`	`Optional`	Offset number of list
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "count": 271,
  "next": "https://api.ezpaypin.com/vendors/v1/catalogs/?limit=10&offset=10",
  "previous": null,
  "results": [
        {
        "sku": 324,
        "title": "iTunes $400",
        "min_price": 400.0,
        "max_price": 400.0,
        "description": "",
        "currency": {
          "country": "America",
          "currency": "Dollars",
          "symbol": "$",
          "code": "USD"
        },
        "categories": [
          {
            "name": "iTunes US"
          }
        ],
        "pre_order": false,
        "regions": {
          "name": "Global",
          "code": "GLC"
        },
        "showing_price": {
        "id": 10612,
        "price": 10.0,
        "showing_currency": {
            "id": 132,
            "country": "United Arab Emirates",
            "currency": "Dirham",
            "symbol": "AED"
        },
        "image": "https://media.ezpaypin.com/media/products/images/2019/11/Image1_lFuTbNn.jpg"
    }
  ]
}

Catalog Range List

Gets a list of all range catalogs. When pre-order is true. you can create order when product out of stock or product is not enough. When the pre-order set is false, you order digital cards for immediate use at the point of sale. An immediate order is limited to a total of five digital cards.

GET /range_catalogs/

Request

Parameter	Type	Position	#	Description
limit	`integer`	`Query Param`	`Optional`	Number of items in list
offset	`integer`	`Query Param`	`Optional`	Offset number of list
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
    "count": 322,
    "next": "https://api.ezpaypin.com/vendors/v1/range_catalogs/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "sku": 1131,
            "upc": 659245710566,
            "title": "Amazon US",
            "price_min": 5.0,
            "price_max": 500.0,
            "price_fix": 0.0,
            "currency": {
                "id": 1,
                "country": "USA",
                "currency": "Dollars",
                "symbol": "$",
                "code": "USD"
            },
            "categories": [
                {
                    "name": "amazon USA"
                }
            ],
            "pre_order": false,
            "image": "http://media.ezpaypin.com/media/products/images/2019/11/Image7.jpg",
            "description": "",
            "regions": {
                "name": "Global",
                "code": "GLC"
            }
        }
    ]
}

Catalog Availability

Checks if enough cards are available for a specific product.

GET /catalogs/{product_sku}/availability/

Request

Parameter	Type	Position	#	Description
item_count	`integer`	`Query Param`	`Required`	Number of items
price	`float`	`Query Param`	`Required`	Product price
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Request

/catalogs/918/availability/?item_count=1&price=2.00

Response

{
    "availability": true,
    "detail": "This catalog is available."
}

Digital Card Order Create

You must include a valid access token in the Authorization header and a valid catalog SKU in the SKU body of the POST request. A successful POST returns the Order ID and created time.

POST /orders/

Request

Parameter	Type	Position	#	Description
sku	`integer`	`Body`	`Required`	Catalog SKU
quantity	`integer`	`Body`	`Required`	Item count
pre_order	`boolean`	`Body`	`Required`	To determine whether you want to pre order your request or not. The product must support pre order mood. if you pass true your cards will get ready in the future.
price	`float`	`Body`	`Required`	Item price
email	`string`	`Body`	`Optional`	The user email
store_id	`string`	`Body`	`Optional`	Vendor store_id that can be defined in user panel as "Sub-users Pin" in settings.
reference_code	`string(UUID)`	`Body`	`Required`	Refernce code. A unique UUID referece code must be included in request
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "order_id": 698,
  "email": null,
  "status": 1,
  "status_text": "accept",
  "created_time": "2020-01-23T14:30:08.749667",
  "reference_code": "0e3b04f1-26d9-43fe-b88e-2d73d24feab7"
  "product": {
        "sku": 20,
        "title": "Test Google 10$"
    },
    "count": 1,
    "unit_price": 9.0,
    "is_completed": true
}

status list: pending(0) , accept(1) , reject(-1)

Digital Card Order Details by Reference Code

You must include a valid access token in the Authorization header of each GET request. lets you retrieve a list of cards in an order using the Reference Code. A successful GET returns information about the cards in the order.

GET /orders/by_reference/{reference_code}/

Request

Parameter	Type	Position	#	Description
reference_code	`string(UUID)`	`Url`	`Required`	Reference Code
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "order_id": 698,
  "email": null,
  "status": 1,
  "status_text": "accept",
  "created_time": "2020-01-23T14:30:08.749667",
  "product": {
        "sku": 20,
        "title": "Test Google 10$"
    },
    "count": 1,
    "unit_price": 9.0,
    "is_completed": true
}

status list: pending(0) , accept(1) , reject(-1)

Digital Card Order Cards Info

You must include a valid access token in the Authorization header of each GET request. lets you retrieve a list of cards in an order using the Reference Code. A successful GET returns information about the cards in the order.

GET /orders/by_reference/{reference_code}/cards/

Request

Parameter	Type	Position	#	Description
reference_code	`string(UUID)`	`Url`	`Required`	Reference Code
limit	`integer`	`Query Param`	`Optional`	Number of items in list
offset	`integer`	`Query Param`	`Optional`	Offset number of list
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
        {
            "card_number": "9668-9438",
            "pin_code": null
        }
    ]
}

Digital Card Order History

You must include a valid access token in the Authorization header of each GET request. lets you retrieve a list of orders using specific filters. A successful GET returns information about the orders history.

GET /orders/

Request

Parameter	Type	Position	#	Description
start_date	`string (YYYY-MM-DDTHH:mm:ss)`	`Query Param`	`Required`	Report Start Date (Ex: 2020-01-03T04:00:00 is 12:00 AM in Dubai(GMT+4) 03 Jan 2020)
end_date	`string (YYYY-MM-DDTHH:mm:ss)`	`Query Param`	`Required`	Report End Date (Ex: 2020-01-07T15:00:00 is 11:00 AM in Dubai(GMT+4) 07 Jan 2020)
limit	`integer`	`Query Param`	`Optional`	Number of items in list
offset	`integer`	`Query Param`	`Optional`	Offset number of list
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
"count": 77,
"next": "https://api.ezpaypin.com/vendors/v1/orders/?end_date=2020-05-27T08%3A41%3A59.098734&limit=10&offset=10&start_date=2020-02-27T08%3A41%3A59.098734",
"previous": null,
"results": [
    {
        "order_id": 4718,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-02-27T08:41:59.098734",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 20,
            "title": "Test Google 10$"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 4719,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-02-27T08:42:56.789759",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 43,
            "title": "Test Spotify $10"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 5383,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-03T09:26:06.029767",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 407,
            "title": "Test Ea Acsess"
        },
        "count": 10,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 5385,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-03T09:29:52.019391",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 20,
            "title": "Test Google 10$"
        },
        "count": 10,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 5433,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-03T13:19:28.332683",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 407,
            "title": "Test Ea Acsess"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 5434,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-03T13:21:01.363127",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 20,
            "title": "Test Google 10$"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 5565,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-04T11:39:22.406431",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 20,
            "title": "Test Google 10$"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 5566,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-04T11:40:03.543281",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 43,
            "title": "Test Spotify $10"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 5569,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-04T11:46:26.390823",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 20,
            "title": "Test Google 10$"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    },
    {
        "order_id": 6278,
        "email": "[email protected]",
        "status": 1,
        "status_text": "accept",
        "created_time": "2020-03-08T13:48:36.087512",
        "reference_code": "9815bc48-b5f3-4aba-90d2-0420d4939863",
        "product": {
            "sku": 20,
            "title": "Test Google 10$"
        },
        "count": 1,
        "unit_price": 10.0,
        "is_completed": false
    }
]
}

Physical Card Check

Client can check physical card status use VAN16 barcode number on the back of physical card.

GET /cards/check/

Request

Parameter	Type	Position	#	Description
barcode	`integer`	`Query Param`	`Required`	Barcode Number Of Physical Card
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "barcode": "888462551206058120006239903648",
  "product": "ITunes US",
  "sku": 299,
  "status_text": "Activated",
  "status": 1,
  "allowed_prices": [
      10.0,
      15.0,
      20.0,
      25.0,
      50.0,
      100.0,
      200.0
  ],
  "activate_price": 10.0,
  "activate_time": "2019-11-20T13:24:26.862624",
  "currency": "USD"
}

status list: Pending(-1) , Activated(1) , Inactive(0)

Physical Card Activate

Client can activate card use van16 barcode number on the back of physical card. sku and price must retrieve from check API first. request will process within maximum 40 seconds and result will return to client.

POST /cards/activate/

Request

Parameter	Type	Position	#	Description
barcode	`integer`	`Url`	`Required`	Barcode Number Of Physical Card
sku	`integer`	`Body`	`Required`	SKU Of Product
price	`float`	`Body`	`Required`	Item price
store_id	`string`	`Body`	`Optional`	vendor store_id that can define in user panel.
reference_code	`string(UUID)`	`Body`	`Required`	Refernce code. A unique UUID referece code must be included in request
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "transaction_id": 50,
  "barcode": "799366084346058120008391049419",
  "product": "Playstation US PS4 $50",
  "reference_code": "0e3b04f1-26d9-43fe-b88e-2d73d24feab7",
  "status": -1,
  "status_text": "Pending",
  "currency": "USD",
  "created_time": "2020-02-03T13:27:12.250248"
}

status list: pending(-1) , activate(1) , failed(-2)

Physical Card Activation Status

Client can check physical card activation status use Reference Code of activation process.

GET /cards/by_reference/{reference_code}/

Request

Parameter	Type	Position	#	Description
reference_code	`integer`	`Url`	`Required`	Reference Code
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "transaction_id": 50,
  "barcode": "799366084346058120008391049419",
  "product": "Playstation US PS4 $50",
  "reference_code": "0e3b04f1-26d9-43fe-b88e-2d73d24feab7",
  "status": -1,
  "status_text": "Pending",
  "currency": "USD",
  "created_time": "2020-02-03T13:27:12.250248"
}

status list: pending(-1) , activate(1) , failed(-2)

Notification Url

You must include a valid access token in the Authorization header of each GET request. lets you retrieve a list of cards in an order using the Order ID. A successful GET returns information about the order.

GET /orders/notification_config/

Request

Parameter	Type	Position	#	Description

Response

{
   "endpoint": "https://example.com/",
   "confidential_key": "ikasd7823q4lmk132jk"
}

Notification

You must include a valid access token in the Authorization header of each POST request. Adjust this section if you want to be notified after the order has been accepted or rejected. This section contains two parameters, including endpoint, confidential_key.
Body received from EZPin would be in following format:

Request

{
  "order_id":1234,
  "status":1
}

STATUS_REJECT = -1
STATUS_READY_FOR_DOWNLOAD= 1

POST /orders/notification_config/

Request

Parameter	Type	Position	#	Description
endpoint	`string`	`Body`	`Required`	The URL that after change order status will report
confidential_key	`string`	`Body`	`Required`	The confidential key that you need to validation for your system
Authorization	`Bearer Token`	`Header`	`Required`	Token generated by API in previous section

Response

{
  "detail": "API setting added successfully"
}