Venmo Enrollment

Venmo is a mobile payment service owned by PayPal. Venmo account holders can transfer funds to others via a mobile phone app; both the sender and receiver have to live in the U.S.

Payment flow

568568

Redirect Integration

Currently not supported.

Backend2Backend Integration

Please find the full diagram here.

13001300

The user enrollment is done using PXP Payment Service V5 API.

User enrollment - Payment Service V5 API

For enrollment of user to Venmo the following request has to be sent:

📘

Venmo Enrollment

... with the following JSON request data parameters:

Name

Description

merchantId

The ID of the Merchant

clientSystemUserEnrollmentId

The ID of the SystemUserEnrollmentID. It should be an unique ID.

type

Type of account. i.e account.venmo

userId

PXP Financial external user ID

accountNumber

The nonce obtained from the Venmo Client Side SDK

Sample EnrollmentRequest:

{
    "merchantId": "YourTestMerchant",
    "clientSystemUserEnrollmentId": "1234556",
    "type": "account.venmo",
    "userId": "5678432",
    "details": {
        "accountNumber" : "fake-venmo-account-nonce"
    }
}

Example EnrollmentResponse:

{
    "id":"0d652af0-c838-48e1-aa0d-9ab3cb9b03f5",
    "state":" AccountTokenized",
    "details":{
        "PaymentAccountID":"8fa1f57f-f5b1-4d82-a1c2-53a0b6cc616",
        "WalletUserName":"venmojoe",
        "WalletUserID":"Venmo-Joe-1",
        "ProviderCustomerID": "Y3VzdG9tZXJfODIwMDY1MjYy"
    }
}
{
    "code": "UserEnrollmentDeclined",
    "details": {
        "error": "The user enrollment request for [Type=account.venmo, UserExternalID=5678432, ClientSystemUserEnrollmentId=1234556, MerchantExternalID=YourTestMerchant] requires an AccountNumber detail."
    }
}
{
    "code": "SchemaValidationError",
    "details": {
        "validationErrors": "The UserID field is required."
    }
}

JSON Response Data Parameters:

Name

Description

PaymentAccountID

The payment account ID registered at PXP. It is used in all subsequent payment initiation requests.

WalletUserName

User's current Venmo username. Can be changed by the user.

WalletUserID

User's immutable Venmo user id. Can never be changed by the user.

ProviderCustomerID

The Customer ID generated by BrainTreeat at the time of customer creation.

Reversal of Enrollment

Example EnrollmentReversalRequest:

{
     "merchantId": "Renegades_Test",
     "clientSystemUserEnrollmentId": "ABC123",
     "type": "Revert",
     "userId": "bf136c9f-5538-4980-b796-7483af"
}

Example EnrollmentReversalResponse:

{
    "id": "b9c04d6d-76d8-4f43-9050-6884cdb8ce7d",
    "state": "EnrollmentReverted",
    "details": {
        "PaymentAccountID": "8da9e464-c659-4eab-856b-7c281f3b7589",
        "WalletUserID": "Venmo-Joe-1",
        "WalletUserName": "venmojoe",
        "ProviderCustomerID": "Y3VzdG9tZXJfMTg4MDE1MTQy"
    },
    "stateDescription": null
}

Example EnrollmentReversalResponse in AccountTokenizationRevertCommunicationError:

{
    "id": "f17070d4-c377-4eef-abd1-c68c24401e29",
    "state": "AccountTokenizationRevertCommunicationError",
    "details": {
        "PaymentAccountID": "5385a198-187e-4407-a517-aea5c308b2a7",
        "WalletUserID": "Venmo-Joe-1",
        "WalletUserName": "venmojoe",
        "ProviderCustomerID": "Y3VzdG9tZXJfMjUzNDM2MTM4"
    },
    "stateDescription": "Error occurred while processing business operation communication for BusinessOperation[ID='2880227', TypeID='4']."
}

Example EnrollmentReversalResponse in AccountTokenizationRevertFailed:

