Unknown macro: {hivestonebreadcrumb}
Page tree
Skip to end of metadata
Go to start of metadata

Overview

This section explains the RESTful API operations including their request and response parameters. You can use these APIs to configure payment scenario. 

Payment exceptions occur when an API operation fails to process a request payload. See Error codes to know more about exception response codes.

API endpoint URL

Zeta provides a fully-functional UAT environment that allows you to safely experiment with the Pay with PayZapp services before going live. It is a replica of the production environment, where you can interact with the Pay with PayZapp APIs to understand the platform and ecosystem. 

UAT API endpoint URL : https://api.tachyon.hdfcbank.com/gwajax/bifrost/

Operation: Create a source

Source is an instrument like card, phone number, or wallet using which the user pays a merchant. By creating a source, the user will save the details of his/her payment instrument in with the merchant. Saving the source is a convenience to the users because they need not enter the details of the instrument every time they pay the merchant.

This operation enables you to associate PayZapp as a payment mode with a merchant.

Functional behaviour

POST

/v2.0/payzapp/sources

Input parameters

ParametersDescription

requestId

Transaction Request ID
This is generated by the requester. Request ID is globally unique and it ensures that duplicate transactions are rejected.

"requestId" Naming Convention

Take care of the following to define requestId:
Characters allowed: a-z, A-Z, 0-9, -
Max size allowed: 60 characters.

successUrl

Merchant’s URL to which the payment gateway will redirect on successful transaction authorization.

failureUrl

Merchant’s URL to which the payment gateway will redirect on failed transaction authorization.


Request Header
{
 "apiKey": <api_key>
 "Content-Type" : "application/json"
}
Request Body
{
    "requestId": "req-spar-vbdjkahffoasdh874627wqufid",
    "successUrl": "htttps://merchant-successUrl.com",
    "failureUrl": "htttps://merchant-failureUrl.com"
}

Output parameters

ParametersDescription

requestId

Same request ID as sent in the request payload is returned.

Example: req-spar-vbdjkahffoasdh874627wqufid

sourceId

Unique identifier for the saved payment source.

Example: src_wqe47hxfjksor89y4

state

State of the payment source - whether active or inactive. Transaction cannot be initiated with inactive source.

Examples: ACTIVE, INACTIVE

authenticationDataThe JWT authentication token. You can use this token to validate the authenticity of the source ID while creating a transaction.

redirectUserTo

The URL where the merchant will redirect the user to complete user authentication

Example: https://pay-gw.preprod.zeta.in/ifi/163030/sendChallenge?q=txn_c60f3d98-21b8-41d0-9c03-09cb7da6527f


Response
{
    "requestId": "req-spar-jhchgvbdjkahffoasdh874627wqjgufid",
    "sourceType": "UNIQUE_ID",
    "state": "INACTIVE",
    "sourceId": "src_e9571fb6-49ea-43eb-9ad6-7d42e6587da5",
    "redirectUserTo": "https://bifrost.hdfc-beta.zetaapps.in/v2.0/tenants/13/sources/initiate?p=src_e9571fb6-49ea-43eb-9ad6-7d42e6587da5",
    "authenticationData": null
}

Response: 201 HTTP code

Operation: Get source details

This operation enables you to retrieve the source details.

Functional behaviour

GET

/v2.0/payzapp/sources/{source_id}

Input parameters

ParametersDescription

apiKey

apiKey will be shared by Zeta with requester during the on-boarding process.

Request Header
{
	"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
}

Output parameters

ParametersDescription

sourceId

This is the unique identifier of the saved payment source. You can use this parameter to allow the users to select a saved source for completing a transaction.

sourceType

This is the type of payment instrument that is saved as source.

Example: MERCHANT_WALLET, CARD, PHONE_NUMBER, EMAIL_ID, VOUCHER_BASED_TOTP, VOUCHER_BASED_EMV_CARD

paymentAccounts

If a bank is holding the details of an account but dos not have the ability to authenticate a transaction, but relies on the issuer bank via an Authorization Gateway), that's called a payment account.

Examples of a payment account which can be used in payment transactions:

  • Debit card in a wallet (like a Visa debit card offered by Citibank)

  • A savings account

  • A UPI handle to which you can debit

typeThis indicates the type of payment account.

paymentAccountId

This is the unique identifier of the payment account.

accountBalancesBalances in various accounts that the user has with Zeta. This is applicable and populated only if the source points to a Zeta hosted account.


