GuidesAPI ReferenceDiscussions

Venmo Enrollment

Suggest Edits

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

568

Redirect Integration

Currently not supported.

Backend2Backend Integration

Please find the full diagram here.

1300

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:

NameDescription
merchantIdThe ID of the Merchant
clientSystemUserEnrollmentIdThe ID of the SystemUserEnrollmentID. It should be an unique ID.
typeType of account. i.e account.venmo
userIdPXP Financial external user ID
accountNumberThe 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:

NameDescription
PaymentAccountIDThe payment account ID registered at PXP. It is used in all subsequent payment initiation requests.
WalletUserNameUser's current Venmo username. Can be changed by the user.
WalletUserIDUser's immutable Venmo user id. Can never be changed by the user.
ProviderCustomerIDThe 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.

AmountResponse
2000.00 - 2999.99Processor Decline with processor response equal to the amount
3000.00-3000.99Failed with a 3000 processor response

Updated about 2 years ago