Transaction Types

S2S Transaction Types

Version: 3.0.0

What Is Server-to-Server Integration?

S2S integration allows you to process payments entirely from your server to PayOrc's API - no redirects, no hosted pages, no client-side SDK. This gives you maximum control over the payment experience but requires PCI DSS compliance since your server handles card data directly.

When to Use S2S

• MOTO payments - Processing phone or mail orders where the merchant enters card details on behalf of the customer.
• Token-based recurring payments - Charging saved card tokens for subscriptions or repeat purchases.
• Backend payment processing - Automating payments without any UI (e.g., invoice payment, backend billing).
• Full customization - When you need complete control over the payment form and flow.

API Endpoint

All S2S requests use base URL https://api.payorc.com/s2s/v1/ and merchant-key / merchant-secret headers (S2S channel API key). See S2S Payment for the correct { "data": { ... } } request shape.

Transaction Types Reference

Payment method types (data.type)

Payment Flows: When to Use Each

Standard Payment (Payment)

Use this for direct card payments where the server initiates the transaction. Best for backend billing systems, API-to-API integrations, and scenarios where the card details are already tokenized.

CAUTH - Pay by Token (Card on File)

Use class: "CAUTH" to charge a stored payment token (merchant-initiated). Send the full S2S payment body with type: "CARD" and data.card_details.payment_token — not raw card number. m_customer_id must match the customer linked to the token; the token is validated against your merchant_id from API credentials. PSP is resolved from the token mandate (Telr, Paymob, or NI). See CAUTH.

MOTO - Mail Order / Telephone Order

Use MOTO when a customer provides their card details over the phone or via email, and a merchant agent enters them into the system. MOTO transactions:

• Bypass 3D Secure - Since the customer is not physically present at a terminal, 3DS is not applicable.
• Are higher risk - Monitor for fraud patterns.
• Require MOTO flag - Set the payment method type to MOTO in your request.

SADAD - Bank Transfer

Use SADAD for customers who prefer to pay directly from their bank account. The flow:

1. Customer selects SADAD at checkout.
2. PayOrc generates a bank transfer invoice.
3. Customer logs into their bank and completes the transfer.
4. PayOrc sends a webhook with INVOICE_CREATED and later a CAPTURE event when payment is confirmed.

Apple Pay

Use type: "APPLE_PAY" when the customer pays with Apple Wallet on iOS or Web. Your app collects the Apple Pay token on the client; your server sends it in data.token (not card_details). Supported PSPs: Telr, Paymob. Payment typically completes in one API call with no redirect. See Apple Pay.

Google Pay

Use type: "GOOGLE_PAY" when the customer pays with Google Pay on Android or Web. Token goes in data.token. May return a 3DS redirect URL when authentication is required. See Google Pay.

3D Secure Handling

3D Secure (3DS) adds an extra authentication layer for card payments. Here's how it works with PayOrc S2S:

1. Initiate payment - Send the auth/sale request with card details.
2. 3DS challenge - If the card issuer requires 3DS, PayOrc returns a 3ds_url and pareq in the response.
3. Redirect customer - Your server redirects the customer to the 3ds_url for authentication.
4. 3DS callback - After authentication, the customer is redirected back to your return_url with authentication results.
5. Complete payment - Submit the 3DS response to PayOrc to finalize the transaction.

Code Examples: S2S Payment Request

# Standard S2S Sale (Auth + Capture in one step)
curl -X POST "https://api.payorc.com/s2s/v1/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "payment_method": "Payment",
    "amount": 100.00,
    "currency": "AED",
    "m_order_id": "ORDER-2026-001",
    "card_number": "4111111111111111",
    "card_expiry": "12/28",
    "card_cvv": "123",
    "card_holder_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_name": "John Doe",
    "return_url": "https://example.com/return",
    "notification_url": "https://example.com/webhook"
  }'

# MOTO Transaction (phone/mail order - no 3DS)
curl -X POST "https://api.payorc.com/s2s/v1/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "payment_method": "MOTO",
    "amount": 250.00,
    "currency": "SAR",
    "m_order_id": "MOTO-2026-001",
    "card_number": "4111111111111111",
    "card_expiry": "06/27",
    "card_cvv": "456",
    "card_holder_name": "Jane Smith",
    "customer_email": "[email protected]",
    "customer_name": "Jane Smith"
  }'

SADAD Bank Transfer Example

SADAD payments follow a different flow - the customer pays via their bank account rather than a card.

# Initiate a SADAD payment
curl -X POST "https://api.payorc.com/s2s/v1/payment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "payment_method": "SADAD",
    "amount": 500.00,
    "currency": "SAR",
    "m_order_id": "SADAD-2026-001",
    "customer_email": "[email protected]",
    "customer_name": "John Doe",
    "notification_url": "https://example.com/webhook"
  }'
# Response includes a SADAD payment URL/QR code
# Customer completes payment from their bank
# Webhook fires with INVOICE_CREATED, then CAPTURE when confirmed

Best Practices

PCI Compliance: S2S integration means your server handles raw card data. Ensure you are PCI DSS certified and follow all security requirements. Consider tokenization (CAUTH flow) to minimize card data exposure.

• Use CAUTH for tokenization - Instead of sending card details on every request, tokenize the card once with CAUTH and use the token for subsequent payments.
• Always handle 3DS - Check for three_ds_required in the response and redirect the customer to complete authentication.
• Verify via webhooks - Don't rely solely on the synchronous API response. Use webhooks to confirm the final transaction status.
• MOTO fraud monitoring - Since MOTO bypasses 3DS, implement additional fraud checks (velocity limits, amount thresholds, manual review queues).
• Idempotency keys - Include a unique m_order_id with every request to prevent duplicate charges on retries.