Venmo

AVAILABLILITY

Venmo is available for supported iOS and Android devices for convenient mobile purchasing.

For more details on compatibility and availability, see our Venmo support article.

Creating a Payment Context

IMPORTANT

The CreateVenmoPaymentContext mutation is intended for API-only merchants. See our client-side integration guides for web or mobile integrations.

Payment Contexts are a “bag of data” that can be read by a merchant, Braintree and Venmo/PayPal. It is used to write into, read from, and share information amongst the applications. You can declare intent about the payment method before creating a Venmo transaction as well as specify details on whether the transaction should be vaulted or not. Additionally, you can specify flags to collect certain customer information. For the full list of available inputs, please check out our reference docs.

mutation

mutation CreateVenmoPaymentContext($input: CreateVenmoPaymentContextInput!) {
    createVenmoPaymentContext(input: $input) {
      clientMutationId
      venmoPaymentContext {
        id
        merchantId
        intent
        createdAt
        updatedAt
        status
        environment
        expiresAt
        paymentMethodId
        clientSDKMetadata {
          platform
          sessionId
          version
          integration
        }
        paymentMethodUsage
        customerClient
        merchantProfileId
        displayName
        isFinalAmount
        returnUrl
        paysheetDetails {
          collectCustomerBillingAddress
          collectCustomerShippingAddress
          transactionDetails {
            shippingAmount
            taxAmount
            discountAmount
            subTotalAmount
            totalAmount
            venmoPaysheetLineItems {
              name
              quantity
              unitAmount
              unitTaxAmount
              type
              description
              url
              productCode
            }
          }
        }
      }
    }
}

variables

{
  "input": {
    "clientMutationId": "abc123",
    "intent": "PAY_FROM_APP",
    "paymentMethodUsage": "MULTI_USE",
    "customerClient": "DESKTOP",
    "merchantProfileId": "optional merchant profile id",
    "displayName": "optional display name",
    "isFinalAmount": true,
    "returnUrl": "https://example.com/returnUrl",
    "paysheetDetails": {
      "collectCustomerBillingAddress": true,
      "collectCustomerShippingAddress": true,
      "transactionDetails": {
        "subTotalAmount": "12.00",
        "totalAmount": "12.00",
        "venmoPaysheetLineItems": [{
          "name": "some name",
          "quantity": 1,
          "unitAmount": "12.00",
          "type": "DEBIT",
          "unitTaxAmount": "0.00"
        }]
      }
    }
  }
}

response

{
  "data": {
    "id": "some-id",
    "merchantId": "integration_merchant_id",
    "intent":"PAY_FROM_APP",
    "createdAt": "YYYY-MM-DD",
    "updatedAt": "YYYY-MM-DD",
    "status":"CREATED",
    "environment":"SANDBOX",
    "expiresAt": "YYYY-MM-DD",
    "paymentMethodId": nil,
    "clientSDKMetadata": {
    "integration": "integration",
    "platform": "iOS",
    "version": "3.14.1",
    "sessionId": "sessionId",
  },
  "paymentMethodUsage": "MULTI_USE",
  "customerClient": "DESKTOP",
  "merchantProfileId": "optional merchant profile id",
  "displayName": "optional display name",
  "isFinalAmount": true,
  "returnUrl": "https://example.com/returnUrl",
  "paysheetDetails": {
    "collectCustomerBillingAddress": true,
    "collectCustomerShippingAddress": true,
    "transactionDetails": {
      "totalAmount": "12.00",
      "discountAmount": nil,
      "taxAmount": nil,
      "shippingAmount": nil,
      "subTotalAmount": "12.00",
      "venmoPaysheetLineItems": [{
      "name": "some name",
      "quantity": 1,
      "unitAmount": "12.00",
      "unitTaxAmount": "0.00",
      "type": "DEBIT",
      "description": nil,
      "url": nil,
      "productCode": nil
      }]
    }
  }
},
    "extensions": {
        "requestId": "a-uuid-for-the-request"
    }
}

Vaulting the Venmo account

Your customer's Venmo account can be saved to your Vault using vaultPaymentMethod mutation and reused for future transactions.

mutation

