Beta version available

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

Initiate a Push to Card payment request

In this tutorial, you'll learn how to use the Global Payments API to initiate a Push to Card payment. 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 Push to Card 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 Push to Card, you'll need the following:

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 bank account configured for each country where you want to perform a Push to Card payment transaction.
A Merchant ID and Program ID for Push to Card, provided by your technical Implementation specialist.

Create and send a Push to Card request payload

Request payloads for the Global Payments API include both optional and required fields. The following example shows the suggested payload for a Push to Card payment request in the U.S.:

POST /tsapi/v1/payments HTTP/1.1

Json

{
  "requestedExecutionDate": "2024-10-30",
  "paymentIdentifiers": {
    "endToEndId": "1lv0t92e023g11354100"
  },
  "transferType": "CREDIT",
  "value": {
    "currency": "USD",
    "amount": "750"
  },
  "paymentType": "CARD",
  "debtor": {
    "name": "John Doe",
    "account": {
      "alternateAccountIdentifiers": [
        {
          "identifier": "PRU01US",
          "idType": "PROGRAM_ID"
        }
      ]
    }
  },
  "debtorAgent": {
    "financialInstitutionIds": [
      {
        "id": "CHASUS33",
        "idType": "BIC"
      }
    ]
  },
  "creditor": {
    "name": "Jane Doe",
    "account": {
      "card": {
        "pan": "4137110019999999",
        "expiryDate": "2207"
      }
    }
  },
  "remittanceInformation": {
    "unstructuredInformation": [
      {
        "text": "Milestone Music"
      }
    ]
  }
}

Create your request payload using the previous example as a template, or test it now in our interactive testing environment.

Create and send a Push to Card TP3 request payload

Third Party Processing (TP3) is supported using ultimate debtor fields as part of the payment initiation. The following example shows an example payload, including optional fields, for a TP3 Push to Card payment request in the U.S. only:

Example payment request including optional fields - TP3 Push to Card payment

Json

{
  "payments": {
    "requestedExecutionDate": "2023-09-26",
    "transferType": "CREDIT",
    "paymentIdentifiers": {
      "endToEndId": "TESTTP302"
    },
    "paymentCurrency": "USD",
    "paymentAmount": 1.10,
    "debtor": {
      "debtorName": "John Doe",
      "debtorAccount": {
        "alternateAccountIdentifier": "TEST1US"
      },
      "ultimateDebtor": {
        "ultimateDebtorName": "Jane Smith ",
        "dateAndPlaceOfBirth": {
          "birthDate": "1994-03-14"
        },
        "countryOfResidence": "US",
        "postalAddress": {
          "addressType": "ADDR",
          "streetName": "Fantasy Lane",
          "buildingNumber": "9999",
          "postalCode": "99999",
          "townName": "Imaginary City",
          "country": "US",
          "countrySubDvsn": "ZZ"
        }
      }
    },
    "debtorAgent": {
      "financialInstitutionId": {
        "bic": "CHASUS33"
      }
    },
    "creditor": {
      "creditorName": "Jane Doe",
      "creditorAccount": {
        "accountType": "CARD",
        "alternateAccountIdentifier": "TEST1US",
        "cardExpiryDate": "2310"
      }
    },
    "remittanceInformation": {
      "unstructuredInformation": [
        "Insurance Payment"
      ]
    }
  }
}

Confirm response

You will receive a successful response containing a firmRootId and an endToEndId. These values can be used in the next step to retrieve the status of your request.

Example response with endToEndId & firmRootId - HTTP 202 Accepted

Json

{
    "paymentInitiationResponse": {
        "endToEndId": "1lv0t92e023g11354100",
        "firmRootId": "98275a2d-1e88-beed-6938-0521a7e0uptc"
    }
}

At this stage, you may encounter several error responses. We recommend viewing 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 into receiving callback responses for their payment initiations.These callbacks offer additional details regarding the status of your request.

Successful callback example:

Example callback successful: COMPLETED

Json

{
  "callbacks": [
    {
      "endToEndId": "TESTTP304",
      "createDateTime": "2023-10-16T17:18:26.096Z",
      "paymentStatus": "COMPLETED",
      "firmRootId": "fffa01ed-786b-4f5f-8517-55c8004230bd"
    }
  ]
}

Failed Callback example:

Example Callback failure: Mandatory field is missing or invalid

Json

{
  "callbacks": [
    {
      "endToEndId": "EDZRLHRQ0WQXYYZ",
      "createDateTime": "2023-10-19T20: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

Learn how to retrieve the status of your request.
Understand required payment parameters.
Review our table of potential error codes.