Overview

You can make use of the following Disbursement REST APIs during a payout scenario. This section explains about all RESTful operations including their functional behaviours, request and response parameters.

APIs presented here are only for happy flow without considering the payment exception cases. We shall publish the error codes soon.

Operation: Create a Payout

This operation enables you to create a transfer.

Functional Behaviour

POST	`/optima/corporates/{corpID}/companies/{companyID}/ programs/{programID}/disbursements/`

Input Parameters

Path Parameters	Description
corpID	A unique corporate ID assigned to the requester’s system
companyID	A unique company ID assigned to the requester’s system
programID	A unique program ID assigned to the requester’s system
Header Parameters	Description
Authorization	Value is "bearer token". Zeta will share this token with the requester.
Body Parameters	Description
requestID	Transfer Request ID This is generated by the requester and should be unique in the requester's system. The response is idempotent on this combination.
type	User account type. We shall support “to_bank_account”, “to_cloud_card” in future.
amount	Value is in paises. Possible values supported for currencies is “INR” for now.
beneficiary	Information of the beneficiary for whom payment transfer is requested. id: A unique beneficiary ID in the requester’s system name: Name of the user to which transfer needs to be initiated email: Email address of the user to which transfer needs to be initiated phoneNumber: Phone number of the user to which transfer needs to be initiated pan: PAN number of the user aadhar: Aadhar number of the user
description (optional)	Custom description that you wish to populate in the response payload
scheduledAt (optional)	Custom field that you wish to populate in the response payload. Supported value is "now".
attributes (optional)	Custom attribute that you wish to populate in the response payload

Request Header

{
	"Authorization": "Bearer nknkdhdj444474848jfnmccvnmADDFFF"
}

Request Body

{
	"requestID": "requestId_hello_12317",
	"type": "to_wallet",
	"amount":{
		"value": 10000,
		"currency": "INR"
	},
	"beneficiary": {
		"id": "Dir-13",
		"name":"Anthony D'souza",
		"email":"ds@zeta.in",
		"phoneNumber": "phone number of the user",
		"pan": "PAN of the user",
		"aadhar":"aadhar of the user"
	},
	"description": "test payout",
	"scheduledAt": "now",
	"attributes": {
		"age1": 10
	}
}

Output Parameters

Parameters	Description
requestID	Requester ID same as in request payload
status	“SUCCESS” or “PENDING” or “FAILED” or "MOVED_TO_ESCROW"

Response Sample

{
    "id": 35,
    "requestID": "requestId_hello_12317",
    "type": "to_wallet",
    "corpID": 3171,
    "companyID": 9443,
    "programID": 16592,
    "amount": {
        "currency": "INR",
        "amount": 10000
    },
    "employeeID": 2288426,
    "description": "test payout",
    "attributes": {
        "age": "10"
    },
    "status": "SUCCESS",
    "scheduledAt": 1516559610000,
    "createdAt": 1516559609000,
    "updatedAt": 1516559613000
}

Payout Status Codes

The following payout status codes are shown to the corporate side post Zeta authorization.

Payout Status	Description
SUCCESS	Beneficiary has received the transfer
PENDING	Transfer to beneficiary is pending and need to be retried by the requester with the same requestID to get the updated status
FAILED	Transfer to beneficiary failed. This could be due to low balance in the requester's funding account.
MOVED_TO_ESCROW	Transfer successful, waiting for beneficiary to signup on zeta.

To resolve any payout related issues, you may need to share requestID with Zeta.

Operation: Check a Beneficiary or User Existence

This operation enables you to check the status of the valid consumer account if the user exists in the Zeta.

Functional Behaviour

GET	`/zeta/hasUser?identityType=[PHONE_NUMBER/EMAIL]& identity={phone no}or{emailID}`

Input Parameters

Query Parameters	Description
identityType	User type supported as "PHONE_NUMBER" or "EMAIL".
identity	Phone number or email address of the user or beneficiary
Header Parameters	Description
Authorization	Value is "bearer token". Zeta will share this token with the requester.

Request Header

{
	"Authorization": "Bearer nknkdhdj444474848jfnmccvnmADDFFF"
}

Output Parameters

Parameters	Description
userExists	"true" or "false"

Response Sample

{
 "userExists": true // [false],
}

Overview

Learn and test Zeta Disbursement APIs in an interactive Zeta API console. To get started, contact Zeta to register and get access to the Zeta API endpoints.

Request for Developer Access

