Tutorial: How to Implement a One-Step Purchase with Sola’s API

Introduction: The “Sale” Transaction

This Sola API tutorial covers the most fundamental transaction in any payment system: the one-step payment. Known commercially as a “Sale” or “immediate capture,” the mechanism is an atomic API call that combines authorization and capture into a single, indivisible operation. Upon a successful 200 OK response, you have an irrevocable guarantee that the funds have been secured and are en route to settlement.

This workflow is the architectural standard for digital goods, subscription sign-ups, and any scenario where fulfillment is instantaneous. There is no delay between verifying the card’s validity and debiting the funds. If your business model involves shipping physical goods or verifying inventory post-authorization, you will require a two-step (Auth/Capture) process, which is covered in a separate tutorial. This guide focuses exclusively on the immediate, final charge, a cornerstone of any A Developer’s Guide to Integrating a Secure Payment Gateway.

Prerequisites: Getting Your Keys

Before making your first API call, ensure you have the following credentials and configurations in place. Access to the Sola API is restricted and requires these elements for authentication and security.

• Sandbox Account: You must have an active Sola developer sandbox account.
• API Credentials: Locate your client_key and client_pass in the developer dashboard.
• Whitelisted IP Address: For server-to-server requests, the IP address of your application server must be whitelisted in your account settings.

Security Mandate: Your client_pass is a secret key. It must never be exposed in client-side code (e.g., JavaScript, mobile applications) or committed to a public version control repository. All authenticated requests must originate from your secure server environment.

Step 1: Constructing the Request Payload

A successful transaction begins with a correctly structured JSON payload. The Sola API is strictly typed and validates every parameter; a malformed request will result in an immediate 400 Bad Request error. To initiate a sale, you will send an authenticated POST request to the /api/v1/payment/sale endpoint.

The body of your request must contain the essential payment parameters for processing. While the Official API Documentation provides an exhaustive list, the core fields are non-negotiable:

• order_id: Your unique internal identifier for this transaction. This is the primary key for reconciliation against your own records. It must be unique for every sale attempt.
• amount: The transaction value specified as an integer in the currency’s smallest unit (e.g., 1000 for €10.00). Floating-point values are not accepted.
• currency: The three-letter ISO 4217 currency code (e.g., EUR, USD).
• card_details: An object containing the raw card data: pan, cvv, expiry_month, and expiry_year. Note that in a production environment, you should be submitting a token here to minimize PCI scope, not raw PANs.

For enhanced security and to leverage our fraud prevention engine, it is critical to also include:

• customer_email: The customer’s email address for risk velocity checks.
• ip_address: The end-user’s IP address for geolocation and pattern analysis.

Submitting this metadata provides our system with more data points to accurately score the transaction, reducing false declines.

Step 2: Sending the Request (Code Example)

With the payload constructed, the next step is to send it to the Sola one-step payment API endpoint. The following CURL example demonstrates a complete, well-formed request. Authentication is handled via HTTP Basic Auth, where you must Base64-encode your client_key:client_pass string.

curl -X POST \
  https://sandbox.sola.live/api/v1/payment/sale \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
  -d '{
    "order_id": "ORD-1678912345",
    "amount": 1000,
    "currency": "EUR",
    "card_details": {
      "pan": "4242424242424242",
      "cvv": "123",
      "expiry_month": "12",
      "expiry_year": "225"
    },
    "customer_email": "test.customer@example.com",
    "ip_address": "8.8.8.8"
  }'

Replace `YOUR_BASE64_ENCODED_CREDENTIALS` with your actual encoded API key and password. A successful request will return a `200 OK` status code with the transaction response.

Step 3: Handling the Response States

A 200 OK response does not automatically signify a successful charge. The JSON body contains a crucial status field that dictates your next action. A robust integration requires a state machine capable of handling all possible outcomes.

• status: ‘approved’ (Success Path): This is the ideal outcome. The transaction was authorized and captured. The response will include a unique transaction_id. At this point, you should persist the transaction details in your database, mark the order as paid, and grant the customer access to their purchase.
• status: ‘declined’ (Failure Path): The issuing bank has rejected the transaction. The response body will contain a response_code and a response_text (e.g., “Insufficient Funds”). Your application should log the specific reason for internal analysis but display a generic, user-friendly message (e.g., “Your card was declined. Please try a different card.”).
• status: ‘3ds_verify’ (Redirect Path): This is the most critical state for European and SCA-mandated transactions. This payment status indicates that the card is enrolled in 3D Secure and requires user authentication. The API response will contain a redirect_url. Your application must redirect the user’s browser to this URL to complete the verification challenge. The final transaction status (approved or declined) will be communicated asynchronously via webhook after the user completes the 3DS redirect. Ignoring this state will result in a 100% failure rate for SCA-protected cards.

Conclusion: Next Steps

By following this Sola API tutorial, you have successfully implemented the core logic for a one-step payment. You can now securely send a request, parse the synchronous response, and handle the critical 3D Secure redirect flow. This is the foundational building block for accepting payments for digital goods and services.

However, many business models require a delay between validating a card and actually debiting the funds. If you are shipping physical goods, verifying inventory, or placing a temporary hold on a customer’s card, you need to implement a two-step auth and capture workflow. To learn how to separate authorization from settlement, proceed to our Tutorial: How to Implement Auth/Capture (Two-Step Payments).