NAV

Getting Started

Welcome to the Tazapay API documentation!

The Tazapay escrow API allows you as a marketplace partner to create accounts, share information about an underlying contact between two parties as well as to collect, hold and release payments between multiple parties.

For each transaction, the Marketplace creates an underlying escrow agreement between the buyer and seller. This agreement becomes the legal basis for collecting, holding and releasing money.

We are constantly working on our API product to make it easier for our partners to integrate with us. If you have any feedback or suggestions, please share them with us at techops@tazapay.com

Why To Use Tazapay Escrow Service

Understanding funds flow

Collect payments from buyers, hold it until the seller/service provider fulfills their obligations before releasing the payment to them. It offers protection to both buyers and sellers by giving equal control over created payments for awarded contracts/projects.

Control how funds flow :

Net settlement will be built in due course.

Benefits of Tazapay Escrow Service

Marketplace without Tazapay Escrow

Platform without Tazapay Escrow

Marketplace with Tazapay Escrow Platform Orchestrates The End to End Payment Flow Including Collection of Platform Fee

Platform without Tazapay Escrow

Key features

Authentication

To start using our APIs, you will require certain credentials that we will use to identify and authorise the use of 'Tazapay APIs'.

Tazapay uses API keys to authenticate requests. Once a marketplace has completed their onboarding process with Tazapay, Tazapay issues an API key & secret to a marketplace.

How to get your credentials?

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

Name Description
API-Key Will be used to identify you on consuming the API
API-Secret Will need to generate the authorisation token which is used to access restricted resources

Signature Calculation


  to_sign = upper_case_http_method + endpoint_url_path + Salt + Timestamp + API-Key + API-Secret
  signature = Base64(HmacSHA256(to_sign, API-Secret))

Signature calculation snippet in Python:


# Sample python program to call Tazapay sandbox API

import hashlib
import base64
import json
import requests
from datetime import datetime
import calendar
from random import *
import hmac

access_key = 'your-access-key'
secret_key = 'your-secret-key'
salt = 'Tif6r2ZqVn'

http_method = 'POST' # upper case
base_url = 'https://api-sandbox.tazapay.com'
path = '/v1/user' # This can hold any value of the supported API.

# Current Unix time.
d = datetime.utcnow()
timestamp = calendar.timegm(d.utctimetuple())

# generate signature
to_sign = http_method + path + salt + str(timestamp) + access_key + secret_key
h = hmac.new(bytes(secret_key, 'utf-8'), bytes(to_sign, 'utf-8'), hashlib.sha256)
signature = base64.urlsafe_b64encode(str.encode(h.hexdigest()))

headers = {
    'accesskey': access_key,
    'signature': signature,
    'salt': salt,
    'timestamp': str(timestamp)
}

payload = {
    "email": "support@tazapay.com",
    "country": "Singapore",
    "ind_bus_type": "Business",
    "business_name":"business name"
}

response = requests.post(url=base_url+path, json=payload, headers=headers)
print(json.loads(response.content.decode('utf-8')))

Calculate the signature as shown below

signature = BASE64 ( HMAC-SHA256 ( upper_case_http_method + endpoint_url_path + Salt + Timestamp + API-Key + API-Secret) + API-Secret)

You will need the following to calculate the signature:

Name Description
upper_case_http_method API method verb in uppercase (GET, POST etc)
endpoint_url_path The complete URL of the API you are calling
API-Key Provided to you
API-Secret Provided to you
Salt Random value
Timestamp Current timestamp

All API calls need authentication using a base64 encoded hash signature, using the HMAC SHA-256 algorithm.

API Headers

For each and every API call, you need to include the following in the header section:

Key Value
accesskey same key used in the signature computation
salt salt used in signature computation
signature signature computed above
timestamp timestamp used in the signature computation

Tazapay Endpoints

All Tazapay endpoints are located on a single domain. The Tazapay API is served over https and unencrypted http connections are not supported.

Types of API

Tazapay has 2 types of APIs :

API Notifications

In phase 1, in order to check on transactions, Tazapay will be providing ‘Get APIs’ which you need to poll. Webhooks will be added in the subsequent phases.

Create and connect your customer accounts

Create and Connect Your Seller/Supplier’s Account

A supplier’s account will be a completely native account to the marketplace and the seller/ supplier will not have to access the Tazapay account. You can create Tazapay accounts for your sellers/suppliers using the“Users API” anytime after they onboard on to your platform.

The account that you create via the user’s API will be linked to your platform account and you will have authorization to transact on behalf of the merchant using Tazapay’s APIs. You can create a new connected account by submitting 4 key pieces of information:

