PayPal Direct Mode — Post-authorization data
What each API returns after PayPal buyer approval in Gr4vy PayPal Direct Mode, how fields map, and when the merchant needs PayPal client secret vs Gr4vy credentials alone.
Prerequisite: How Gr4vy PayPal Direct Mode works
For pre-Gr4vy fraud (PayPal GET before Gr4vy complete), see Pre-Gr4vy fraud — PayPal timing.
Executive summary
| Question | Answer |
|---|---|
After a successful Direct Mode payment, is Gr4vy GET /transactions/{id} enough for reconciliation? | Yes. Status, amount, PayPal order id, authorization id, payer id, buyer email, and shipping are present after the completion handshake. |
| Does the merchant need PayPal client secret to finalize Direct Mode? | No. Finalize uses Gr4vy merchant auth + GET default_completion_url + GET /transactions/{id}. |
| When is PayPal client secret required? | Only when the merchant backend calls PayPal REST directly — e.g. GET /v2/checkout/orders/{id}, authorization void, order PATCH, or pre-complete fraud enrichment. |
| Browser PayPal SDK | Public clientId from Gr4vy session_data only. Secret must never be used in the browser. |
Post-approve flow
Gr4vy GET /transactions/{id} (after complete)
Representative fields after the completion handshake:
| Field | Example | Gr4vy JSON path |
|---|---|---|
| Gr4vy transaction id | c58b5863-7243-4ce3-aa4f-4dca6ec1beac | id |
| Status | authorization_succeeded | status |
| Amount | 1000 (minor = $10.00) | amount |
| PayPal order id | 46S52514Y7950482F | payment_service_transaction_id, additional_identifiers.payment_service_processor_id |
| PayPal authorization id | 48R58639WC2361713 | additional_identifiers.payment_service_authorization_id |
| PayPal payer id | EZTGT5S4DBD82 | additional_identifiers.payer_id |
| Buyer email | sb-fa43tz49039152@personal.example.com | buyer.billing_details.email_address |
| Shipping | John Doe, San Jose CA | shipping_details.* |
Auth: Gr4vy merchant JWT. No PayPal client secret.
Quirks
raw_response_code: "PAYER_ACTION_REQUIRED"can remain even whenstatusisauthorization_succeeded— connector metadata, not a failed auth.buyer.billing_details.addressmay be sparse; fulfillment address is usually onshipping_details.- One
GET /transactions/{id}after complete is enough for that transaction id.
PayPal GET /v2/checkout/orders/{id}
Endpoint: GET https://api-m.sandbox.paypal.com/v2/checkout/orders/{orderId}
Auth: OAuth client_credentials — client id + secret on the merchant server only.
Field mapping (Gr4vy vs PayPal)
| Item | PayPal path | Gr4vy path |
|---|---|---|
| Order id | id | payment_service_transaction_id |
| Authorization id | purchase_units[0].payments.authorizations[0].id | additional_identifiers.payment_service_authorization_id |
| Payer id | payer.payer_id | additional_identifiers.payer_id |
| Buyer email | payer.email_address | buyer.billing_details.email_address |
| Amount | purchase_units[0].amount.value (major) | amount (minor) |
| Shipping | purchase_units[0].shipping.* | shipping_details.* |
PayPal-only fields (not on Gr4vy)
| PayPal path | Notes |
|---|---|
purchase_units[0].payments.authorizations[0].seller_protection.* | Seller protection eligibility |
purchase_units[0].payments.authorizations[0].links[] | HATEOAS capture / void URLs |
purchase_units[0].payee.merchant_id | PayPal merchant id |
For OMS after complete, Gr4vy GET is usually sufficient. PayPal GET adds value for fraud before complete and PayPal-native fields (seller protection, void links).
PayPal client secret — when required
| Use case | PayPal client secret? |
|---|---|
| Gr4vy finalize (completion URL + Gr4vy GET) | No |
| Gr4vy transaction status / reconciliation | No |
| PayPal JS SDK in browser | No |
PayPal REST GET /v2/checkout/orders/{id} | Yes |
| Post-approve fraud before Gr4vy complete | Yes |
| PayPal auth void on fraud decline (fallback) | Yes |
| Merchant-created PayPal orders (create / PATCH) | Yes |
OAuth pattern:
POST {PAYPAL_API_BASE}/v1/oauth2/tokenwithAuthorization: Basic base64(clientId:clientSecret)andgrant_type=client_credentials.- Call PayPal APIs with
Authorization: Bearer {access_token}.
Gr4vy’s connector uses its own PayPal credentials for orchestration. The merchant’s client secret is only for direct PayPal REST calls from the merchant backend.
Which API to use when
| Goal | Use | Why |
|---|---|---|
| Mark order paid after Direct Mode complete | Gr4vy GET | Canonical PSP status; buyer, shipping, PayPal ids |
| Fraud before Gr4vy complete | PayPal GET | At onApprove, Gr4vy may still be buyer_approval_pending |
| Fraud / OMS after complete | Gr4vy GET | Terminal status and enriched buyer/shipping |
| Void on fraud decline | Gr4vy void first; PayPal auth void fallback | — |
| Side-by-side debugging | Both | Compare order id, auth id, amount, email |
State split around onApprove
| System | At onApprove | After completion handshake |
|---|---|---|
| PayPal order | APPROVED or COMPLETED | COMPLETED with authorization id |
| Gr4vy transaction | buyer_approval_pending | authorization_succeeded (authorize intent) |
| Timing | Gr4vy GET | PayPal GET |
|---|---|---|
After onApprove, before complete | Sparse; status often pending | Primary for fraud enrichment |
| After complete | Fully enriched | Largely redundant for OMS; useful for PayPal-only fields |
Post-complete Gr4vy GET is sufficient for OMS/reconciliation for standard Direct Mode fields.