{
    "id": "b0c0bc1d-c21b-45ed-85cd-78c9962146f6",
    "state": "AccountTokenizationRevertFailed",
    "details": {
        "PaymentAccountID": "32571feb-6b65-4449-9902-4717d15405bc",
        "WalletUserID": "Venmo-Joe-1",
        "WalletUserName": "venmojoe",
        "ProviderCustomerID": "Y3VzdG9tZXJfODI3NTgyNTU1"
    },
    "stateDescription": null
}

Example EnrollmentReversalResponse in EnrollmentRevertFailed:

{
    "id": "a32a3720-3d8e-4d0d-861a-529f8df6e810",
    "state": "EnrollmentRevertFailed",
    "details": {
        "PaymentAccountID": "eecd33aa-a85f-4804-be68-9571a6206f0b",
        "WalletUserID": "Venmo-Joe-1",
        "WalletUserName": "venmojoe",
        "ProviderCustomerID": "Y3VzdG9tZXJfODcyNjQ1MTMw"
    },
    "stateDescription": null
}

Payment Account Change Notifications

A Venmo customer can delete the merchant connection from within their Venmo app or Venmo account any time. This will remove the Venmo payment method from the merchant´s vault.
In such a case, the merchant should no longer show this Venmo account/token as stored payment method in the merchant profile for that customer.

PXP system receives a notification from Braintree with the information that the customer has deleted the merchant connection. The information is processed and the regarding Payment Account is set to isActive = false and isVisible = false.

A handlePaymentAccountChangedNotification is sent to the merchant system by PXP to inform about the change of the payment account.
Also see PaymentAccountChangedNotification.

📘

Attention

This notification request will be changed shortly.
From May on TEST1 and LIVE, isActive will be returned as true, and isVisible will be returned as false. The sample below has already been adjusted accordingly.

Example handlePaymentAccountChangedNotificationRequest sent to merchant:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentAccountChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <paymentAccount>
        <merchantID xmlns="http://www.cqrpayments.com/PaymentProcessing">29101992</merchantID>
        <userID xmlns="http://www.cqrpayments.com/PaymentProcessing">e45ed472-dd52-443b-b1a7-76e39b</userID>
        <paymentAccountID xmlns="http://www.cqrpayments.com/PaymentProcessing">2aa37f1e-abec-4fc7-83b3-19a48ae9f47c</paymentAccountID>
        <paymentAccountTypeID xmlns="http://www.cqrpayments.com/PaymentProcessing">26</paymentAccountTypeID>
        <isActive xmlns="http://www.cqrpayments.com/PaymentProcessing">true</isActive>
        <isVisible xmlns="http://www.cqrpayments.com/PaymentProcessing">false</isVisible>
        <specificPaymentAccountData xmlns="http://www.cqrpayments.com/PaymentProcessing">
            <data xsi:type="keyStringValuePair">
                <key>WalletUserID</key>
                <value>Venmo-Joe-1BB</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>WalletUserName</key>
                <value>venmojoe</value>
            </data>
        </specificPaymentAccountData>
        <state xmlns="http://www.cqrpayments.com/PaymentProcessing">
            <id>9138e23e-9ba6-42e0-9726-01b81265715d</id>
            <definition>2</definition>
            <createdOn>2022-01-20T16:57:54.4580883Z</createdOn>
            <paymentAccountStateDetails />
        </state>
    </paymentAccount>
</handlePaymentAccountChangedNotificationRequest>

Example handlePaymentAccountChangedNotificationResponse to be sent back by the merchant:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentAccountChangedNotificationResponse
         xmlns="http://www.cqrpayments.com/PaymentProcessing"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema">
</handlePaymentAccountChangedNotificationResponse>

Negative testing in Sandbox

On provider testing in sandbox, the merchant can run test transactions with the following amounts and it should trigger declines.

Amount

Response

2000.00 - 2999.99

Processor Decline with processor response equal to the amount

3000.00-3000.99

Failed with a 3000 processor response