Filling out the merchant application is required to enable live payment processing on SanctusPay. We gather essential business and compliance information to verify your account and help maintain a secure ecosystem.

Welcome to the SanctusPay Developer Portal! Here, you’ll find everything you need to integrate our secure payment solutions into your applications, websites, or e-commerce platforms. Our documentation covers the entire payment lifecycle—from token-based authentication and creating payment intents, to handling settlements, refunds, and more.

Whether you’re just starting out or looking to optimize an existing integration, these docs provide clear, step-by-step guides and reference materials to help you launch quickly and confidently. We’re excited to support your business with fast, reliable, and secure payment capabilities—explore the sections below or jump right to Quickstart!

Explore our sections

A Transaction represents the primary record of money movement in SanctusPay’s payment platform. It indicates whether a particular flow of funds is a payment, a refund, or a chargeback, and contains the essential data needed to track, audit, and manage the lifecycle of that financial event.

Field Descriptions

Transaction Types

• PAYMENT: Standard transaction flow where a customer pays the merchant. Typically begins with authorization, followed by capture (partial or full).

• REFUND: The returning of funds to a customer for a previously captured payment. This transaction references the original payment and tracks the refunded amount.

• CHARGEBACK: Initiated by the cardholder’s bank due to a dispute or fraudulent activity. Funds previously captured may be reversed, pending further investigation or resolution.

Transaction Statuses

• AUTHORIZED: The transaction has been authorized. Funds are held but not captured. The hold is kept until you capture, void or it expires automatically.

• VOIDED: The authorization was canceled before funds were captured. No money moves in a void and the cardholder gets the authorized amount available immediately.

• PARTIAL_CAPTURED: Only a portion of the authorized amount was captured so far.

• CAPTURED: The entire authorized amount is captured. The money has left the cardholder's account and will be transferred to the Merchant.

• EXPIRED: The authorization window elapsed without capture or void, automatically releasing the hold on funds.

Here you’ll learn how a transaction moves through its lifecycle—from the initial authorization or auth+capture, to potential partial captures, voids, and final settlement. By combining the concepts of “Transaction” (the high-level record of payment, refund, or chargeback) with “Operations” (the actions that change its state), SanctusPay offers a transparent, step-by-step approach to managing payments at every stage.

Transaction

A Transaction is the primary record representing the movement of funds—be it a payment, refund, or chargeback. Each transaction includes essential details like a unique ID, a merchant-specific external reference ID, its type (PAYMENT, REFUND, or CHARGEBACK), and the associated amount and currency. This high-level entity serves as the core reference for all subsequent actions, providing a clear overview of the payment’s lifecycle.

Operation

An Operation is a discrete event describing a specific action taken on a transaction (such as authorization, capture, or void). Each operation references the associated transaction, includes the operation type (authorize, refund, etc.), and records relevant data like amount, currency, origin, and timestamps. Together, operations form a detailed audit trail of every step in the transaction’s lifecycle.

Relationship & Lifecycle

• Transaction as the “Container” A Transaction identifies the overall movement of funds—whether it’s a payment, refund, or chargeback. It stores details like transaction ID, external reference, amount, and currency.

• Operations as “Actions” Each Operation records a specific event in the transaction’s lifecycle—such as authorize, capture, void, or expire. An operation references its parent transaction, tracks the amount involved, and notes the context (origin, timestamps, etc.).

• Chronological Progression Together, multiple operations form a timeline for a single transaction. For example, a transaction may start with authorize, transition to partial_capture, and eventually end with a settle operation. At every step, the transaction’s status updates to reflect the latest successful operation.

• Final Status Determination The most recent operation typically dictates the transaction’s current status (e.g., AUTHORIZED, CAPTURED, VOIDED, SETTLED). By examining the sequence of operations, one can audit the transaction’s complete journey from initiation to final resolution.

Key Takeaway

By keeping Transactions and Operations separate, SanctusPay’s system provides merchants with a transparent, granular view of the payment journey—ensuring that every authorization, capture, or void can be monitored from initiation to final settlement.

When your application is approved, your merchant account moves from test mode to live mode. This unlocks the ability to process real transactions and access production API credentials.

