PayPal

​

At a glance

npx @deploybaseline/cli start --service paypal

import { createEmulator } from "@deploybaseline/cli";

const paypal = await createEmulator({ service: "paypal" });
// paypal.url is http://localhost:4000

{
  "paypal": {
    "apps": [
      {
        "name": "My store",
        "client_id": "baseline-paypal-client-id",
        "client_secret": "baseline-paypal-client-secret",
        "brand_name": "Baseline Store",
        "webhooks": [
          {
            "url": "http://localhost:3000/api/paypal/webhook",
            "event_types": ["*"]
          }
        ]
      }
    ],
    "buyers": [
      {
        "email": "[email protected]",
        "name": "John Doe"
      },
      {
        "email": "[email protected]",
        "name": "Dee Clined",
        "fail_with": "INSTRUMENT_DECLINED"
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service paypal

import { Client, Environment, OrdersController, CheckoutPaymentIntent } from "@paypal/paypal-server-sdk";

const emulator = new URL(process.env.PAYPAL_EMULATOR_URL!);
const client = new Client({
  clientCredentialsAuthCredentials: {
    oAuthClientId: "baseline-paypal-client-id",
    oAuthClientSecret: "baseline-paypal-client-secret",
  },
  environment: Environment.Sandbox,
  unstable_httpClientOptions: {
    adapter: "fetch",
    env: {
      fetch: async (input: string | URL | Request, init?: RequestInit) => {
        const url = new URL(input instanceof Request ? input.url : String(input));
        url.protocol = emulator.protocol;
        url.host = emulator.host;
        if (!(input instanceof Request)) return fetch(url, init);
        const body = input.body ? await input.arrayBuffer() : undefined;
        return fetch(url, { method: input.method, headers: input.headers, body });
      },
    },
  },
});

const orders = new OrdersController(client);
const { result } = await orders.createOrder({
  body: {
    intent: CheckoutPaymentIntent.Capture,
    purchaseUnits: [{ amount: { currencyCode: "USD", value: "100.00" } }],
  },
});

​

URL mapping

​

Auth

• POST /v1/oauth2/token — Get access token: HTTP Basic client_id:client_secret and grant_type=client_credentials (form or JSON)
• POST /v1/oauth2/token/terminate — Revoke access token: token=<access token>

• A wrong client id or secret answers 401 {"error":"invalid_client","error_description":"Client Authentication failed"}.
• A missing grant type answers 400 unsupported_grant_type (Grant Type is NULL).
• An API call without a bearer token answers 401 AUTHENTICATION_FAILURE. An unknown or revoked token answers 401 {"error":"invalid_token","error_description":"Token signature verification failed"}, and an expired one Access Token expired.
• A token without a scope the call needs answers 403 NOT_AUTHORIZED with PERMISSION_DENIED, as does reading another app’s order or payment.
• A bearer token the Baseline CLI was started with acts as the first app with all of its scopes.

​

Orders v2

• POST /v2/checkout/orders — Create order: intent CAPTURE or AUTHORIZE and one to ten purchase_units. Amounts are checked as PayPal does: value syntax, currency decimals (JPY, HUF, and TWD take none), amount.breakdown against the total (AMOUNT_MISMATCH), items against item_total and tax_total (ITEM_TOTAL_MISMATCH, TAX_TOTAL_MISMATCH), one currency per unit, unique reference_ids when there are several units.
• payment_source.paypal (with experience_context: return_url, cancel_url, brand_name, user_action, shipping_preference) makes the order PAYER_ACTION_REQUIRED with a payer-action link. Without a payment source the order is CREATED with an approve link; application_context is read for the same fields.
• payment_source.card (number, expiry, name) makes the order APPROVED at once. attributes.verification.method of SCA_ALWAYS asks for 3D Secure: the order is PAYER_ACTION_REQUIRED until the buyer completes the step on the hosted page. Expired cards answer CARD_EXPIRED. Other sources answer PAYMENT_SOURCE_NOT_SUPPORTED.
• GET /v2/checkout/orders/{id} — Show order details
• PATCH /v2/checkout/orders/{id} — Update order: a JSON Patch array (add, replace, remove) on /intent, /payer, and purchase unit fields addressed by reference id, such as /purchase_units/@reference_id=='default'/amount, .../shipping/address, .../invoice_id, .../custom_id, .../description, .../items. Other paths answer NOT_PATCHABLE; malformed pointers INVALID_JSON_POINTER_FORMAT. Answers 204.
• POST /v2/checkout/orders/{id}/confirm-payment-source — Confirm payment source: sets a paypal or card source on an order
• POST /v2/checkout/orders/{id}/authorize — Authorize payment for order: this and /capture answer 201 and refuse with ORDER_NOT_APPROVED, ACTION_DOES_NOT_MATCH_INTENT, ORDER_ALREADY_CAPTURED, ORDER_ALREADY_AUTHORIZED, PAYER_ACTION_REQUIRED, or DUPLICATE_INVOICE_ID (another payment of the app already used the invoice id).
• processing_instruction: ORDER_COMPLETE_ON_PAYMENT_APPROVAL captures or authorizes on approval.

​

Hosted approval page

​

Payments v2

• GET /v2/payments/authorizations/{id} — Show authorized payment details. POST .../capture captures all of an authorization or part of it (amount, final_capture), up to ten times, never more than is left (MAX_CAPTURE_AMOUNT_EXCEEDED). Statuses go CREATED, PARTIALLY_CAPTURED, CAPTURED.
• POST .../reauthorize is refused during the three day honor period (REAUTHORIZATION_TOO_SOON) and allows up to 115% of the original amount (at most 75 more in the currency); it returns a new authorization and voids the original. Authorizations expire after 29 days (AUTHORIZATION_EXPIRED).
• POST .../void answers 204 (or 200 with Prefer: return=representation). Voiding the last open authorization of an order with no captures voids the order.
• GET /v2/payments/captures/{id} — Show captured payment details. POST .../refund refunds it, with an optional amount (default: what is left). Refunds may be partial; more than is left answers REFUND_AMOUNT_EXCEEDED, a fully refunded capture CAPTURE_FULLY_REFUNDED, a capture older than 180 days REFUND_TIME_LIMIT_EXCEEDED. Capture statuses go COMPLETED, PARTIALLY_REFUNDED, REFUNDED.
• GET /v2/payments/refunds/{id} — Show refund details

​

Emulator clock

• POST /_paypal/clock/advance — Advance emulator clock: {"seconds": 259200}

​

Deterministic failures

• Negative testing: a PayPal-Mock-Response: {"mock_application_codes":"INSTRUMENT_DECLINED"} header makes the call fail with that issue and changes nothing, as in PayPal’s sandbox. Most codes answer 422 UNPROCESSABLE_ENTITY; INTERNAL_SERVER_ERROR answers 500, PERMISSION_DENIED 403, INVALID_RESOURCE_ID 404, and parameter issues 400. INSTRUMENT_DECLINED on an order adds the redirect link back to the approval page.
• Sandbox buyers: a buyer seeded with fail_with: INSTRUMENT_DECLINED (or any issue) fails every authorize or capture. INSTRUMENT_DECLINED sends the order back to CREATED with a redirect link, so the buyer can pick another account. A buyer with capture_status: PENDING gets PENDING captures (status_details.reason: PENDING_REVIEW).
• Card names: a card whose name is one of PayPal’s test triggers is declined: capturing gives a DECLINED capture and authorizing a DENIED authorization, with its processor response code: CCREJECT-REFUSED (0500), CCREJECT-SF (9500), CCREJECT-EC (5400), CCREJECT-IRC (5180), CCREJECT-IF (5120), CCREJECT-LS (9520), CCREJECT-IA (1330), CCREJECT-BANK_ERROR (5100), CCREJECT-CVV_F (00N7).
• Fault injection: the faults: seed key and the control API add latency or canned responses in front of any route, as for every Baseline service.

​

Webhooks

• POST /v1/notifications/webhooks — Create webhook: url, event_types, up to 10 per app
• DELETE /v1/notifications/webhooks/{id} — Delete webhook: the same path also takes GET, and PATCH to replace /url or /event_types
• GET /v1/notifications/webhooks/{id}/event-types — List event subscriptions for webhook
• GET /v1/notifications/webhooks-event-types — List available events
• GET /v1/notifications/webhooks-events — List event notifications: newest first, page_size, start_time, end_time, event_type, transaction_id, next links
• POST /v1/notifications/simulate-event — Simulate webhook event: sends a sample event of a type to a webhook or URL without keeping it
• POST /v1/notifications/verify-webhook-signature — Verify webhook signature

• The verify endpoint takes auth_algo, cert_url, transmission_id, transmission_sig, transmission_time, webhook_id, and webhook_event and answers {"verification_status":"SUCCESS"} or FAILURE.
• Offline, fetch the PEM certificate at PAYPAL-CERT-URL (served by the emulator at /v1/notifications/certs/{id}, one key per emulator, kept in saved state) and check the signature with it, as PayPal’s own samples do:

import { createVerify, X509Certificate } from "node:crypto";
import { crc32 } from "node:zlib";

const cert = new X509Certificate(await (await fetch(headers["paypal-cert-url"])).text());
const message = `${headers["paypal-transmission-id"]}|${headers["paypal-transmission-time"]}|${webhookId}|${crc32(rawBody) >>> 0}`;
const valid = createVerify("RSA-SHA256").update(message).verify(cert.publicKey, headers["paypal-transmission-sig"], "base64");

​

Seed config

{
  "paypal": {
    "apps": [
      {
        "name": "My store",
        "client_id": "baseline-paypal-client-id",
        "client_secret": "baseline-paypal-client-secret",
        "brand_name": "Baseline Store",
        "webhooks": [
          {
            "url": "http://localhost:3000/api/paypal/webhook",
            "event_types": ["*"]
          }
        ]
      }
    ],
    "buyers": [
      {
        "email": "[email protected]",
        "name": "John Doe"
      },
      {
        "email": "[email protected]",
        "name": "Dee Clined",
        "fail_with": "INSTRUMENT_DECLINED"
      },
      {
        "email": "[email protected]",
        "name": "Rev Hold",
        "capture_status": "PENDING"
      }
    ]
  }
}

• brand_name: shown on the approval page
• merchant_email, merchant_id, and scopes are optional on an app

​

Inspector

​

Limits

• No order tracking, and no SAVED status or vaulting.
• No wallets or alternative payment methods beyond paypal and card payment sources.
• Subscriptions, Invoicing, Payouts, and Disputes are not modeled.

​

Conformance