Skip to main content
Beta version

Welcome to the beta version of the Global Payments 2 API! For the generally available Global Payments API, refer to Global Payments. 

Initiate a Kinexys Digital Payments request

In this tutorial, you will learn how to use the Global Payments API to initiate a Kinexys Digital Payments request from a Blockchain Deposit Account (BDA) to another BDA or a Demand Deposit Account (DDA). By the end of this tutorial, you will know how to:

  • Create a well-formed Kinexys Digital Payments request payload from a BDA to BDA.
  • Create a well-formed Kinexys Digital Payments request payload from a BDA to DDA from the same or different entity.
  • Interpret the values in a successful response.

Before you begin

To initiate a Kinexys Digital Payments, you need:

  • A registered and fully onboarded Developer Account on the J.P. Morgan Payments Developer Portal.
  • An active project that provides you with the credentials used to make a request.
  • A J.P. Morgan Blockchain Deposit Accounts (BDA) opened at J.P. Morgan Chase Bank, N.A. 
  • A Demand Deposit Account (DDA) opened in an approved funding location in which you want to perform a Kinexys Digital Payments transaction.
Tip

In addition to regular Demand Deposit Accounts (DDA), select Client Money Accounts (CMA) and Mortgage Servicing Accounts (MSA) are supported by this product, subject to J.P. Morgan review.

Send a request

Request payloads for the Global Payments API have optional and required fields. The full request payload is sent using a POST request to the /payments endpoint.

The following examples show the minimum required payload for a Kinexys Digital Payments request, with no optional fields included.

Kinexys Digital Payments (BDA to BDA)

Use the following payload example to initiate a payment to move funds between two Blockchain Deposit Accounts (BDAs). These BDAs can belong to the same or different entity.

Example of a Kinexys Digital Payments (BDA to BDA) request
curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/payment/v2/payments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 1b036f9c-8c84-4ce6-b1dd-5979472945a1' \
  --header 'Request-Id: 1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p' \
  --data '{
"requestedExecutionDate": "2024-10-30",
  "paymentIdentifiers": {
    "endToEndId": "Kinexys2024_0834"
  },
  "transferType": "CREDIT",
  "value": {
    "currency": "USD",
    "amount": "6500"
  },
  "paymentType": "BLOCKCHAIN",
  "debtor": {
    "account": {
      "accountNumber": "940091064",
      "accountType": "BDA"
    }
  },
  "debtorAgent": {
    "financialInstitutionIds": [
      {
        "id": "CHASUS33",
        "idType": "BIC"
      }
    ]
  },
  "creditor": {
    "account": {
      "accountNumber": "80091097",
      "accountType": "BDA"
    }
  },
  "creditorAgent": {
    "financialInstitutionIds": [
      {
        "id": "CHASESM3",
        "idType": "BIC"
      }
    ]
  },
  "remittanceInformation": {
    "unstructuredInformation": [
      {
        "text": "Payment for container shipment"
      }
    ]
  }
}'

Kinexys Digital Payments (BDA to DDA)

Use the following payload example to initiate a payment to move funds from a Blockchain Deposit Account (BDA) to a Demand Deposit Account (DDA). The following are common Kinexys Digital Payments combinations:

  • A payment from a BDA to a DDA, where both the BDA and DDA belong to the same entity
  • A payment from a BDA to a DDA, where the BDA and DDA can belong to different entities 
Example of a Kinexys Digital Payments (BDA to DDA) request
curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/payment/v2/payments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 1b036f9c-8c84-4ce6-b1dd-5979472945a1' \
  --header 'Request-Id: 1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p' \
  --data '{
   "requestedExecutionDate": "2024-10-30",
  "paymentIdentifiers": {
    "endToEndId": "Kinexys2024_0834"
  },
  "transferType": "CREDIT",
  "value": {
    "currency": "USD",
    "amount": "6500"
  },
  "paymentType": "BLOCKCHAIN",
  "debtor": {
    "account": {
      "accountNumber": "80091097",
      "accountType": "BDA"
    }
  },
  "debtorAgent": {
    "financialInstitutionIds": [
      {
        "id": "CHASSGSG",
        "idType": "BIC"
      }
    ]
  },
  "creditor": {
    "account": {
      "accountNumber": "0070103277",
      "accountType": "DDA"
    }
  },
  "creditorAgent": {
    "financialInstitutionIds": [
      {
        "id": "CHASUS33",
        "idType": "BIC"
      }
    ]
  },
  "remittanceInformation": {
    "unstructuredInformation": [
      {
        "text": "Payment for container shipment"
      }
    ]
  }
}'

Confirm the response

You should receive a successful response containing  an endToEndId and a paymentId. These values are used to retrieve the status of your request.

Example of a successful Kinexys Digital Payments response
Json
{
  "endToEndId": "Kinexys2024_0834",
  "paymentId": "98275a2d-1e88-beed-6938-0521a7e0oinc"
}

There are a few error responses you may encounter. For more information about error codes, see the status response and error codes section.

Kinexys Digital Payments request callbacks

Transaction status responses for your Kinexys Digital Payments request are provided through callbacks.

The Kinexys Digital Payments supports multiple response types, including RECEIVED, ACCEPTED, PROCESSING, CANCELED, COMPLETED, and RETURNED. For more information, see Response types.

Next steps