SanctusPay Hosted Checkout Page (HCP) offers robust customization capabilities designed to create an optimal and branded shopping experience for your customers. Merchants have the flexibility to adapt the visual elements of the HCP, ensuring that the checkout process aligns seamlessly with their overall brand identity.

You can customize the checkout page by modifying the colors, fonts, and layout to mirror your brand's aesthetic. Additionally, it is possible to personalize the experience further by uploading your logo, embedding specific company information, and incorporating support contact details, thereby reassuring customers that help is accessible if needed. The HCP also presents detailed information about the user's current order, such as item descriptions, prices, and quantities, which promotes transparency and strengthens trust. This ability to provide a cohesive and informative checkout experience not only enhances the customer's journey but also potentially increases conversion rates by reducing cart abandonment.

Configuring the SanctusPay HCP

To configure the SanctusPay Hosted Checkout Page (HCP), users must first log into the SanctusPay Portal. Within the portal, they can access a dedicated section for customizing their HCP settings. Here, users have the option to add or modify various elements, such as adjusting the color scheme, selecting suitable fonts, and rearranging the layout to match their brand's design. They can also upload their company logo and input essential support contact details. By making these adjustments, merchants ensure that the checkout process reflects their brand identity, providing a seamless and reassuring experience for their customers.

The SanctusPay API provides merchants with a secure, reliable, and scalable way to process payments. By leveraging industry-standard JSON-based REST endpoints, merchants can integrate functionalities such as authentication, payment intent creation, card tokenization, transaction retrieval, and refunds into their own systems. This API is designed to reduce integration complexity and speed up time-to-market for online payment processing.

Key Capabilities

With the SanctusPay API, you can manage the entire lifecycle of a payment: from obtaining a new access token and generating payment intents, to finalizing transactions and handling refunds or chargebacks. Our endpoints ensure sensitive card data is transmitted and stored securely—often via tokenization and other PCI-compliant mechanisms—minimizing your liability and protecting your customers’ financial information.

Implementation Details

Integration follows a straightforward bearer token approach for authentication, requiring you to include the generated token in the Authorization header. Every endpoint in this specification details the required parameters, sample requests and responses, and potential error messages you may encounter, enabling you to build robust payment solutions with minimal friction.

For added flexibility, the SanctusPay API offers dedicated environments (test and live).

A Hosted Checkout Page (HCP sometimes also refered as HPP) is a secure, standalone payment page hosted by a payment provider (such as SanctusPay). Rather than the merchant’s own website handling and storing sensitive card data directly, the user is redirected to this pre-built, fully compliant checkout form to enter their payment details. Here’s what it generally does and why it’s beneficial:

1. Secure Data Collection

   • The HCP ensures cardholder information is collected in a PCI-compliant environment.

   • Sensitive payment details (e.g., card number, CVV) never pass through the merchant’s servers, reducing the merchant’s risk and PCI-DSS scope.

2. Payment Workflow

   • The merchant creates a “payment intent” (or similar transaction request) and receives an identifier from the SanctusPay API.

   • Using this intent identifier, the merchant redirects the customer to the HCP.

   • The customer reviews their order details and enters their card/billing information on the hosted page.

3. Authorization & Processing

   • The HPP securely communicates with the SanctusPay backend to perform the authorization (and capture if applicable).

   • When the transaction completes—successfully or otherwise—the HCP redirects the customer back to the merchant’s website along with the transaction status.

4. Customization

   • SanctusPay allows merchants to customize the HCP’s look and feel so it aligns with the merchant’s branding, while still ensuring best-in-class security.

5. Reduced Complexity for Merchants

   • Because the hosted page is fully managed by the SanctusPay, merchants do not need to develop or maintain complex payment forms.

   • It also alleviates the burden of rigorous compliance checks, as the provider typically handles the bulk of security requirements.

Overall, a Hosted Checkout Page simplifies payment acceptance by offloading the most sensitive and compliance-heavy parts of payment processing to a secure third-party platform. This lets merchants focus on their core business while still offering a smooth checkout experience to customers.

The SanctusPay process involves the merchant creating a payment intent with the API, directing the user to the HCP for secure card entry. The HCP confirms payment with the API and redirects the user back to the merchant with the transaction result.

Access HCP & Live and Test environments