By creating the account via the "Users API", you implicitly indicate the user's acceptance of Tazapay’s terms & conditions. Also, you consent to the terms covering the tri-party relationship between Tazapay, your business and the party on whose behalf you are opening the account, and in doing so Tazapay is authorised to take action on the connected account according to your instructions.

Create and Connect Your Buyer/Client’s Account

A buyer/client account is a non-native account and the buyer/client will have to set a password while accessing Tazapay for the first time. You can create a Tazapay account for your buyer/client when they sign up on your platform or when they are about to initiate an escrow payment.

To create and connect your buyer/client’s account, you need to follow the steps given below:

Step 1: You can create a new connected account by submitting 4 key pieces of information:

Step 2: The buyer/client will have to set a password with Tazapay while using the account for the first time to make a payment.

By creating the account via the "Users API", you implicitly indicate the user's acceptance of Tazapay’s terms & conditions. Also, you consent to the terms covering the tri-party relationship between Tazapay, your business and the party on whose behalf you are opening the account, and in doing so Tazapay is authorised to take action on the connected account according to your instructions.

Transact On Behalf Of Your Customers

Using the Tazapay Account-id of the account connected to your platform, you will be able to transact on behalf of the customer in-line with the authorisation-level provided using the tazapay regular endpoints.

For example, you will be able to:

To call the end-point on behalf of the customer, simply specify the account-ID when making a request.

User APIs

Create User

Request For Individual:

{
    "email": "shrikar+729@tazapay.com",
    "country": "IN",
    "contact_code": "+91",
    "contact_number": "",
    "ind_bus_type": "Individual",
    "first_name": "Shrikar",
    "last_name": "vaitala"
}

Request For Business:

{
    "email": "shrikar+729@tazapay.com",
    "country": "IN",
    "contact_code": "+91",
    "contact_number": "",
    "ind_bus_type": "Business",
    "business_name":"business name"
}

Response:

{
    "status": "success",
    "message": "Partner user signup successful",
    "data": {
        "account_id": "afcd6ed3-8c48-471d-8f6c-beee2f504274",
        "customer_id": "1373413"
    }
}

HTTP Request

POST /v1/user

Body Parameters

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

Parameter Description
email
required
string User's email address
first_name
required if ind_bus_type is Individual
string User's first name
last_name
required if ind_bus_type is Individual
string User's last namee
contact_code
optional
string Mobile country code of the user
contact_number
optional
string User's mobile number
country
required
string User's country, in ISO 3166 standard alpha-2 code. eg: SG, IN, US, etc.
The complete list can be fetched from Country List
ind_bus_type
required
string User's entity type. Can be: Business or Individual
business_name
required, if ind_bus_type is Business
string Name of the business
partners_customer_id
optional
string User's ID or reference number on your platform

Response

Parameter Description
message string Success or failure messsage.
status string Success of failure status code.
data data Create User Data Object. Please check Create User Data Object

create_user_data

Parameter Description
account_id string Account ID of the newly created user
customer_id string Customer reference ID as shared by the partner

Escrow APIs

Create Escrow

Request Body:

{
   "txn_type" : "goods", // optional
   "release_mechanism" : "tazapay", // optional
   "reference_id": "my_ref_val" // optional
   "initiated_by" : "tp_account_id",
   "buyer_id" : "tp_account_id", 
   "seller_id" : "tp_account_id",
   "txn_description" : "",
   "txn_docs":[ // optional
      {
         "type" : "Proforma Invoice",
         "url" : "https://direct.download.link"
      },
      {
         "type" : "Others",
         "name" : "OTH - File", // req: if type = Others
         "url" : "https://direct.download.link"
      }
   ],
   "is_milestone": false, // optional
   "attributes": {}, // optional
   "invoice_currency" : "USD",
   "invoice_amount": 100,
   "fee_tier" : "standard", // optional
   "fee_paid_by" : "seller", // optional
   "fee_percentage": 100 // optional [req: if fee_paid_by != ""]
   "release_docs": [ // optional
      {
         "type": "Proof of Work",
         "url": "https://direct.download.link" // optional
      },
      {
         "type" : "Others",
         "name" : "OTH - File", // req: if type = Others
         "url" : "https://direct.download.link" // optional
      }
   ]
}

Response:

{
   "txn_no": "7844",
   "state": "Awaiting_Payment",
   "sub_state": "na",
   "txn_type": "goods",
   "invoice_currency": "USD",
   "invoice_amount": 1000,
   "fee_tier": "standard",
   "fee_paid_by": "buyer",
   "fee_tier_percentage": 1.8,
   "fee_amount": 18,
   "collect_amount": 1018,
   "disburse_amount": 1000,
}

