Skip to main content
Beta version available

The Global Payments 2 API is currently available in beta. Contact our team to start your integration process.

Initiate a Zelle® Disbursement request

In this tutorial, you'll learn how to use the Global Payments API to initiate a Zelle® Disbursement. After sending the request, you'll review a successful response and learn how to check the status of your request.

By the end of this tutorial, you'll know how to:

  • Create a well-formed Zelle® Disbursements payment request payload.
  • Interpret the values in a successful response.
  • Use the endToEndId to check and confirm the status of your request.

Before you begin

To use Zelle® Disbursements, you'll need the following:

Create and send a Zelle® Disbursement request payload

Request payloads for the Global Payments API have optional and required fields. The following example shows the suggested payload for a Zelle® Disbursement request in the United States:

POST /tsapi/v1/payments HTTP/1.1
Json
{
  "payments": {
    "requestedExecutionDate": "2025-05-08",
    "paymentIdentifiers": {
      "endToEndId": "ZELLETESTABC"
    },
    "paymentCurrency": "USD",
    "paymentAmount": 0.1,
    "transferType": "CREDIT",
    "debtor": {
      "debtorName": "John Doe",
      "debtorAccount": {
        "accountId": "123456789"
      }
    },
    "debtorAgent": {
      "financialInstitutionId": {
        "bic": "CHASUS33"
      }
    },
    "creditor": {
      "creditorName": "Jane Doe",
      "creditorAccount": {
        "accountType": "ZELLE",
        "alternateAccountIdentifier": "Jane.Doe@example.com",
        "schemeName": {
          "proprietary": "EMAL"
        }
      }
    }
  }
}

Confirm response

You'll receive a successful response containing a firmRootId and an endToEndId. You can use these values in the next step to retrieve the status of your request.

Example response with endToEndId & firmRootId - HTTP 202 Accepted
Json
{
    "paymentInitiationResponse": {
        "firmRootId": "107c46c4-f99f-47ba-9a3f-4594fa567ef8",
        "endToEndId": "ZELLETESTABC XR202109202311354152"
    }
}

You may encounter several error responses at this stage. We recommend checking the error codes section to understand supported responses. If you need additional support, contact your Client Service Account Manager.

Payment initiation callback

Clients can opt to receive callback responses for their payment initiations. Callbacks provide additional details about the status of your request..

Successful callback example

Example callback successful: COMPLETED
Json
{
  "callbacks": [
    {
      "endToEndId": " ZELLETESTABC ",
      "createDateTime": "2025-05-08T17:18:26.096Z",
      "paymentStatus": "COMPLETED",
      "firmRootId": “107c46c4-f99f-47ba-9a3f-4594fa567ef8"
    }
  ]
}

Rejected callback example

Example of a rejected callback
Json
{
  "callbacks": [
    {
      "endToEndId": "EDZRLHRQ0WQXYYZ",
      "createDateTime": "2025-05-08T20:01:23.900Z",
      "paymentStatus": "REJECTED",
      "firmRootId": "2205f1d6-2fbb-49cc-be7e-b99cd245zzyy",
      "exceptions": [
        {
          "errorCode": "10001",
          "errorDescription": "Error occurred on /creditor/creditorAccount/accountId or /creditor/creditorAccount/alternateAccountIdentifier",
          "ruleDefinition": "Mandatory field is missing or invalid"
        }
      ]
    }
  ]
}

Next steps