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 :

• Buyer and seller will confirm the order/contract/PO on your platform.
• Your platform originates the escrow transaction with Tazapay.
• Buyer makes a payment, Tazapay notifies your platform of “money receipt”.
• Your platform updates the “payment status” on your dashboard.
• Your platform sends a payment release instruction once the seller completes the agreed milestone.
• Tazapay transfers funds to the seller after deducting your platform fee.
• Settlement between Tazapay and the platform is going to be gross-settlement in phases. Tazapay will transfer your fees after deducting Tazapay fees on a bi-weekly basis.

Net settlement will be built in due course.

Benefits of Tazapay Escrow Service

Marketplace without Tazapay Escrow

• Platform has no visibility into payments. Payments are off platform
• No payment protection for buyer & seller
• No option for buyers to pay with local payment methods & cards. Only wire transfers are available
• Wire transfers typically involve unfavourable exchange rates, additional fees & charges and processing delays

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

• Payment collection from buyer, deduction of platform fees and payouts to the seller
• Payment protection for buyer & seller
• Buyers have a choice host of local payment methods and cards in addition to the traditional bank transfer methods
• Transparency with respect to cost and speed of transfer

Key features

• End to end orchestration of multiple legs of payment : collect from buyer, hold in escrow, deduction of platform fee and release to seller
• Collect payments: Collect payments from customers in about 80+ countries. Supported payment methods:
  • Local bank transfers - SEPA transfers in EU, US ACH transfers, SG Fast transfer, GBP Local transfer
  • Wire transfers - Worldwide
  • Cards - Worldwide
• Fee collection: Monetise your business by making your platform a transactional platform and collect fees for your services.
• Payouts: Route payments to your recipients’ bank accounts programmatically
• Onboarding: Collect information through your own flow (or) using our hosted KYB screens (coming soon) and let Tazapay take care of the complex KYB verification and sanction screening requirements.

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.

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:

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:

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 :

• Native API: This is a pure back-end API interaction between your platform and Tazapay
• Hosted page API: When you make a call to a Tazapay hosted API, Tazapay will return a URL, to which the customer can be redirected

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:

• Primary contact email address
• Country
• Account type = Business (or) Individual.
• If Business, provide business name; if Individual, provide the first name and last name of the individual.

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:

• Primary contact email address
• Country
• Account type = Business (or) Individual.
• If Business, provide business name; if Individual, provide the first name and last name of the individual.

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:

• Create an escrow transaction based on the contract/PO created on your platform
• Originate a new payment request on behalf of your buyer. For buyers/clients, since their money is being held by Tazapay, for compliance & legal reasons they will have to create a Tazapay account and originate payment through a Tazapay hosted payment page.
• Verify your seller’s business
• Get escrow status
• Originate payouts to your seller’s bank account

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.

Response

create_user_data

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.

Response

txn_doc

release_docs

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.

Response

payment

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

Response

get_escrow_status

All Possible Statuses

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

Response

country_config

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

Response

invoice_currency

Errors

The API uses the following error codes:

HTTP Status Codes

Tazapay Internal Error Codes

generic

auth

session

user

escrow

payment

metadata