Payments

Once a merchant is onboarded and approved, you can take payments. PayBridge uses a hosted checkout: you create a session from your backend, redirect the customer to a secure PayBridge-hosted payment page (card data is captured there and never touches your servers or ours), then confirm the result.

All requests use the base URL, X-API-Key, and X-Requested-With header from the Overview. Amounts are in cents.

Step 1: Create a checkout session

When a customer is ready to pay, create a session from your backend.

POST /checkout/sessions

{
  "merchant_id": "a1b2c3d4-...",
  "amount": 75000,
  "currency": "USD",
  "description": "Custom Shed - 10x12 Barn Style",
  "success_url": "https://yourstore.com/orders/123/confirmed",
  "cancel_url": "https://yourstore.com/orders/123/checkout",
  "customer_email": "buyer@example.com",
  "idempotency_key": "order-123-checkout-v1"
}

The success_url and cancel_url must match origins registered with your app (set during provisioning) — this prevents open-redirect attacks. The idempotency_key is required so retries never create duplicate sessions.

Response (201):

{
  "id": "session-uuid",
  "checkout_url": "https://sandbox.api.nfs-pay.com/checkout/session/session-uuid?st=...",
  "amount": 75000,
  "currency": "USD",
  "status": "pending",
  "expires_at": "2026-03-26T12:30:00Z",
  "created_at": "2026-03-26T12:00:00Z"
}

Step 2: Redirect the customer

Send the customer to the checkout_url. This opens a PayBridge-hosted payment page where they enter their card or bank details on the secure hosted page.

window.location.href = checkoutSession.checkout_url;

After payment, the customer is redirected to your success_url with query parameters:

https://yourstore.com/orders/123/confirmed
  ?pay_session_id=session-uuid
  &pay_payment_id=payment-uuid
  &pay_status=posted
  &pay_amount=75000

If they cancel, they're sent to your cancel_url.

Step 3: Confirm the payment

Don't trust the redirect parameters alone — verify from your backend.

GET /checkout/sessions/{session_id}

{
  "id": "session-uuid",
  "status": "completed",
  "amount": 75000,
  "currency": "USD",
  "payment_id": "payment-uuid",
  "completed_at": "2026-03-26T12:02:30Z"
}

Session statuses:

• pending — waiting for payment
• completed — payment succeeded
• expired — session timed out (30 minutes)

You can also register a checkout.completed webhook to be notified when a payment succeeds; verify the X-PayBridge-Signature header and fall back to status polling for any missed event.

Refunds

Issue a full or partial refund against a completed payment. Refunds route back to the processor that handled the original payment.

POST /payments/{payment_id}/refund

Full refund (omit amount):

{
  "idempotency_key": "refund-order-123-full",
  "description": "Order cancelled by customer"
}

Partial refund:

{
  "amount": 25000,
  "idempotency_key": "refund-order-123-partial-v1",
  "description": "Partial refund for returned item"
}

Response (201):

{
  "id": "refund-uuid",
  "payment_id": "original-payment-uuid",
  "amount": 25000,
  "status": "posted",
  "created_at": "2026-03-28T10:00:00Z"
}

Only payments in posted or settled status can be refunded. Multiple partial refunds are allowed, up to the original payment amount. idempotency_key is required to prevent duplicate refunds on retry.

Sandbox testing

The sandbox connects to the processor's sandbox. The hosted checkout page accepts the test card or bank details directly — no VGS setup is required in sandbox — so you can run a payment end to end. Staging and production still capture card data through VGS.

See Testing for the sandbox test cards.