Skip to main content

​
Core Concepts Overview

Before integrating with Orsunpay, it’s essential to understand our core concepts and how they work together to process payments.

​
Key Entities

​
Merchant

A Merchant represents your business or organization within Orsunpay. Each merchant has:
  • Unique ID: Generated with mr_ prefix (e.g., mr_abc123def456)
  • Domain: Your business domain for validation
  • Private Key: Used for webhook signature verification
  • Company Association: Links to your company account
{
  "id": "mr_clkj3h2n0000qjr8x4c5h6e7b",
  "companyId": "co_clkj3h2n0000qjr8x4c5h6e7b",
  "name": "Acme E-commerce Store",
  "domain": "acme-store.com",
  "isActive": true,
  "privateKey": "sk_merchant_abc123def456...",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

​
Customer

A Customer represents the end user making a payment. Customer data helps with:
  • Risk assessment and fraud prevention
  • Payment method recommendations
  • Compliance with local regulations
  • Transaction history tracking
{
  "id": "cu_clkj3h2n0000qjr8x4c5h6e7b",
  "buyerId": "customer_12345",
  "companyId": "co_clkj3h2n0000qjr8x4c5h6e7b",
  "merchantId": "mr_clkj3h2n0000qjr8x4c5h6e7b",
  "email": "[email protected]",
  "phone": "+1234567890",
  "firstName": "John",
  "lastName": "Doe",
  "address": "123 Main Street",
  "address2": "Apt 4B",
  "city": "New York", 
  "country": "US",
  "state": "NY",
  "zip": "10001",
  "ip": "192.168.1.1",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "dob": "1990-01-15",
  "riskScore": 15,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
The buyerId is your internal customer identifier, while our id is Orsunpay’s unique identifier.

​
Credential Config

A Credential Config defines how payments are processed for specific payment methods. It includes:
  • Provider credentials (securely encrypted)
  • Payment method configuration
  • Fee settings and calculation rules
  • Currency and country restrictions
  • Amount limits for transactions
{
  "id": "cr_clkj3h2n0000qjr8x4c5h6e7b",
  "provider": "stripe",
  "merchantId": "mr_clkj3h2n0000qjr8x4c5h6e7b",
  "companyId": "co_clkj3h2n0000qjr8x4c5h6e7b",
  "paymentMethod": "card",
  "isActive": true,
  "isFeeEnabled": true,
  "feeType": "PERCENTAGE",
  "feeCharge": "MERCHANT",
  "feeAmount": 290,
  "defaultCurrency": "USD",
  "isDccEnabled": false,
  "isSaleEnabled": true,
  "isPayoutEnabled": false,
  "saleMinAmount": 100,
  "saleMaxAmount": 100000,
  "payoutMinAmount": 0,
  "payoutMaxAmount": 0,
  "allowedCountries": ["US", "CA", "GB"],
  "allowedCurrencies": ["USD", "CAD", "GBP"],
  "settings": {
    "publicKey": "pk_live_...",
    "secretKey": "[ENCRYPTED]",
    "webhookEndpoint": "https://api.orsunpay.com/webhooks/stripe"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

​
Transaction

A Transaction represents a payment attempt and contains:
  • Payment details (amount, currency, customer)
  • Processing state and status history
  • Provider information and external IDs
  • Metadata for custom business logic
  • URLs for redirect flows
{
  "id": "tr_clkj3h2n0000qjr8x4c5h6e7b",
  "customerId": "cu_clkj3h2n0000qjr8x4c5h6e7b",
  "companyId": "co_clkj3h2n0000qjr8x4c5h6e7b",
  "merchantId": "mr_clkj3h2n0000qjr8x4c5h6e7b",
  "credentialConfigId": "cr_clkj3h2n0000qjr8x4c5h6e7b",
  "provider": "stripe",
  "paymentMethod": "card",
  "buyerId": "customer_12345",
  "orderId": "order_67890",
  "pspTransactionId": "pi_1234567890",
  "locale": "en-US",
  "successUrl": "https://yoursite.com/success",
  "failureUrl": "https://yoursite.com/failure",
  "returnUrl": "https://yoursite.com/return",
  "callbackUrl": "https://yoursite.com/webhooks/orsunpay",
  "metadata": {
    "productId": "prod_123",
    "campaignId": "campaign_456"
  },
  "currency": "USD",
  "processingCurrency": "USD",
  "isFeeEnabled": true,
  "feeType": "PERCENTAGE",
  "feeCharge": "MERCHANT",
  "feeAmount": 150,
  "currencyRate": 1.0,
  "amount": 5000,
  "processingAmount": 5000,
  "processingAmountWithFee": 5150,
  "status": "SUCCESS",
  "action": "SALE",
  "ruleId": "rule_auto_routing_123",
  "errorCode": null,
  "finalStatusUpdatedAt": "2025-01-15T10:35:00.000Z",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z"
}

​
Payment Flow

Understanding the typical payment flow helps you integrate Orsunpay effectively:

​
Flow Steps

  1. Create Transaction: Your backend creates a transaction via our API
  2. Provider Routing: Our system selects the best provider based on your rules
  3. Payment Processing: Customer completes payment through provider’s interface
  4. Webhook Notifications: Both you and we receive status updates
  5. Status Synchronization: Your system updates order status accordingly

​
Transaction Statuses

Transaction statuses are immutable once they reach a final state (SUCCESS, DECLINED, EXPIRED, CANCELED).
StatusDescriptionFinalNext Possible States
CREATEDTransaction initiatedNoWAIT_APPROVE, PROCESSING, CANCELED
WAIT_APPROVEAwaiting operator approvalNoPROCESSING, DECLINED, CANCELED
PROCESSINGPayment in progressNoSUCCESS, DECLINED, EXPIRED, CANCELED
SUCCESSPayment completed successfullyYesNone
DECLINEDPayment rejected by providerYesNone
EXPIREDPayment session expiredYesNone
CANCELEDPayment canceled by customerYesNone

​
Transaction Actions

Different transaction types serve various business needs:
ActionPurposeDescription
SALEDirect paymentImmediate capture of funds
AUTHORIZEPre-authorizationReserve funds without capture
PAYOUTMoney transferSend money to recipients
REFUNDReturn fundsReverse a previous transaction
CHARGEBACKDispute resolutionHandle payment disputes
Use AUTHORIZE for scenarios where you need to confirm order details before capturing payment (e.g., inventory verification).

​
Payment Methods

Orsunpay supports a wide range of payment methods, categorized as:

​
Cards

  • Credit/Debit Cards: Visa, Mastercard, American Express, etc.
  • Local Cards: Maestro, Dankort, EFTPOS, etc.

​
Alternative Payment Methods (APM)

  • Digital Wallets: PayPal, Apple Pay, Google Pay, Alipay
  • Bank Transfers: SEPA, ACH, Open Banking, PIX
  • Buy Now Pay Later: Klarna, Afterpay, Affirm
  • Cash: Boleto, OXXO, 7-Eleven
  • Cryptocurrencies: Bitcoin, Ethereum, USDC

​
Webhooks and Callbacks

Webhooks are critical for maintaining payment state synchronization:

​
Webhook Events

Common webhook events you’ll receive:
  • transaction.created - Transaction initiated
  • transaction.processing - Payment started
  • transaction.succeeded - Payment completed
  • transaction.failed - Payment declined
  • transaction.expired - Payment session timeout

​
Callback URLs

Configure these URLs in your transaction requests:
  • Success URL: Where customers go after successful payment
  • Failure URL: Where customers go after failed payment
  • Return URL: General return URL from payment provider
  • Callback URL: Server-to-server webhook endpoint
Webhook endpoints must respond with HTTP 200 status within 30 seconds to avoid retries.

​
Best Practices

​
Security

  • Never expose API keys in frontend code
  • Always validate webhook signatures
  • Use HTTPS for all callback URLs
  • Implement idempotency for critical operations

​
Error Handling

  • Check transaction status via webhook and API calls
  • Implement retry logic for network failures
  • Log all interactions for debugging and compliance
  • Handle edge cases gracefully

​
Performance

  • Cache payment methods to reduce API calls
  • Use webhooks instead of polling for status updates
  • Implement proper timeouts for API requests
  • Monitor response times and error rates

​
Next Steps

Now that you understand the core concepts, let’s set up authentication and make your first API call.

Authentication Setup

Configure API keys and security headers for your integration.

Environment Configuration

Understand the differences between sandbox and production environments.