> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orsunpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts Overview
> Understand the fundamental concepts and entities in Orsunpay
# 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
```json theme={null}
{
"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
```json theme={null}
{
"id": "cu_clkj3h2n0000qjr8x4c5h6e7b",
"buyerId": "customer_12345",
"companyId": "co_clkj3h2n0000qjr8x4c5h6e7b",
"merchantId": "mr_clkj3h2n0000qjr8x4c5h6e7b",
"email": "john.doe@example.com",
"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
```json theme={null}
{
"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
```json theme={null}
{
"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`).
| Status | Description | Final | Next Possible States |
| -------------- | ------------------------------ | ----- | -------------------------------------------- |
| `CREATED` | Transaction initiated | No | `WAIT_APPROVE`, `PROCESSING`, `CANCELED` |
| `WAIT_APPROVE` | Awaiting operator approval | No | `PROCESSING`, `DECLINED`, `CANCELED` |
| `PROCESSING` | Payment in progress | No | `SUCCESS`, `DECLINED`, `EXPIRED`, `CANCELED` |
| `SUCCESS` | Payment completed successfully | Yes | None |
| `DECLINED` | Payment rejected by provider | Yes | None |
| `EXPIRED` | Payment session expired | Yes | None |
| `CANCELED` | Payment canceled by customer | Yes | None |
## Transaction Actions
Different transaction types serve various business needs:
| Action | Purpose | Description |
| ------------ | ------------------ | ------------------------------ |
| `SALE` | Direct payment | Immediate capture of funds |
| `AUTHORIZE` | Pre-authorization | Reserve funds without capture |
| `PAYOUT` | Money transfer | Send money to recipients |
| `REFUND` | Return funds | Reverse a previous transaction |
| `CHARGEBACK` | Dispute resolution | Handle 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](/getting-started/auth) and make your first API call.
Configure API keys and security headers for your integration.
Understand the differences between sandbox and production environments.