Initiate a Push to Wallet payment request

In this tutorial, you will learn how to use the Global Payments API to initiate a Push to Wallet 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 will know how to:

Create a well-formed Push to Wallet 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 Wallet, you will 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 bank account configured for each country where you want to perform a Push to Wallet payment transaction.

Create and send a Push to Wallet request payload

Request payloads for the Global Payments API have required and conditional fields.

Venmo mobile phone number

The below example shows for an Push to Wallet payment request when the payment is to a Venmo wallet using a mobile phone number:

POST /tsapi/v1/payments HTTP/1.1 - Venmo mobile phone number

Json

{
  "payments": {
    "possibleDuplicateMessage": false,
    "paymentIdentifiers": {
      "endToEndId": "SL37CB45SDD3"
    },
    "requestedExecutionDate": "2024-01-01",
    "transferType": "CREDIT",
    "paymentCurrency": "USD",
    "paymentAmount": 10,
    "debtor": {
      "debtorAccount": {
        "accountId": "012345678",
        "accountType": "DDA"
      },
      "debtorName": "Edison James"
    },
    "debtorAgent": {
      "financialInstitutionId": {
        "bic": "CHASUS33"
      }
    },
    "creditor": {
      "creditorName": "Kagisago Rabada",
      "creditorAccount": {
        "alternateAccountIdentifier": "0987600000",
        "accountType": "VENMO",
        "schemeName": {
          "proprietary": "TELI"
        }
      },
      "postalAddress": {
        "postalCode": "33606",
        "country": "US"
      }
    },
    "remittanceInformation": {
      "unstructuredInformation": [
        "Payment for catering facilities - INVC009887"
      ]
    }
  }
}

PayPal e-mail address

The following example shows a Push to Wallet payment request when the payment is to a PayPal wallet using an e-mail address:

POST /tsapi/v1/payments HTTP/1.1 - PayPal e-mail address

Json

{
  "payments": {
    "possibleDuplicateMessage": false,
    "paymentIdentifiers": {
      "endToEndId": "FJ57S9K4L0AA22"
    },
    "requestedExecutionDate": "2024-01-01",
    "transferType": "CREDIT",
    "paymentCurrency": "USD",
    "paymentAmount": 10,
    "debtor": {
      "debtorAccount": {
        "accountId": "012345678",
        "accountType": "DDA"
      },
      "debtorName": "Eoin Morgan"
    },
    "debtorAgent": {
      "financialInstitutionId": {
        "bic": "CHASUS33"
      }
    },
    "creditor": {
      "creditorName": "Robert Brown",
      "creditorAccount": {
        "alternateAccountIdentifier": "robert.brown@example.com",
        "accountType": "PAYPAL",
        "schemeName": {
          "proprietary": "EMAL"
        }
      },
      "postalAddress": {
        "postalCode": "33634",
        "country": "US"
      }
    },
    "remittanceInformation": {
      "unstructuredInformation": [
        "Payment for Building materials - INVC009100"
      ]
    }
  }
}

PayPal mobile for TP3/MSB

The following example shows a Push to Wallet payment request when the payment is directed to a PayPal wallet using a mobile phone number, and by a client who is a Third Party Payment Provider or Money Services Business.

POST /tsapi/v1/payments HTTP/1.1 - PayPal mobile phone number for MSB

Json

{
  "payments": {
    "requestedExecutionDate": "2024-06-26",
    "paymentIdentifiers": {
      "endToEndId": "07222024334"
    },
    "paymentCurrency": "USD",
    "paymentAmount": 0.01,
    "transferType": "CREDIT",
    "debtor": {
      "debtorName": "Eoin Morgan",
      "debtorAccount": {
        "accountId": "112011000"
      },
      "ultimateDebtor": {
        "ultimateDebtorName": "Paula Smitty",
        "postalAddress": {
          "streetName": "Kennody",
          "buildingNumber": "291",
          "postalCode": "33606",
          "townName": "Tampa",
          "country": "US"
        },
        "organizationId": {
          "id": "001"
        }
      }
    },
    "debtorAgent": {
      "financialInstitutionId": {
        "bic": "CHASUS33"
      }
    },
    "creditor": {
      "creditorName": "Jane Smith",
      "creditorAccount": {
         "alternateAccountIdentifier": "someone@domain.com",
        "accountType": "PAYPAL",
        "schemeName": {
          "proprietary": "EMAL"
        }
      },
    "postalAddress": {
        "postalCode": "33634",
        "country": "US"
      }
    },
    "purpose": {
      "code": "GOODS",
      "type": "PROPRIETARY"
    },
    "remittanceInformation": {
      "unstructuredInformation": [
        "Test Transaction 000"
      ]
    }
  }
}

Create a request payload using one of the examples above as a template and try it now in our interactive testing environment.

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": {
    "firmRootId": "19694843-h035-4951-srj3-0c95d3fe4b66",
    "endToEndId": "DJ937HJ4L5S0"
    }
}

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

Next steps

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