SanctusPay's Hosted Checkout Page (HCP) operates in two distinct environments: Live and Test. The Live environment is used for processing real transactions with actual payment details, ensuring that all interactions are secure and reliable. On the other hand, the Test environment is designed for development and troubleshooting, allowing merchants to simulate transactions without incurring actual charges. This separation ensures that developers can verify their integration and functionality without jeopardizing real customer data or financial information.

Environments

HCP URL Variables

To access the Hosted Checkout Page (HCP) URL, it is essential to supply two specific GET parameters: client_id and intent_id.

The client_id represents the unique identifier assigned to the merchant's account, ensuring that the transaction is linked to the correct merchant. You can get this information in your api/developer section in Portal. It's also referred as "Account ID".

HCP Sequence Flow

Step-by-Step Explanation

1. Merchant Website → SanctusPay API: The merchant’s backend sends a POST /intents/payment request to create a new payment intent. This request typically includes information such as the merchant’s external_id, order details, and redirect URLs.

2. SanctusPay API → Merchant Website: The SanctusPay API responds with a JSON payload that includes an intent_id. This unique identifier references the newly created payment intent.

3. Merchant Website → User: With the intent_id in hand, the merchant constructs and provides the Hosted Checkout Page URL to the user. This might involve redirecting the user’s browser or displaying a link/button that includes the intent_id and the merchant account_id (also known as client_id).

4. User → Hosted Checkout Page: The user clicks on the provided link (or is automatically redirected) to the SanctusPay Hosted Checkout Page (HCP). The HCP page is responsible for securely collecting the user’s card and billing information.

5. Hosted Checkout Page → SanctusPay API: Once the user inputs their card details and confirms payment, the HPP sends the card data and confirmation to the SanctusPay API. This step initiates the actual payment authorization process.

6. SanctusPay API → Hosted Checkout Page: The SanctusPay API processes the request (e.g., checks the card, contacts the payment network, etc.) and returns the authorization result to the HPP. The result can be a success (authorized) or failure (declined or error).

7. Hosted Checkout Page → Merchant Website: Finally, the Hosted Checkout Page redirects the user back to the merchant-specified success or failure URL. This redirect typically includes parameters indicating the status of the transaction, and possibly the intent_id or a transaction reference.

Sign Up for a Merchant Account

2. Confirm Your Email: Click the link in the confirmation email, then set your password.

3. Log In: You’ll have immediate access to the test environment (sandbox).

Explore & Integrate

Registration is the first step to accessing SanctusPay’s platform. By creating an account, you gain instant access to our test environment and can start experimenting with our APIs right away.

An Operation represents a discrete event or action taken on a Transaction. Multiple operations can accumulate on a single transaction, providing a detailed audit trail of how a transaction moved from initial authorization to capture, void, refund, and beyond. This granular record is accessible in the SanctusPay Portal’s transaction details view, giving you insight into every step of the transaction’s lifecycle.

Key Fields (Portal View)

Note: In the SanctusPay database, operations may also track internal fields like TrxID, TrxType, Operation Origin, and more. However, these internal details are not directly exposed via any public API endpoints. Merchants can see a subset of this information when viewing transaction history in the Portal.

Operation Types

Operations reflect each significant action in the transaction lifecycle. Below are some of the common Operation Type values you might see:

• authorize: A request to hold funds (no immediate capture).

• authcap: An authorization combined with an immediate capture of the total amount.

• partial_capture: Capturing only a portion of the total authorized amount.

• capture: A full capture of all authorized funds.

• void: Canceling the authorization before capture.

• refund: Reversing funds back to the customer for a completed (captured) transaction.

• expire: Automatically releasing the hold on funds after the authorization period lapses.

How to View Operations

Since the SanctusPay API does not expose an endpoint to fetch operations directly, the Portal is the primary tool for merchants to see these records. Within a transaction’s details page, you’ll find a timeline or list of all operations performed on that transaction, along with timestamps, amounts, and any relevant notes.

Why Operations Matter

• Audit Trail: Operations document every state change, enabling thorough reviews or investigations.

• Clarity & Debugging: If a transaction was partially captured or voided unexpectedly, the operation history explains exactly when and how it happened.

• Lifecycle Tracking: From initial authorization to final capture, each step is logged as a separate operation, providing a chronological account of the transaction’s journey.