PayPal Commerce Platform gateway guide
Quick Start
New to integrating PayPal Commerce Platform with Spreedly? Here's your setup guide:
- Retrieve your PayPal Commerce Platform credentials
- Log in to the PayPal Dashboard.
- Navigate to My Apps & Credentials.
- Select the application you want to enable with Spreedly.
- Copy the Client ID and Secret.
- You will use the Client ID as login and the Secret as password when creating the gateway.
- Get familiar with the Spreedly API
- Review Spreedly API basics
- Understand the core concepts: Gateways, Payment Methods, and Transactions
- Add PayPal Commerce Platform gateway to Spreedly in sandbox mode
OAuth 2.0 authentication: PayPal Commerce Platform requests authenticate to PayPal using OAuth 2.0 access tokens instead of Basic auth. Spreedly generates the access token from the existing REST Client ID and Secret credentials via PayPal’s /v1/oauth2/token endpoint, so merchants do not need to create new credentials or complete additional setup.
The OAuth 2.0 access token is used for PayPal Commerce Platform API requests, including PayPal Wallet and Venmo wallet payment methods. This behaviour is supported by PayPal for both wallets. Reference: PayPal REST authentication documentation.
Review this documentation to understand more about how to test transactions.
| Additional notes |
|---|
The Spreedly integration to the PayPal Commerce Platform supports two primary transaction paths: Spreedly offsite payment flow, where a customer uses a payment method stored at PayPal Direct credit card transactions using a payment method stored in Spreedly's vault In both cases, work with your PayPal account manager to verify your account is configured correctly. This may include enabling support for raw card payment data. If you want a customer's billing address returned in gateway responses, PayPal must enable that feature. Without it, certain gateway-specific response fields cannot be populated. |
Google Pay support is limited to
CRYPTOGRAM_3DS.PAN_ONLYis not supported, and PayPal Commerce Platform does not support Global 3DS for this flow.
Adding a PayPal Commerce Platform Gateway
Required credentials
login: PayPal Client ID
password: PayPal Secret
Request
curl https://core.spreedly.com/v1/gateways.xml \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/xml' \
-d '<gateway>
<gateway_type>paypal_commerce_platform</gateway_type>
<login>client id</login>
<password>secret</password>
</gateway>'Response
<gateway>
<token>YovvB1bIN56lvJedMbTBiqGgXYZ</token>
<gateway_type>paypal_commerce_platform</gateway_type>
<name>PayPal Commerce Platform</name>
<login>client id</login>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_partial_capture type="boolean">true</supports_partial_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_partial_credit type="boolean">true</supports_partial_credit>
<supports_general_credit type="boolean">true</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_verify type="boolean">true</supports_verify>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">true</supports_remove>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
<supports_inquire_by_gateway_transaction_id type="boolean">true</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">true</supports_inquire_by_order_id>
<supports_stored_credentials type="boolean">true</supports_stored_credentials>
<supports_transaction_retry type="boolean">true</supports_transaction_retry>
</characteristics>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>google_pay</payment_method>
<payment_method>paypal</payment_method>
<payment_method>third_party_token</payment_method>
</payment_methods>
<state>retained</state>
</gateway>Add your Client ID to login and your Secret to password. Use your sandbox credentials when creating a test gateway.
Purchase
Request
curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "payment_method_token",
"amount": 100,
"currency_code": "USD"
}
}'Authorize
Request
curl https://core.spreedly.com/v1/gateways/[gateway_token]/authorize.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "payment_method_token",
"amount": 500,
"currency_code": "USD"
}
}'Capture
Request
curl https://core.spreedly.com/v1/transactions/[authorization_token]/capture.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"amount": 500,
"currency_code": "USD"
}
}'Void
Request
curl https://core.spreedly.com/v1/transactions/[authorization_token]/void.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{}'Credit (Refund)
Request
curl https://core.spreedly.com/v1/transactions/[purchase_or_capture_token]/credit.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"amount": 100,
"currency_code": "USD"
}
}'Google Pay
PayPal Commerce Platform supports Google Pay for Purchase and Authorize when the payment method uses CRYPTOGRAM_3DS. PAN_ONLY is not supported. Because this gateway does not support Global 3DS, PAN-only Google Pay cannot be used here. Stored credentials are not supported with Google Pay payment methods.
Request
curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "google_pay_cryptogram_payment_method_token",
"amount": 100,
"currency_code": "USD",
"billing_address": {
"address1": "123 Main Street",
"city": "San Jose",
"state": "CA",
"zip": "95131",
"country": "US"
}
}
}'Apple Pay
PayPal Commerce Platform supports Apple Pay for Purchase and Authorize. Stored credentials are supported with Apple Pay payment methods.
Request
curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "apple_pay_payment_method_token",
"amount": 100,
"currency_code": "USD",
"billing_address": {
"address1": "123 Main Street",
"city": "San Jose",
"state": "CA",
"zip": "95131",
"country": "US"
}
}
}'Network Token
PayPal Commerce Platform supports network tokens for Purchase and Authorize when the payment method has a provisioned network token and the request includes attempt_network_token. Store is not supported with network token payment methods.
Request
curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "payment_method_token",
"amount": 100,
"currency_code": "USD",
"attempt_network_token": true
}
}'Store / Remove
Third-party vaulting
The PayPal Commerce Platform gateway supports storing a payment method directly with PayPal using PayPal's Vault API. Once stored, you can reuse the resulting PayPal vault token for future transactions without resending the original card number.
Storing a payment method
To create a PayPal vault token, call store on a retained payment method through the PPCP gateway:
curl https://core.spreedly.com/v1/gateways/{gateway_token}/store.json \
-u 'your_environment_key:your_access_secret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "{payment_method_token}"
}
}'A successful store request returns a new Spreedly payment method with payment_method_type of third_party_token, associated with the PPCP gateway. Use transaction.payment_method.token from the store response as the payment method token for later purchase, authorize, and redact calls. This token represents the card stored in PayPal's vault.
Using a stored third-party token
Reference the third_party_token payment method (transaction.payment_method.token from store) in place of the original payment method on any supported transaction
curl https://core.spreedly.com/v1/gateways/{gateway_token}/purchase.json \
-u 'your_environment_key:your_access_secret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"amount": 1000,
"currency_code": "USD",
"payment_method_token": "{third_party_token}"
}
}'Spreedly sends the PayPal vault token to PayPal's Orders v2 API as payment_source.card.vault_id.
Removing a stored payment method
To delete the corresponding PayPal vault token, redact the third_party_token payment method and include remove_from_gateway
curl https://core.spreedly.com/v1/payment_methods/{third_party_token}/redact.json \
-u 'your_environment_key:your_access_secret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"remove_from_gateway": "{gateway_token}"
}
}'Inquire / Sync
PayPal Commerce Platform is only partly async. Sync/Inquire is mainly useful for unvaulted PayPal and Venmo offsite transactions, and for General Credit payouts that are still pending or processing.
Card, Google Pay, Apple Pay, capture, refund, and void usually complete on the first Spreedly response, so they should not be expected to support Sync/Inquire. Void has no pending state.
Webhooks
PayPal Orders v2 does not use per-order IPN or notify_url. PPCP completion is handled through redirect plus API calls. Spreedly does not currently process PPCP REST webhooks.
What Sync/Inquire supports
- Supported: offsite PayPal or Venmo purchase/authorize when Spreedly has the PayPal order ID.
- Supported: General Credit payouts when Spreedly has the payout batch ID.
- Not supported: card, Google Pay, Apple Pay purchase/authorize, Capture, and Void.
Pending and error behaviour
If the buyer approval or payout is still pending, Inquire returns pending: true and the transaction moves from pending to processing.
If PayPal returns RESOURCE_NOT_FOUND, or if Sync/Inquire is used for an unsupported transaction, the transaction can currently fail instead of staying unchanged.
Use Sync/Inquire only for supported offsite PayPal/Venmo flows and General Credit payouts. For most other PPCP transactions, the first Spreedly response is the final result.
Partial Capture
Use gateway-specific field final_capture to control whether more captures are expected.
Set false when additional captures will follow
Use true, or omit the field, on the final capture
Authorizations expire, and a single capture cannot exceed 115% of the original authorized amount.
Request: partial capture
curl https://core.spreedly.com/v1/transactions/[authorization_token]/capture.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"amount": 300,
"currency_code": "USD",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"final_capture": false
}
}
}
}'Request: final capture
curl https://core.spreedly.com/v1/transactions/[authorization_token]/capture.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"amount": 200,
"currency_code": "USD",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"final_capture": true
}
}
}
}'Example flow: authorize 5.00 USD, capture 3.00 USD with final_capture: false, then capture 2.00 USD with final_capture: true.
Idempotent Requests
Pass gateway-specific field paypal_request_id, ideally as a UUID. Spreedly forwards this value as the PayPal-Request-Id header.
Supported operations include Purchase, Authorize, Capture, Credit, and Void.
curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "payment_method_token",
"amount": 2800,
"currency_code": "USD",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"paypal_request_id": "a1b2c3d4-e5f6-7890-abcd-ef123456xyz0"
}
}
}
}'- Using the same key with the same payload should return the same
gateway_transaction_id - If the payload changes, use a new idempotency key
Payouts via General Credit
General Credit can be used for PayPal payouts.
Required gateway-specific fields
recipient_type: EMAIL, PHONE,orPAYPAL_IDrecipient_wallet: PAYPAL, VENMO,orRECIPIENT_SELECTEDreference_idemail_subjectemail_message
If a PayPal payout remains pending, Spreedly may keep the General Credit transaction pending until an inquire call resolves the final status.
Stored Credentials
For recurring or merchant-initiated usage patterns, include stored credential fields on Purchase or Authorize requests.
stored_credential_initiatorstored_credential_reason_type
curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
-u 'EnvironmentKey:AccessSecret' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "payment_method_token",
"amount": 100,
"currency_code": "USD",
"stored_credential_initiator": "cardholder",
"stored_credential_reason_type": "recurring"
}
}'Gateway Specific Fields
| Field Name | Type | Required | Use Case | Example |
|---|---|---|---|---|
paypal_request_id | String | No | Idempotency key | UUID value |
final_capture | Boolean | No | Marks whether a partial capture is final | false |
verification_method | String | No | Controls verification behavior | SCA_WHEN_REQUIRED |
recipient_type | String | Yes for payouts | Identifies the payout recipient type | EMAIL |
recipient_wallet | String | Yes for payouts | Identifies the payout wallet destination | PAYPAL |
reference_id | String | No | Merchant reference for payouts | general_credit_2020_100007 |
email_subject | String | Yes for payouts | Subject line for payout notification | You have a payout! |
email_message | String | Yes for payouts | Message body for payout notification | Thanks for using our service! |
payee | Hash/Object | No | Identifies the merchant who receives the funds and fulfills the order | { "merchant_id": "ABCD1234", "email": "[email protected]" } |
Existing nested fields may also apply, including purchase_units, application_context, airline_data, order_only, and uuid. For more information and examples, please refer to the Paypal developer documentation.
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
<gateway_specific_fields>
<paypal_commerce_platform>
<paypal_request_id>123abcde</paypal_request_id>
<final_capture>true</final_capture>
<verification_method>SCA_WHEN_REQUIRED</verification_method>
<recipient_type>[email protected]</recipient_type>
<recipient_wallet>paypal</recipient_wallet>
<reference_id>general_credit_2020_100007</reference_id>
<email_subject>You have a payout!</email_subject>
<email_message>Thanks for using our service!</email_message>
<payee>
<merchant_id>ABCDEF12345</merchant_id>
<email>[email protected]</email>
</payee>
</paypal_commerce_platform>
</gateway_specific_fields>
</transaction>'Gateway Specific Response Fields
Offsite responses can include buyer and address information when enabled on the PayPal account. Possible fields include payer, first_name, last_name, billing and shipping address values, email, merchant_id, national_number, and issue for errors.
Additional resources
If you need support with this gateway, please contact Support at [email protected].
PayPal Commerce Platform documentation: PayPal developer documentation
API Endpoint: https://api.paypal.com (Production)
Test Endpoint: https://api-m.sandbox.paypal.com (Test)
Local Payment Methods
Spreedly supports PayPal and Venmo wallets on the PayPal Commerce Platform (PPCP). Each uses offsite buyer approval for unvaulted payment methods, optional vaulting, and server-side purchase or authorize when the payment method reference is vault#…. Expand each payment method for request and response samples.
All examples use HTTP Basic authentication (environment key as username, access secret as password) against https://core.spreedly.com. Offsite flows require redirect_url and callback_url.
PayPal wallet
PayPal wallet
PayPal wallet payments use payment method type paypal. Unvaulted wallets run as OffsitePurchase or OffsiteAuthorization (buyer approves at PayPal). After vaulting, the payment method reference is vault#<id> and subsequent charges are inline Purchase or Authorization (no checkout_url).
Key capabilities
- Offsite purchase and authorize (unvaulted)
- Wallet vault without purchase (
verifyon the gateway) - Vault with purchase via gateway specific field
vault - Server-side charges and MIT/recurring on vaulted wallets
- PayPal Mobile Checkout SDK v3 (
funding_source,sdk_session,client_metadata_id)
Create PayPal payment method
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{environment_key}}
Password {{access_secret}}{
"payment_method": {
"payment_method_type": "paypal",
"email": "[email protected]",
"retained": true
}
}{
"payment_method": {
"token": "01ABCDEF...",
"payment_method_type": "paypal",
"email": "[email protected]",
"reference": null,
"storage_state": "retained"
}
}Offsite purchase (unvaulted)
POST /v1/gateways/{gateway_token}/purchase.json{
"transaction": {
"payment_method_token": "{{paypal_payment_method_token}}",
"amount": 1000,
"currency_code": "USD",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"application_context": {
"brand_name": "Example Merchant",
"shipping_preference": "NO_SHIPPING",
"user_action": "PAY_NOW"
}
}
}
}
}{
"transaction": {
"state": "pending",
"transaction_type": "OffsitePurchase",
"checkout_url": "https://www.sandbox.paypal.com/checkoutnow?token=ORDER_ID",
"setup_verification": "ORDER_ID"
}
}Redirect the buyer to checkout_url. After approval, Spreedly completes the transaction via your redirect_url / callback_url flow.
Offsite authorize (unvaulted)
POST /v1/gateways/{gateway_token}/authorize.json{
"transaction": {
"payment_method_token": "{{paypal_payment_method_token}}",
"amount": 10000,
"currency_code": "USD",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"application_context": {
"shipping_preference": "GET_FROM_FILE",
"user_action": "CONTINUE"
}
}
}
}
}Wallet vault without purchase (offsite verify)
Vault a PayPal wallet without charging by calling gateway verify on an unvaulted PayPal payment method (not smart-routing inline verify). Spreedly returns a PayPal Vault setup checkout_url; after buyer approval the payment method reference becomes vault#<id>.
POST /v1/gateways/{gateway_token}/verify.json{
"transaction": {
"payment_method_token": "{{paypal_payment_method_token}}",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"retain_on_success": true,
"gateway_specific_fields": {
"paypal_commerce_platform": {
"application_context": {
"brand_name": "Example Merchant",
"locale": "en-US",
"shipping_preference": "NO_SHIPPING",
"user_action": "CONTINUE"
}
}
}
}
}{
"transaction": {
"state": "pending",
"transaction_type": "OffsiteVerification",
"checkout_url": "https://sandbox.paypal.com/agreements/approve?approval_session_id=SETUP_TOKEN_ID",
"setup_verification": "SETUP_TOKEN_ID"
}
}{
"transaction": {
"state": "succeeded",
"transaction_type": "OffsiteVerification",
"payment_method": {
"payment_method_type": "paypal",
"reference": "vault#jwgvx42"
}
}
}Vault with purchase
On an offsite purchase or authorize, set vault.store_in_vault to ON_SUCCESS so PayPal vaults the wallet when the payment succeeds. You may pass a vault object or the shorthand "vault": true (equivalent to ON_SUCCESS / MERCHANT).
{
"transaction": {
"payment_method_token": "{{paypal_payment_method_token}}",
"amount": 2000,
"currency_code": "USD",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"retain_on_success": true,
"gateway_specific_fields": {
"paypal_commerce_platform": {
"vault": {
"store_in_vault": "ON_SUCCESS",
"usage_type": "MERCHANT"
},
"application_context": {
"shipping_preference": "NO_SHIPPING",
"user_action": "PAY_NOW"
}
}
}
}
}Charge a vaulted PayPal wallet
When reference is vault#…, purchase or authorize without redirect URLs.
{
"transaction": {
"payment_method_token": "{{vaulted_paypal_payment_method_token}}",
"amount": 1000,
"currency_code": "USD"
}
}{
"transaction": {
"succeeded": true,
"state": "succeeded",
"transaction_type": "Purchase",
"message": "Succeeded!"
}
}PayPal receives a create-order call, then capture or authorize with payment_source.paypal.vault_id.
MIT / recurring (vaulted wallet)
{
"transaction": {
"payment_method_token": "{{vaulted_paypal_payment_method_token}}",
"amount": 1500,
"currency_code": "USD",
"stored_credential_initiator": "merchant",
"stored_credential_reason_type": "recurring",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"usage_pattern": "RECURRING_POSTPAID"
}
}
}
}See Stored credentials for additional stored-credential fields.
PayPal Mobile Checkout SDK v3
For mobile integrations, use gateway specific fields:
funding_source:PAYPAL,PAY_LATER, orCREDITsdk_session: true— Spreedly omits return/cancel URL overrides on PayPal create-order; complete approval in the SDK and use the Confirm API when the buyer does not return through a browser URLclient_metadata_id— sent asPayPal-Client-Metadata-Idon create-order and capture/authorize
{
"transaction": {
"amount": 1000,
"currency_code": "USD",
"payment_method_token": "{{paypal_payment_method_token}}",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"funding_source": "PAYPAL",
"sdk_session": true,
"client_metadata_id": "cmid-from-mobile",
"application_context": {
"brand_name": "Example Merchant",
"shipping_preference": "NO_SHIPPING",
"user_action": "PAY_NOW"
}
}
}
}
}Venmo wallet
Venmo wallet
Venmo wallet payments use payment method type venmo. Unvaulted Venmo always routes to offsite purchase or authorize; checkout_url includes fundingSource=venmo. After vaulting, charges use payment_source.venmo.vault_id.
Key capabilities
- Offsite purchase and authorize (unvaulted)
- Wallet vault without purchase (
verify) - Vault with purchase via gateway specific field
vault - Server-side charges and MIT/recurring on vaulted wallets
- Venmo app-switch URLs when using
sdk_session
Create Venmo payment method
POST /v1/payment_methods.json{
"payment_method": {
"payment_method_type": "venmo",
"email": "[email protected]",
"retained": true,
"offsite_sync": false
}
}{
"payment_method": {
"token": "01ABCDEF...",
"payment_method_type": "venmo",
"email": "[email protected]",
"reference": null,
"storage_state": "retained"
}
}Offsite purchase (unvaulted)
POST /v1/gateways/{gateway_token}/purchase.json{
"transaction": {
"payment_method_token": "{{venmo_payment_method_token}}",
"amount": 1000,
"currency_code": "USD",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"retain_on_success": true,
"gateway_specific_fields": {
"paypal_commerce_platform": {
"application_context": {
"brand_name": "Example Merchant",
"shipping_preference": "NO_SHIPPING",
"user_action": "PAY_NOW"
}
}
}
}
}{
"transaction": {
"state": "pending",
"transaction_type": "OffsitePurchase",
"checkout_url": "https://www.sandbox.paypal.com/checkoutnow?token=ORDER_ID&fundingSource=venmo",
"setup_verification": "ORDER_ID"
}
}Offsite authorize (unvaulted)
Use the same shape as offsite purchase with authorize.json and user_action: CONTINUE when appropriate.
Wallet vault without purchase (offsite verify)
POST /v1/gateways/{gateway_token}/verify.json{
"transaction": {
"payment_method_token": "{{venmo_payment_method_token}}",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"application_context": {
"brand_name": "Example Merchant",
"locale": "en-US",
"shipping_preference": "NO_SHIPPING"
}
}
}
}
}After buyer approval, confirm reference is vault#…. If you use sdk_session: true and the buyer does not return via a browser URL, complete the flow with POST /v1/transactions/{token}/confirm.json and {"state":"Successful"}.
Vault with purchase
{
"transaction": {
"payment_method_token": "{{venmo_payment_method_token}}",
"amount": 1000,
"currency_code": "USD",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"retain_on_success": true,
"gateway_specific_fields": {
"paypal_commerce_platform": {
"vault": {
"store_in_vault": "ON_SUCCESS",
"usage_type": "MERCHANT"
},
"application_context": {
"shipping_preference": "NO_SHIPPING",
"user_action": "PAY_NOW"
}
}
}
}
}Charge a vaulted Venmo wallet
{
"transaction": {
"payment_method_token": "{{vaulted_venmo_payment_method_token}}",
"amount": 1000,
"currency_code": "USD"
}
}PayPal receives create-order (order only), then capture with {"payment_source":{"venmo":{"vault_id":"…"}}}.
MIT / recurring (vaulted Venmo)
{
"transaction": {
"payment_method_token": "{{vaulted_venmo_payment_method_token}}",
"amount": 1500,
"currency_code": "USD",
"stored_credential_initiator": "merchant",
"stored_credential_reason_type": "recurring",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"usage_pattern": "RECURRING_POSTPAID"
}
}
}
}Venmo Mobile Checkout SDK v3
Unlike PayPal wallet, sdk_session: true does not omit Venmo return/cancel URLs. Pass app-switch URLs when needed. Do not set funding_source to venmo; Venmo is implied by the Venmo payment method type.
{
"transaction": {
"amount": 1000,
"currency_code": "USD",
"payment_method_token": "{{venmo_payment_method_token}}",
"redirect_url": "https://merchant.example.com/return",
"callback_url": "https://merchant.example.com/callback",
"gateway_specific_fields": {
"paypal_commerce_platform": {
"sdk_session": true,
"client_metadata_id": "cmid-from-mobile",
"return_url": "com.merchant.app://paypal-return",
"cancel_url": "com.merchant.app://paypal-cancel"
}
}
}
}Updated 5 days ago