{ "swagger": "2.0", "host": "api.stage.zeta.in", "basePath": "/", "tags": [ { "name": "Disbursement APIs", "description": "Delivering enterprise payout solutions" } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/optima/corporates/{corpId}/companies/{compId}/programs/{programId}/disbursements": { "post": { "tags": [ "Disbursement APIs" ], "summary": "Create a Payout", "operationId": "OptimaCorporatesCompaniesProgramsProgramIdDisbursementsByCorpIdAndCompIdPost", "produces": [ "application/json" ], "parameters": [ { "name": "Body", "in": "body", "required": true, "description": "", "schema": { "$ref": "#/definitions/DisbursementRequest" } }, { "name": "Authorization", "in": "header", "required": true, "type": "string", "description": "A bearer token shared by Zeta" }, { "name": "corpId", "in": "path", "required": true, "type": "string", "description": "A unique corporate identifier assigned to the client" }, { "name": "compId", "in": "path", "required": true, "type": "string", "description": "A unique company identifier assigned to the client" }, { "name": "programId", "in": "path", "required": true, "type": "string", "description": "A unique program identifier assigned to the client" } ], "responses": { "200": { "description": "Successful transaction shows SUCCESS or PENDING or FAILED or MOVED_TO_ESCROW post Zeta authorization" } }, "x-unitTests": [], "x-operation-settings": { "CollectParameters": false, "AllowDynamicQueryParameters": false, "AllowDynamicFormParameters": false, "IsMultiContentStreaming": false } } }, "/zeta/hasUser": { "get": { "tags": [ "Disbursement APIs" ], "summary": "Check a Beneficiary or User Existence", "operationId": "ZetaHasUserGet", "produces": [ "application/json" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "type": "string", "description": "A bearer token shared by Zeta" }, { "name": "identityType", "in": "query", "required": true, "type": "string", "description": "PHONE_NUMBER or EMAIL" }, { "name": "identity", "in": "query", "required": true, "type": "string", "description": "Phone number or email of the user" } ], "responses": { "200": { "description": "Successful transaction displays TRUE or FALSE post Zeta authorization" } }, "x-unitTests": [ { "request": { "method": "GET", "uri": "/zeta/hasUser?identity_type=EMAIL&identity=test@zeta.in" }, "expectedResponse": { "x-allowExtraHeaders": true, "x-bodyMatchMode": "NONE", "x-arrayOrderedMatching": false, "x-arrayCheckCount": false, "x-matchResponseSchema": true, "headers": {} }, "x-testShouldPass": true, "x-testEnabled": true, "x-testName": "hasUser" } ], "x-operation-settings": { "CollectParameters": false, "AllowDynamicQueryParameters": false, "AllowDynamicFormParameters": false, "IsMultiContentStreaming": false } } } }, "definitions": { "DisbursementRequest": { "title": "disbursementRequest", "example": { "requestID": "requestId-test-4-9", "type": "to_wallet", "value": { "amount": in paise, "currency": "INR" }, "beneficiary": { "id": "beneficiary ID", "name": "beneficiary name", "email": "beneficiary email", "phoneNumber": "beneficiary phone number", "pan": "beneficiary pan number", "aadhar": "beneficiary aadhar number" }, "description": "test payout", "scheduledAt": "now", "attributes": { "age": 10 } }, "type": "object", "properties": { "requestID": { "description": "", "example": "requestId-test-4-9", "type": "string" }, "type": { "description": "", "example": "to_wallet", "type": "string" }, "value": { "$ref": "#/definitions/Value" }, "beneficiary": { "$ref": "#/definitions/Beneficiary" }, "description": { "description": "", "example": "test payout", "type": "string" }, "scheduledAt": { "description": "", "example": "now", "type": "string" }, "attributes": { "$ref": "#/definitions/Attributes" } }, "required": [ "requestID", "type", "value", "beneficiary", "description", "scheduledAt", "attributes" ] }, "Value": { "title": "Value", "example": { "amount": 10000, "currency": "INR" }, "type": "object", "properties": { "amount": { "description": "", "example": 10000, "type": "integer", "format": "int32" }, "currency": { "description": "", "example": "INR", "type": "string" } }, "required": [ "amount", "currency" ] }, "Beneficiary": { "title": "Beneficiary", "example": { "id": "beneficiary ID", "name": "beneficiary name", "email": "", "phoneNumber": "beneficiary phone number", "pan": "beneficiary name PAN number", "aadhar": "beneficiary aadhar number" }, "type": "object", "properties": { "id": { "description": "", "example": "test-13", "type": "string" }, "name": { "description": "", "example": "Virat Kohli", "type": "string" }, "email": { "description": "", "type": "string" }, "phoneNumber": { "description": "", "example": "9999999999", "type": "string" }, "pan": { "description": "", "example": "IPTPT88N87", "type": "string" }, "aadhar": { "description": "", "type": "string" } }, "required": [ "id", "name", "email", "phoneNumber", "pan", "aadhar" ] }, "Attributes": { "title": "Attributes", "example": { "age": 10 }, "type": "object", "properties": { "age": { "description": "", "example": 10, "type": "integer", "format": "int32" } }, "required": [ "age" ] } } }

On this page:

API References

Page tree

Overview

Operation: Create a Payout

Functional Behaviour

Input Parameters

Output Parameters

Payout Status Codes

Operation: Check a Beneficiary or User Existence

Functional Behaviour

Input Parameters

Output Parameters

Overview