PayPal Payment Integration

PayPal is a globally recognised e-wallet and alternative payment system that supports instant payments for services and goods. PayPal requires customers to have an account linked to a debit or credit card, offering a one-click checkout experience that removes the need for manual card entry — improving conversion rates for merchants.

Availability

PayPal is accepted globally, except in sanctioned countries and entities.

---

High-level flow

Refer to the Netvalve Hosted Payment Page guide for the full flow diagram.

---

How to offer PayPal

Contact the Netvalve team to enable the PayPal payment option on your Netvalve Hosted Payment Page before going live.

---

Step 1 — Create the order

Send a POST request to the Create Order endpoint. Set paymentOption to "apm_paypal" to enable PayPal on the hosted page.

POST /order — request body

{
  "amount": 44.99,
  "currency": "USD",
  "siteId": "f76fb7ed-3312-4791-a216-45918f899271",
  "clientOrderId": "{{clientOrderId}}",
  "orderDesc": "Order for Apple 14 Pro",
  "successUrl": "https://merchantsite.com/success.html",
  "cancelUrl": "https://merchantsite.com/cancel.html",
  "failedUrl": "https://merchantsite.com/failed.html",
  "pendingUrl": "https://merchantsite.com/pending.html",
  "paymentOption": "apm_paypal",
  "customerDetails": {
    "customerAddress": "123 Main Street",
    "customerCity": "New York",
    "customerCountryCode": "US",
    "customerEmail": "customer@example.com",
    "customerIp": "123.123.123.123",
    "customerName": "John",
    "customerLastName": "Doe",
    "customerPhone": "800-1234567",
    "customerState": "NY",
    "customerZipCode": "10001"
  }
}

tip

paymentOption accepts a comma-separated list. For example, "card,apm_paypal" will display both card and PayPal on the hosted page.

---

Step 2 — Redirect the customer

On a successful order creation the response contains a redirectUrl. Send the customer there to complete payment on the Netvalve hosted page.

POST /order — success response

{
  "traceID": "98e151b7-fca4-4e2a-8597-ab58512f2d41",
  "responseTimestamp": "2025-09-09T06:54:38.626+00:00",
  "orderId": 123445,
  "transactionID": "txn-98e151b7",
  "responseCode": "GTW_1000",
  "responseMessage": "Transaction Approved / Request Successful.",
  "orderState": "CREATED",
  "redirectUrl": "https://checkout.uat.sandbox-netvalve.com?paymentToken=eyJ...",
  "midId": "mid-4521",
  "netvalveMidId": "f76fb7ed-3312-4791-a216-45918f899271"
}

Additional instructions

1. Verify responseCode === "GTW_1000" before redirecting — any other value means the order was not created successfully.
2. To pre-select PayPal on the hosted page, append &paymentOption=paypal to the redirectUrl.
3. The customer will see all enabled payment options and can select PayPal. Netvalve then redirects them to PayPal to log in and complete the payment.

---

Step 3 — Handle the redirect outcome

After the customer completes (or abandons) the payment, Netvalve redirects them to one of the URLs provided in the order:

Outcome	Redirect target
Payment succeeded	successUrl
Customer cancelled	cancelUrl
Payment failed	failedUrl
Payment pending	pendingUrl

---

Step 4 — Receive a webhook (optional)

Netvalve can notify your server via a server-to-server POST when the payment status changes.

note

Webhook endpoint configuration is managed by the Netvalve team. See the Webhook Message guide for the full payload schema.

---

Exception handling

If your server does not receive a redirect or you need to independently verify a transaction status, use the Inquiry API.

Inquiry API — pending response example

{
  "traceID": "965c2c75-b29d-41fc-aa3a-6d40b9f3fbb0",
  "responseTimestamp": "2024-04-25T13:48:49.959+00:00",
  "transactionID": 22,
  "responseCode": "GTW_1002",
  "responseMessage": "Transaction status is Pending.",
  "responseCodeType": "PENDING"
}

If the status is PENDING, wait briefly and re-poll the Inquiry API.

---

Related resources

Resource	Link
Netvalve Hosted Payment Page guide	Hosted Payment Page
Swagger API reference	API Reference
Webhook Message guide	Webhook Message
Error Codes reference	Error Codes