Server to Server Integration Guide

Server to Server (S2S) is a fully API-driven integration where your server handles the entire payment flow — collecting card data, calling UseePay APIs directly, and managing the PaymentIntent lifecycle — without any UseePay-hosted UI or JS SDK.

Note: S2S integration requires your application to be PCI DSS compliant, as raw card data passes through your server.

When to Use S2S

Scenario	Recommended
Native mobile app (iOS / Android)	✅
Existing custom payment form	✅
Full control over payment UI and flow	✅
Server-side batch payments or auto-charge	✅
Want UseePay to handle the payment UI	❌ Use Embedded or Hosted Checkout instead

How It Works

Integration Steps

Step 1 · Collect Card Data on Your Frontend

Your frontend collects card details directly from the customer. You are responsible for securing the transmission (HTTPS required).

Minimum required fields

Field	Description
Card number	16-digit PAN
Expiry month	MM format
Expiry year	YY or YYYY format
CVV	3 or 4 digits

Send the collected card data to your own backend over HTTPS. Never log or store raw card data.

Step 2 · Server · Create a PaymentIntent

Your server creates a PaymentIntent to represent the payment session.

Key parameters

Parameter	Description
`amount`	Amount in minor units (e.g. `1000` = $10.00)
`currency`	ISO 4217 code, e.g. `USD`
`merchantOrderId`	Your unique order ID
`captureMethod`	`automatic` · charge immediately / `manual` · auth only
`returnUrl`	Redirect URL after 3DS completion

Response — store id for the next step.

Step 3 · Server · Confirm with Card Data

Submit the card details to confirm the PaymentIntent. This is where the actual charge attempt happens.

Key parameters

Parameter	Description
`paymentMethod.card.number`	Encrypted or raw card number
`paymentMethod.card.expiryMonth`	Card expiry month
`paymentMethod.card.expiryYear`	Card expiry year
`paymentMethod.card.cvc`	Card CVV
`returnUrl`	Where to redirect after 3DS

Possible response statuses

Status	Meaning	Action
`succeeded`	Payment complete	Fulfill order
`requires_capture`	Authorized (manual mode)	Capture when ready
`requires_action`	3DS required	Redirect customer
`failed`	Payment declined	Show error, retry

Step 4 · Handle 3DS Authentication (if required)

If the card requires 3DS, the confirm response will contain next_action:

{
  "status": "requires_action",
  "nextAction": {
    "type": "redirect",
    "redirect": {
      "url": "https://3ds.useepay.com/authenticate?token=xxx"
    }
  }
}

Redirect the customer to nextAction.redirect.url. After authentication, the customer is returned to your returnUrl:

https://yoursite.com/payment/result
  ?payment_intent=pi_1234567890
  &redirect_status=succeeded

Always verify the final status server-side — do not rely solely on the redirect params.

Step 5 · Capture (Manual Mode Only)

If you created the PaymentIntent with captureMethod: "manual", the card is authorized but not charged after confirmation. Capture when you are ready to fulfill the order.

The authorization hold will expire if not captured within the allowed window.

Step 6 · Receive Webhook Events

Set up a Webhook endpoint in the Merchant Dashboard to receive real-time payment notifications.

Event	Description
`payment_intent.succeeded`	Payment completed
`payment_intent.payment_failed`	Payment failed
`payment_intent.requires_capture`	Authorized, awaiting capture
`payment_intent.canceled`	Payment canceled

Webhook is the recommended way to confirm payment status — more reliable than redirect params or polling.

PaymentIntent Status Lifecycle

requires_payment_method
         │
         ▼
 requires_confirmation
         │
         ▼
   requires_action ──── 3DS auth ────┐
         │                           │
         ▼                           │
 requires_capture (manual mode)      │
         │                           │
         ▼                           ▼
      succeeded ◄────────────────────┘

  canceled / failed  (terminal states)

Supported Payment Methods (S2S)

Payment Method	Notes
Credit / Debit Card	Full S2S support including 3DS
Apple Pay	Requires Apple Pay token from device
Google Pay	Requires Google Pay token from device

Go-Live Checklist

Confirm your PCI DSS compliance scope with your security team

Obtain API keys from the Merchant Dashboard

Implement HTTPS on all pages that handle card data

Create PaymentIntent server-side before submitting card data

Handle requires_action status — redirect customer to 3DS URL

Set up Webhook endpoint and verify final payment status server-side

Implement refund flow via POST /refunds for failed fulfillments

Test with test cards in sandbox before going live

Server to Server Integration Guide

When to Use S2S#

How It Works#

Integration Steps#

PaymentIntent Status Lifecycle#