Response
{
  "sourceId" : "src_ihfihd-04803-cjbd",
  "sourceType" : "UNIQUE_ID",
  "state": "ACTIVE",
  "paymentAccounts" : [
      {
        "type" : "PG_CARD",
        "id" : "02809789-ed5c-4f5e-88ff-80b8657a9139",
        "payload" : {
          "cardNumber" : "872636-xxxxxx-3679",
        }
      },
      {
        "type" : "PG_UPI",
        "id" : "2df52e5f-abd0-4996-ac6d-1cd2b058f1bc",
        "payload" : {
          "virtualAddress" : "test.user@ybl"  
        }
      },
      {
        "type" : "PG_NB",
        "id" : "31790eeb-9110-4435-b592-671249566860",
        "payload" : {
          "nbBank" : "ICICI Bank"
        }
      },
     {
        "type" : "PG_NB",
        "id" : "346fb18b-3746-43f0-91d5-e76e4ae496f6",
        "payload" : {
          "nbBank" : "AXIS Bank"
        }
      },
      {
        "type" : "PREPAID_CARD",
        "id" : "354f4665-3814-42f0-b9e7-574c9b652c8e",
        "payload" : {},         
        "amount": {
            "currency": "INR",
            "value": "20.00"
        }
      }
    ]
}


Operation: Create a transaction

This operation enables you to create a transaction using phone number or card.

Functional behaviour

POST

/v2.0/payzapp/transactions

Input Parameters

ParametersDescription

requestId

Transaction Request ID
This is generated by the requester. Transaction request ID is globally unique and it ensures that duplicate transactions are rejected.

"requestId" Naming Convention

Take care of the following to define requestId:
Characters allowed: a-z, A-Z, 0-9, -
Max size allowed: 60 characters.

merchantInfo

