Note

CBPR+ fields are available in mock responses for select endpoints. Preview supported scenarios in the API specification for Global Payments 2. Learn more in our blog.

Initiate a Push to Wallet payment request

In this tutorial, you'll 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'll know how to:

Create a well-formed Push to Wallet payment request payload.
Interpret the values in a successful response.
Use the endToEndId to verify the status of your request.

Before you begin

To use Push to Wallet, you'll need the following:

A registered and fully onboarded Developer Account on the J.P. Morgan Payments Developer Portal.
An active project with valid API credentials.
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 following example shows a Push to Wallet payment request for a Venmo wallet using a mobile phone number:

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

Json

{
  "payments": {
    "requestedExecutionDate": "2024-06-26",
    "paymentIdentifiers": {
      "endToEndId": "0722B02A100"
    },
    "paymentCurrency": "USD",
    "paymentAmount": 10,
    "transferType": "CREDIT",
    "debtor": {
      "debtorName": "John Doe",
      "debtorAccount": {
        "accountId": "012345678"
      }
    },
    "debtorAgent": {
      "financialInstitutionId": {
        "bic": "CHASUS33"
      }
    },
    "creditor": {
      "creditorName": "Jane Doe",
      "creditorAccount": {
        "alternateAccountIdentifier": "TEST1US",
        "accountType": "VENMO",
        "schemeName": {
          "proprietary": "TELI"
        }
      },
      "postalAddress": {
        "postalCode": "99999",
        "country": "US"
      }
    },
    "purpose": {
      "code": "SERVICES",
      "type": "PROPRIETARY"
    },
    "remittanceInformation": {
      "unstructuredInformation": [
        "Payment for catering facilities - INVC009887"
      ]
    }
  }
}

PayPal e-mail address

The following example shows a Push to Wallet payment request for a PayPal wallet using an email 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 directed to a PayPal wallet using a mobile phone number, initiated by a client who is a Third Party Payment Provider (TP3) or Money Services Business (MSB):

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 previous examples as a template and try it now in our interactive testing environment.

Confirm Response

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

Example response with endToEndId & firmRootId - HTTP 202 Accepted

Json

{
  "paymentInitiationResponse": {
    "firmRootId": "19694843-h035-4951-srj3-0c95d3fe4b66",
    "endToEndId": "DJ937HJ4L5S0"
    }
}

You may encounter several error responses at this stage. We recommend reviewing 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.