mutation VaultPaymentMethod($input: VaultPaymentMethodInput!){ 
  vaultPaymentMethod(input: $input) {
    paymentMethod {
      id
      legacyId
      details {
        ... on VenmoAccountDetails{
          username
          venmoUserId
        }
      }
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method"
  }
}

response

{
  "data": {
    "vaultPaymentMethod": {
      "paymentMethod": {
        "id": "id_of_payment_method",
        "legacyId": "legacy_id_of_payment_method",
        "details": {
          "username": "username",
          "venmoUserId": "id_of_venmo_user"
        },
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

You can also save the customer's Venmo account to your Vault during your transaction by using chargePaymentMethod or chargeVenmoAccount and passing vaulstPaymentMethodAfterTransacting in the input.

Deleting a Vaulted Payment Method

If a customer deletes a vaulted Venmo payment method on a merchant website or app, it will also delete the Venmo customer's merchant connection within their Venmo app on the Connected Businesses page. However, if your Vault has duplicate payment methods for the same Venmo account, the merchant connection will not be deleted until the last payment method is deleted.

Remember that a Venmo customer can delete a merchant connection from within their Venmo app at anytime. This will automatically remove the Venmo payment method from the merchant's Vault.

Authorization

To authorize an eligible Venmo account, use the authorizeVenmoAccount mutation. This mutation will return a transaction payload, and the success of the authorization can be seen by using the status field.

mutation

mutation AuthorizeVenmoAccount($input: AuthorizeVenmoAccountInput!){
  authorizeVenmoAccount(input: $input){
    transaction{
      id
      legacyId
      amount{
        value
        currencyCode
      }
      status
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": 15.00
    }
  }
}

response

{
  "data": {
    "authorizeVenmoAccount": {
      "transaction": {
        "id": "id_of_transaction",
        "legacyId": "legacy_id_of_transaction",
        "amount": {
          "value": "15.00",
          "currencyCode": "USD"
        },
        "status": "AUTHORIZED"
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Creating transactions

Creating a Venmo transaction is the same as creating any other transaction with a payment method. Be sure to pass the device data you collected on the client side when you create the transaction.

You can create a Venmo transaction using the chargePaymentMethod mutation while supplying an amount and paymentMethodId.

mutation

mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) {
  chargePaymentMethod(input: $input) {
    transaction {
      id
      legacyId
      status
      paymentMethodSnapshot{
        ... on VenmoAccountDetails {
          username
          venmoUserId
        }
      }
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "1.00",
    }
  }
}

response

{
  "data": {
    "chargePaymentMethod": {
      "transaction": {
        "id": "id_of_transaction",
        "legacyId": "legacy_id_of_transaction"
        "status": "SUBMITTED_FOR_SETTLEMENT",
        "paymentMethodSnapshot": {
          "username": "username",
          "venmoUserId": "id_of_venmo_user"
        }
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Specifying the business profile

If you want to specify a business associated with a Venmo transaction, use the chargeVenmoAccount mutation. Specify the business profile by passing the profileId associated with the Venmo business profile that you want to create the transaction for. This should be the same profileId used when tokenizing the Venmo account on the client side. If you don't pass a profileId, the transaction will be associated with the default business profile.

mutation

mutation ChargeVenmoAccount($input: ChargeVenmoAccountInput!){ 
  chargeVenmoAccount(input: $input) {
    transaction {
      id
      legacyId
      amount {
        value
        currencyCode
      }
      paymentMethodSnapshot {
        ...on VenmoAccountDetails{
          username
          venmoUserId
        }
      }
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "10.00",
    },
    "options":{
      "profileId": "id_of_profile"
    } 
  }
}

response

{
  "data": {
    "chargeVenmoAccount": {
      "transaction": {
        "id": "id_of_transaction",
        "legacyId": "legacy_id_of_transaction",
        "amount": {
          "value": "10.00",
          "currencyCode": "USD"
        },
        "paymentMethodSnapshot": {
          "username": "username",
          "venmoUserId": "id_of_venmo_user"
        }
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Settlement

Capturing multiple partial amounts against the same authorization

If you send physical goods to customers in multiple shipments, you can capture the total authorized amount across multiple partial settlements using partialCaptureTransaction.