// Note: All the amount above is in invoice currency format

HTTP Request

POST /v1/escrow/

Body Parameters

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

Parameter Description
txn_type
optional
Enum Type of transaction. Can be: goods, service, If empty; contracted MP level value will get applied
release_mechanism
optional
Enum Party responsible for verifying the release documents. Can be: marketplace, tazapay, If empty; contracted MP level value will get applied
reference_id
optional
string Marketplace identifier value. Example, marketplace escrow number, auto generated value, etc.
initiated_by
required
string Tazapay account UUID of the party who has initiated the transaction
buyer_id
required
string Tazapay account UUID of the buyer
seller_id
required
string Tazapay account UUID of the seller
txn_description
required
string A short description of the underlying transaction or trade
txn_docs
optional
[] txn_doc Supporting documents for transaction.
Please check txn_doc
is_milestone
optional
bool Default to false
attributes
optional
json Tunnelled add-on fields
invoice_currency
required
string Invoice currency, ISO 4217 standard specifies three-letter ("Alpha-3") codes. e.g. USD
invoice_amount
required
float Invoice amount
fee_tier
optional
string Applicable fee tier. If empty, contracted MP level "standard" tier property will be used
fee_paid_by
optional
string Party that bears the fee for the transaction. Can be: buyer or seller. If empty; contracted MP level value will get applied
fee_percentage
optional
string If the fee is to be split between the buyer and seller, pass the percentage of split to be paid by the entity passed above. E.g. if fee_paid_by is "buyer" and fee_percentage is 40%, 60% of the remaining fee will need to be paid by the seller.
release_docs
optional
[] release_docs The list of documents to be provided as completion proof for the verification.
Please check release_docs

Response

Parameter Description
txn_no string This the 4 digit escrow transcation number

txn_doc

Parameter Description
type
required
string one of Proforma Invoice , PO, Contract, Order Form, Others
name
optional
string required; if type=others
url
required
string Direct download link

release_docs

Parameter Description
type
required
string one of Bill of lading, Commercial Invoice, Packing List, Certificate of Origin, Airway Bill, Inspection Certificate, Others
name
optional
string required; if type=others
url
required
string Direct download link

Create Payment

Request Body:

{
    "txn_no": "1234",
    "complete_url": "",
    "error_url": "",
    "callback_url": ""
}

Response:

{
    "status": "success",
    "message": "payment session created successfully",
    "data": {
        "redirect_url": "https://sandbox.tazapay.com/marketplace/paymentdetails?token=dff96ecd-0485-41e4-8a75-b5f3b368fb6d"
    }
}

HTTP Request

POST '/v1/session/payment'

Pre-Requisite: Need to have created an escrow agreement prior to creating payment.

Body Parameters

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

Parameter Description
txn_no
required
String Escrow transcation number received from create_escrow API response
complete_url
required
string URL where the customer is redirected after a successful payment
error_url
required
string URL where the customer is redirected in case of an error in the payment
callback_url
optional
string URL to notify your server about the Async payment

Response

Parameter Description
status string status of the API.
message string message for the response.
data data Please check payment

payment

Parameter Description
redirect_url string URL to redirect the users to the Tazapay hosted page

Get Escrow Status

Response:

{
    "status": "success",
    "data": {
        "txn_no": "1234",
        "state": "Basic",
        "sub_state": "Basic",
        "invoice_currency": "INR",
        "invoice_amount": 10
    }
}

HTTP Request

GET /v1/escrow/{txn_no}

Query Parameters

Parameter Type Value
txn_no
required
integer 3456

Response

Parameter Description
status string success or failure.
data data Get Status Response Data Object. get_escrow_status

get_escrow_status

Parameter Description
txn_no string The txn_no for the request made.
state string The state / status of escrow
sub_state string the sub state / status of escrow.
invoice_currency string the invoice currency of payment made for this escrow.
invoice_amount float64 / numeric invoice amount i.e. amount paid for this escrow.

All Possible Statuses

Type Name Description
state Awaiting_Payment Awaiting Payment from Buyer
subState Payment_Initiated Buyer selected the payment method
subState Payment_Failed Payment failed
state Payment_Recieved Received Payment from Buyer
state Payment_NoResponse Not received Payment from Buyer before due date
state Release_Authorized Buyer or Marketplace requested to release the payment to seller
subState Payout_Processing Tazapay started processing the payment to seller
subState Payout_Failed Payment to seller failed
state Payout_Completed Seller received the payment
subState Generic Generic status if State does not have any specific substate

Metadata API

Country Config

Response:

