PayPal

PayPal is a digital wallet that enables buyers to pay using their PayPal balance, bank accounts, or cards. PayPal also offers card acquiring, which processes credit and debit card payments directly, and Venmo for buyers in the United States.

​

Supported payment methods

Integration shows how the buyer pays:

• Direct: you send card or bank account details through Gr4vy, using Embed, Secure Fields, or the API. Gr4vy stores bank accounts. See Bank payments.
• Redirect: the buyer completes the payment on the provider’s page, and the provider keeps their details.
• Redirect or SDK: as redirect, or you can use the provider’s own SDK or components in place of the redirect. See the method’s page.

​

Setup

PayPal provides a self-service sign-up for a sandbox account. To sign up for an account visit the sign-up page and fill in the details, ensuring to choose Business Account when prompted.

​

Credentials

When setting up PayPal in the dashboard, configure the following credentials, which are obtained from PayPal:

• Client ID: Find this in the PayPal Developer Portal under Apps & Credentials -> REST API Apps -> Your App.
• Client secret: Find this in the PayPal Developer Portal under Apps & Credentials -> REST API Apps -> Your App.
• Webhook ID: The ID PayPal returns when you create the webhook for this connection. Gr4vy uses it to verify incoming webhooks. See Webhooks.
• BN code: Optional field that identifies the integration partner to PayPal. Use your own value if you are already an integration partner.
• Merchant ID: Find this in the PayPal Merchant Dashboard under Account settings -> Business Information. See Merchant ID for how Gr4vy uses it.

​

Merchant ID

Gr4vy uses the Merchant ID in two places:

• Client SDKs: Gr4vy returns it as merchantId in the session data for direct integrations, so you can pass it to PayPal’s JavaScript and mobile SDKs.
• Set Transaction Context: Gr4vy needs it to send the additional_data connection option to PayPal as Set Transaction Context (STC) values. A transaction with additional_data fails when the Merchant ID is empty.

Gr4vy doesn’t send the Merchant ID as the payee of an order. Payments are created for, and settle to, the PayPal account that owns the client ID and client secret. Partner and multiparty setups, where one PayPal account takes payments on behalf of other PayPal accounts, aren’t supported.

​

Webhooks

PayPal reports payment updates and stored PayPal accounts to Gr4vy through webhooks. Set up a webhook for every PayPal account you connect, before you go live.

1. In the Gr4vy dashboard, go to Connections -> Configured connections, select your PayPal connection, then scroll to the Synchronization section and copy the webhook URL. Each connection has its own URL.
2. In the PayPal Developer Dashboard, open Apps & Credentials, select the app whose client ID the connection uses, and add a webhook with that URL.
3. Subscribe the webhook to all events, or at least to the events in the list below.
4. Copy the webhook ID that PayPal shows and enter it as the connection’s Webhook ID. Gr4vy ignores events it can’t verify with this ID.

The PayPal connectors handle the following events:

• CHECKOUT.ORDER.APPROVED
• PAYMENT.AUTHORIZATION.CREATED
• PAYMENT.AUTHORIZATION.VOIDED
• PAYMENT.CAPTURE.COMPLETED
• PAYMENT.CAPTURE.DECLINED
• PAYMENT.CAPTURE.DENIED
• PAYMENT.CAPTURE.REFUNDED
• VAULT.PAYMENT-TOKEN.CREATED
• VAULT.PAYMENT-TOKEN.DELETED
• VAULT.PAYMENT-TOKEN.DELETION-INITIATED

When PayPal reports that a stored account was removed, through VAULT.PAYMENT-TOKEN.DELETION-INITIATED or VAULT.PAYMENT-TOKEN.DELETED, Gr4vy deletes the payment method and sends a payment-method.deleted webhook.