The following information about the merchant for whom the payment is requested.

  • AID: Acquirer ID (Unique identifier of the merchant's acquirer)

  • MID: Merchant ID (Unique identifier of the merchant)

  • TID: Terminal ID (Unique identifier of the merchant terminal)

amount

Transaction value with currency.
attributesSpecific tag used by the merchant for sharing any useful information as per their use case.
authenticationDataThe JWT authentication token returned when you created the source. You can validate the authenticity of the source ID using this token.

sourceId

Unique identifier for the saved payment source.

successUrl

Merchant’s URL to which the payment gateway will redirect on successful transaction authorization.

failureUrl

Merchant’s URL to which the payment gateway will redirect on failed transaction authorization.

validUntilRepresents the time in milliseconds during which the current request ID cannot be repeated.
Request Header
{
 "apiKey": "quejrhdkspoeiskw=="
}
Request Body
{
  "requestId": "req-spar-vbdjkahffoasdh874627wqufid",
  "merchantInfo": {
    "aid": "135743",
    "mid": "023563834593839",
    "tid": "56273158"
  },
  "amount": {
    "currency": "INR",
    "value": "20.00"
  },
  "attributes": {
    "requester_defined_attribute": "1234567890"
  },
  "authenticationData" : "jwtToken<String>",
  "sourceId": "src_d28adbe0-eacf-423c-af29-9841cab85a10",
  "successUrl": "htttps://merchant-successUrl.com",
  "failureUrl": "htttps://merchant-failureUrl.com",
  "validUntil": "1234234543"
}

Output parameters

ParametersDescription

transactionId

Transaction ID generated by system.

"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

requestId

Same as in request payload.

amountTransaction value and currency.

transactionState

The current state of the transaction.

Example: WAITING_FOR_CONSENT

redirectUserTo

This is a Zeta hosted URL where the merchant must redirect the users for completing the transaction. On this page, the users can view their payment instruments and authenticate the transaction using a payment instrument of their choice. After authentication, the user gets redirected back to requester’s success/failure URL.



Response
{
    "transactionId": "txn_0927be8a-4d13-402f-a0ae-c4f081cf552a",
    "requestId": "req-spar-wafwfvbdjkahffoasdh8746ddd27wqufid",
    "amount": {
        "currency": "INR",
        "value": "20.00"
    },
    "transactionState": "WAITING_FOR_CONSENT",
    "redirectUserTo": "https://bifrost.hdfc-beta.zetaapps.in/v2.0/tenants/13/transactions/initiate?q=txn_0927be8a-4d13-402f-a0ae-c4f081cf552a",
    "purposes": null,
    "transactionDetails": [
        {
            "merchantRequestId": "merchant_req_e35a5414-dd16-4fd9-b25f-72370290c6cf",
            "merchantInfo": {
                "aid": "HDFC_PVT_LTD",
                "mid": "Q22716",
                "tid": "75010004",
                "ifi": 1,
                "attributes": {}
            },
            "purposes": [
                {
                    "purpose": "PG",
                    "amount": {
                        "currency": "INR",
                        "value": "20.00"
                    }
                }
            ],
            "attributes": {
                "requester_defined_attribute": "1234567890"
            },
            "towards": null
        }
    ]
}

Error Codes

Possible error codes are ER000, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024, ERO65. For more details, see Error codes.

Response: 201 HTTP code

Operation: Create a transaction without source

This operation enables you to create a transaction without linking PayZapp as a source.

Functional behaviour

POST

/v2.0/payzapp/transactions

Input parameters

ParametersDescription

requestId

Transaction Request ID
This is generated by the requester. Transaction request ID is globally unique and it ensures that duplicate transactions are rejected.

"requestId" Naming Convention

Take care of the following to define requestId:
Characters allowed: a-z, A-Z, 0-9, -
Max size allowed: 60 characters.

merchantInfo

The following information about the merchant for whom the payment is requested.

  • AID: Acquirer ID (Unique identifier of the merchant's acquirer)

  • MID: Merchant ID (Unique identifier of the merchant)

  • TID: Terminal ID (Unique identifier of the merchant terminal)

amount

Transaction value with currency.
attributesSpecific tag used by the merchant for sharing any useful information as per their use case.

successUrl

Merchant’s URL to which the payment gateway will redirect on successful transaction authorization.

failureUrl

Merchant’s URL to which the payment gateway will redirect on failed transaction authorization.

validUntilRepresents the time in milliseconds during which the current request ID cannot be repeated.
Request Header
{
 "apiKey": "quejrhdkspoeiskw=="
}
Request Body
{
  "requestId": "req-spar-vbdjkahffoasdh874627wqufid",
  "merchantInfo": {
    "aid": "135743",
    "mid": "023563834593839",
    "tid": "56273158"
  },
  "amount": {
    "currency": "INR",
    "value": "20.00"
  },
  "attributes": {
    "requester_defined_attribute": "1234567890"
  },
  "successUrl": "htttps://merchant-successUrl.com",
  "failureUrl": "htttps://merchant-failureUrl.com",
  "validUntil": "1234234543"
}

Output parameters

ParametersDescription

transactionId

Transaction ID generated by system.

"transactionId" Naming Convention

Take care of the following to define transactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

requestId

Same as in request payload.

amountTransaction value and currency.

transactionState

The current state of the transaction.

Example: WAITING_FOR_CONSENT

redirectUserTo

URL where requester should redirect the user to complete authorization of transaction.
After authorization user is redirected back to requester’s success/failure Url.

Response
{
    "transactionId": "txn_0a51e284-2e5e-435a-9fb0-ae4c9bce1c05",
    "requestId": "99164993xdxdd55352731117",
    "amount": {
        "currency": "INR",
        "value": "292"
    },
    "transactionState": "WAITING_FOR_SOURCE",
    "redirectUserTo": "https://bifrost.hdfc-beta.zetaapps.in/v2.0/tenants/13/transactions/initiate?q=txn_0a51e284-2e5e-435a-9fb0-ae4c9bce1c05",
    "purposes": null,
    "transactionDetails": [
        {
            "merchantRequestId": "merchant_req_d22e5fd6-ee17-4a48-89dc-8293e3d17c59",
            "merchantInfo": {
                "aid": "HDFC_PVT_LTD",
                "mid": "Q22716",
                "tid": "75010004",
                "ifi": 1,
                "attributes": {}
            },
            "purposes": [
                {
                    "purpose": "PG",
                    "amount": {
                        "currency": "INR",
                        "value": "292"
                    }
                }
            ],
            "attributes": {},
            "towards": null
        }
    ]
}

Error Codes

Possible error codes are ER000, ER007, ER011, ER012, ER013, ER014, ER015, ER016, ER017, ER019, ER024, ERO65. For more details, see Error codes.

Response: 201 HTTP code

OperationGet transaction details

This operation enables you to retrieve the transaction details.

This API should be used only for Purchase transactions and not for Refund transactions.

Functional Behaviour

GET

/v2.0/payzapp/transactions/{transaction_id}

/v2.0/payzapp/transactions/request_id/{request_id}

Input parameters

ParametersDescription

apiKey

apiKey will be shared by Zeta with requester during the on-boarding process.

Request Header
{
	"apiKey" : "w9e75yifheq09tyehqriofhy0q349htorehtlGJKHu095338kehqo"
}

Output parameters

ParametersDescription
transactionIdTransaction ID generated by system.
requestIdRequest Id used to fetch the transaction details.
amountTransaction amount and currency.

transactionState

AUTHORIZED

(For detailed description, refer to Transaction States)

failureReasonReason for failure of transaction.

sourceId

Source used for completing the transaction.

paymentAccounts

Type of payment account and amount.

transactionCreatedTime

Time at which the transaction was created.

transactionReceipt

Transaction receipt attribute defined by the requester.

ReceiptIDUnique identifier of the receipt.
AuthorisationTimeTime at which the transaction was authorized.
Response Sample
{
    "transactionId": "txn_8028ff97-7f62-453c-b5d3-18cc95a48e24",
    "requestId": "99164993xdxdd5535ddwfw2731117",
    "amount": {
        "currency": "INR",
        "value": "292.00"
    },
    "transactionState": "AUTHORIZED",
    "sourceId": "src_748d0851-07e7-432c-9460-145dca30fe42",
    "transactionCreatedTime": 1662540634671,
    "transactionReceipt": {
        "receiptID": 29436002685,
        "authorisationTime": 1662540677792
    },
    "paymentAccounts": [
        {
            "type": "PREPAID_CARD",
            "amount": {
                "currency": "INR",
                "value": "292"
            }
        }
    ]
}

Error Codes

Possible error codes are - ER000, ER007, ER010, ER013, ER017, ER019. For more details, see Error codes.

Response: 200 HTTP code

Operation: Request a refund

This operation enables you to partially or fully refund the amount during a pre and post clearance process.

When does the money get refunded to the customer?
If full refund is requested before the transaction gets cleared, the amount is refunded immediately.
If the refund is requested post clearance or a partial refund is requested, then refund will be done in next 2-3 days.

Refund of transactions created using an older version PayZapp API

To refund any transaction created using a previous version of PayZapp API, you must use the previous version Request Refund API itself. You can't use this API to refund a transaction created using an older version PayZapp API. 


Functional behaviour

POST

/v2.0/payzapp/transactions/{transactionId}/refund

Input Parameters

ParameterDescription
requestId

Refund transaction request ID. This is generated by the requester. Request ID is globally unique and it ensures that duplicate transactions are rejected.

Take care of the following allowed naming conventions for defining requestId:
Characters allowed: a-z, A-Z, 0-9, -
Max size allowed: 60 characters.

transactionId

This is the transaction ID of the purchase transaction for which refund has to be initiated. You can find this transaction ID in the response for Create Transaction API.

amount

Transaction value and currency.
Request Header
{
 "apiKey" : "quejrhdkspoeiskw=="
}
Request Body
{
  "requestId": "refund-request-id-1",
  "transactionId": "txn_69a2f3a5-0afb-46a3-86d2-1ec62881e067",
  "amount": {
    "currency": "INR",
    "value": "10.00"
  }
}

Output parameters

ParameterDescription
requestIdRequest ID echoed back from the request payload itself.
purchaseTransactionId

Purchase transaction ID of the requested refund. This parameter is mandatory to get the refund status.

"purchaseTransactionId" Naming Convention

Take care of the following to define purchaseTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

refundTransactionId

Refund transaction ID of a refund transaction.

"refundTransactionId" Naming Convention

Take care of the following to define refundTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

Response Sample
{
    "requestId": "refund-reqsuest-id-1",
    "purchaseTransactionId": "txn_8028ff97-7f62-453c-b5d3-18cc95a48e24",
    "refundTransactionId": "txn_f582be2b-944a-442a-aef2-556a172e6e6b"
}

Error Codes

Possible refund-related error codes are - ER041, ER042. For more details, see Error codes.

Response: 201 HTTP code

Operation: Get refund status

This operation enables you to retrieve the status of the refunds.

Functional behaviour

GET

/v2.0/payzapp/transactions/{purchaseTransactionId}/refunds

Input parameters

ParameterDescription
apiKeyapiKey will be shared by Zeta with requester during the on-boarding process.
purchaseTransactionId

Purchase transaction ID of the requested refund from the Refund a Transaction operation.

"purchaseTransactionId" Naming Convention

Take care of the following to define purchaseTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

Request Header
{
 "apiKey" : "quejrhdkspoeiskw=="
}

Output parameters

ParameterDescription

refundTransactionId

Refund transaction ID of a refund transaction

"refundTransactionId" Naming Convention

Take care of the following to define refundTransactionId:
Characters allowed: a-z, A-Z, 0-9, -, _
Max size allowed: 60 characters.

requestIDRequest Id used to fetch the transaction details.

refundState

State of the refund.
amountThe transaction amount.
refundRequestedTimeTime at which the request was made.
Response Sample
{
    "refundStatusDetails": {
        "txn_f582be2b-944a-442a-aef2-556a172e6e6b": {
            "refundTransactionId": "txn_f582be2b-944a-442a-aef2-556a172e6e6b",
            "requestId": "refund-reqsuest-id-1",
            "refundState": "REFUND_COMPLETED",
            "amount": {
                "currency": "INR",
                "value": "292"
            },
            "requestTime": 1662540887241
        }
    }
}

Response: 200 HTTP code


On this page:

  • No labels