{
    "status": "success",
    "data": {
        "market_type": "buyer",
        "buyer_countries": null, // or []string
        "seller_countries": [
            "AE",
            "AR",
            "AT",
            "AU",
            "BD"
        ]
    }
}

HTTP Request

GET /v1/escrow/metadata/countryconfig?country=SG

Query Parameters

Parameter Type Value
country string ISO 3166 standard alpha-2 code. eg: SG, IN, US, etc.

Response

Parameter Description
status string returns the status of the API, "success" (or) "error_response"
data data Data object. Please check country_config

country_config

Parameter Description
market_type string Describes about the market type for this country, possible values : buyer, seller, both
buyer_countries []string Gives a list of buyer countries.
seller_countries []string Gives a list of seller countries.

If the txn initiator is a buyer; use seller_countries object to list the counter party country, vice-versa.

Invoice Currency

Response:

{
    "status": "success",
    "data": {
        "currencies": [
            "USD",
            "SGD"
        ]
    }
}

HTTP Request

GET /v1/escrow/metadata/invoicecurrency?buyer_country=SG&seller_country=IN

Query Parameters

Parameter Type Value
buyer_country string ISO 3166 standard alpha-2 code. eg: SG, IN, US, etc.
seller_country string ISO 3166 standard alpha-2 code. eg: SG, IN, US, etc.

Response

Parameter Description
status string returns the status of the API, "success" (or) "error_response"
data data Data object. Please check invoice_currency

invoice_currency

Parameter Description
currencies []string Gives a list of supported invoice currency for the escrow txn

Errors

The API uses the following error codes:

HTTP Status Codes

Http Status Code Meaning
400 Bad Request : Your request is invalid
401 Unauthorized : Your API key is wrong
403 Forbidden : The resource requested is not authorized
404 Not Found : The specified resource could not be found
405 Method Not Allowed : You tried to access with an invalid method
406 Not Acceptable : You requested a format that isn't json
410 Gone : The requested resource has been removed from our servers
429 Too Many Requests : You're requesting too many resources! Slow down!
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

Tazapay Internal Error Codes

generic

Error Code Meaning
1000 Failure on decoding the json request provided by the client
1001 One of the queries for this operation has failed
1002 Something went wrong with this API
1003 Invalid parameter in the URL path.
Example : /xyz/my_value/abc Here my_value is invalid
1004 Invalid parameter in the URL path.
Example : /xyz/&sort=my_value/abc Here my_value is invalid
1005 The resource which you are trying to retrieve is not present

auth

Error Code Meaning
1100 Missing authentication header
1101 Invalid access key
1102 Unauthenticated api call

session

Error Code Meaning
1200 Invalid session
1201 Session expired

user

Error Code Description
1300 User email already exists but other fields are not synced to process the transaction
1301 Failed to create user. please try again
1302 Please provide the email address
1303 Please provide first_name as account type is individual
1304 Please provide last_name as account type is individual
1305 Country is mandatory for account creation
1306 Account type is mandatory for account creation
1307 business_name is mandatory as account type is business
1308 Please provide the password
1309 Failed to set user password
1310 Failed to update email verified as true
1311 Failed to sign into the system

escrow

Error Code Description
1400 Field is required
1401 Value must be either goods or service
1402 Field is required and must be a valid UUID
1403 Alternate field is required or must be a valid UUID
1404 Field is required and must be a valid email address
1405 Field is required and must have ISO 3166-1 alpha-2 country code, Example: IN, SG
1406 Field is required and must have ISO 4217 alpha-3 currency code, Example: IND USA
1407 Field is required and value must be greater than 0
1408 Value should be either buyer or seller
1409 Value must be between 0 and 100
1410 Alternate field is required or should have a dependent data
1411 Please contact our support team to configure the defaults
1412 User not found
1413 Invoice currency is not supported at this moment
1414 Please configure the default value or consider to pass a valid data in request
1415 Invoice amount should be less than %v USD (dynamic value)
1416 Invoice amount should be less than %v USD equivalent (dynamic value)
1417 Country or invoice currency is not supported at this moment
1418 Country or invoice currency is not supported at this moment
1419 Field is required and value should be either individual or business
1420 Counter party details not found

payment

Error Code Description
1500 Error fetching escrow_id from database for corresponding txn_no
1501 Error saving payment session in database
1502 Field is required
1503 Should be between 0 and 100

metadata

Error Code Description
1600 Country is not supported at this moment
1601 Currency is not supported at this moment
1602 Amount should be greater than 0
1603 Amount should be less than %v USD (dynamic value)
1604 Amount should be less than %v USD equivalent (dynamic value)