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

Redirect Integration

Currently not supported.

Backend2Backend Integration

Please find the full diagram here.

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

URL: https://payments.test.kalixa.com/api/v5/userEnrollments

Type: account.venmo

HttpMethod: POST

... 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.

ExamplehandlePaymentAccountChangedNotificationRequest 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>

ExamplehandlePaymentAccountChangedNotificationResponse 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

Updated 17 days ago

Venmo Enrollment

Payment flow

Redirect Integration

Backend2Backend Integration

User enrollment - Payment Service V5 API