Skip to main content

Server-to-Server (S2S) Integration

Supported currency: AUD only.
The Server-to-Server (S2S) API allows you to securely create card payments directly from your backend without using the JavaScript SDK.
This method is designed for PCI DSS–compliant servers that collect and send raw card details (card_info) directly to the Hello Clever API.

🔧 Environments​

EnvironmentBase URL
Sandboxhttps://sandbox-api.lightningpay.me
Productionhttps://api.lightningpay.me

✅ Endpoint​

POST /api/v2/cards/charges

This endpoint creates a payment intent using raw card information.

🔑 Authentication​

Server-to-Server API requests must include the following headers:

HeaderTypeRequiredDescription
app-idstring✅The App ID registered and secured inside the Hello Clever system.
secret-keystring✅The client's confidential key used to authenticate API requests from your server to Hello Clever.
Content-Typestring✅Always application/json.

✅ Integration Steps​

Step 1: Register Your App ID & Get Credentials​

  • Contact the Hello Clever team to register your domain and receive your app_id and secret-key.
  • Ensure your server is PCI DSS compliant before handling raw card data.

Step 2: Set Up Authentication Headers​

Include the following headers in all API requests:

app-id: YOUR_APP_ID
secret-key: YOUR_SECRET_KEY
Content-Type: application/json

Step 3: Make API Call and Handle Response​

Create a JSON request body with the required fields. See the 📥 Detail here for the complete schema.

POST https://sandbox-api.lightningpay.me/api/v2/cards/charges
{
  "amount": 1000,
  "currency": "AUD",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "billing_address": {
    "address": "123 Main Street",
    "city": "Sydney",
    "state": "NSW",
    "country": "AU",
    "postal_code": "2000"
  },
  "card_info": {
    "card_number": "4111111111111111",
    "card_expiry_month": 12,
    "card_expiry_year": 2028,
    "card_cvv_number": "123",
    "card_holder_name": "John Doe"
  },
  "payment_type": "regular",
  "capture": false,
  "external_id": "order_test_xxx",
  "return_url": "https://example.com",
  "description": "Payment for invoice #1234",
  "webhook_notification": {
    "endpoint_url": "https://merchant.com/webhook",
    "authorization_header": "Bearer xxxxxx"
  }
}

Handle the response:

  • If the payment requires 3DS authentication, redirect the customer to pay_code.3ds_url

  • When the payment reaches authorised or waiting status, a token object is returned in this response or webhook notification - save this token object for future payments

    Token object example:

    {
      "token": {
        "id": "tok_dfe1988a1ffc0d6562d3",
        "type": "card"
      }
    }

Step 4: Reusing tokens for future payments​

Call the Create Payment via Tokenisation API using your saved token. (token.id and token.type).

POST https://sandbox-api.lightningpay.me/api/v2/cards/create_payment
{
  "amount": 100,
  "currency": "AUD",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "external_id": "order_test_xxx",
  "return_url": "https://example.com",
  "capture": false,
  "webhook_notification": {
    "endpoint_url": "https://merchant.com/webhook",
    "authorization_header": "Bearer xxxxxx"
  }
}

📥 Request Body​

FieldTypeRequiredDescription
amountnumber✅Amount in the smallest currency unit (e.g., cents).
currencystring✅ISO 4217 currency code (e.g., AUD).
emailstring✅Customer’s email address.
first_namestring✅Customer’s first name.
last_namestring✅Customer’s last name.
billing_addressobject✅Customer’s billing address details.
└─ addressstring✅Address (building number, road name, etc.).
└─ citystring✅City, district, or locality.
└─ statestring✅State, province, or region.
└─ countrystring✅ISO 3166-1 alpha-2 country code.
└─ postal_codestring✅ZIP or postal code.
card_infoobject✅Card information.
└─ card_numberstring✅The card number.
└─ card_expiry_monthinteger✅Expiry month of the card (1–12).
└─ card_expiry_yearinteger✅Expiry year of the card (4-digit).
└─ card_cvv_numberstring✅The card verification value/code (3–4 digits).
└─ card_holder_namestring✅Cardholder’s name as printed on the card.
payment_typestring❌The type of payment. One of regular | unscheduled.
Default: regular.
charge_reasonstring❌Indicates the reason for a merchant-initiated payment request. One of resubmission | delayed_charge | no_show | reauthorisation.
Should be provided if payment_type is unscheduled.
previous_payment_uuidstring❌An identifier that links the payment to an existing series of payments.
Should be provided if payment_type is unscheduled.
browser_detailsobject❌Browser details information.
└─ user_agentstring✅Exact content of the HTTP user-agent header.
└─ languagestring✅The browser language as defined in IETF BCP47.
└─ color_depthnumber✅The bit depth of the colour palette for displaying images, in bits per pixel.
└─ screen_heightnumber✅Total height of the Cardholder’s screen in pixels.
└─ screen_widthnumber✅Total width of the cardholder’s screen in pixels.
└─ java_enabledboolean✅The ability of the cardholder browser execute JavaScript.
└─ time_zonenumber✅Time-zone offset in minutes between UTC and the Cardholder browser local time.
└─ accept_headerstring✅Exact content of the HTTP accept headers.
└─ javascript_enabledboolean✅The ability of the cardholder browser execute JavaScript.
ip_addressstring❌The IP address of the cardholder.
captureboolean❌Whether to auto capture the payment (if applicable).
Default: false
external_idstring✅Unique identifier for the order.
return_urlstring✅URL to redirect after success/failure.
descriptionstring✅Description for the payment.
webhook_notificationobject❌Webhook configuration details.
└─ endpoint_urlstring✅URL where webhooks will be sent.
└─ authorization_headerstring✅Authorization header for webhook.

💳 Payment Types In S2S Integration​

1️⃣ Regular Payment​

Customers can request to store their card details during a payment, which you can then use for future payments without customers having to re-enter the details.

SCA requirements
In regions that require Strong Customer Authentication (SCA) — the customer must complete a 3D Secure (3DS) challenge during the payment process.
When SCA is required, the API response includes a pay_code.3ds_url field — redirect your customer to this URL to complete the authentication.

Set up an regular payment

The payment request can include the following (optional, defaults to "regular" if not provided):

  • payment_type = "regular"

Request Example

POST https://sandbox-api.lightningpay.me/api/v2/cards/create_payment
{
  "amount": 100,
  "currency": "AUD",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "external_id": "order_test_xxx",
  "return_url": "https://example.com",
  "capture": false,
  "payment_type": "regular",
  "webhook_notification": {
    "endpoint_url": "https://merchant.com/webhook",
    "authorization_header": "Bearer xxxxxx"
  }
}

Response Example

{
  "uuid": "7PPPMXIGH",
  "name": "Testing",
  "email": "[email protected]",
  "external_id": "wc_order_6C1hcvg4T7Pom",
  "status": "pending",
  "pay_code": {
    "3ds_url": "https://3ds-auth.example.com/verify"
  },
  "currency": "AUD",
  "amount": 100,
  "total": 100,
  "paid_amount": 0,
  "is_refundable": true,
  "payment_method": "card",
  "expired_at": "",
  "webhook_notification": {
    "endpoint_url": "https://webhook.site/456adb8f-4407-4bce-90fe-2c431db19696",
    "authorization_header": "****"
  },
  "refund_information": null,
  "sender_details": {
    "card": {
      "card_type": "card",
      "card_brand": "visa",
      "card_last_4": "1111",
      "card_country": "US"
    }
  },
  "capture": false,
  "payment_type": "regular",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "created_at": "2025-05-28T04:22:21.567+0000"
}

2️⃣ Unscheduled Payment​

With an unscheduled payment agreement, you can request to store a customer’s card details during an initial transaction and perform a card-not-present transaction with the stored card at a later date.

For example, a customer may provide their card details when checking in to a hotel, but will only be charged after they check out, at which point they may have incurred additional charges.

SCA requirements
Merchant-initiated transactions fall out of scope of SCA and qualify for exemption under Merchant Initiated Exclusion, meaning 3DS authentication is not required

Set up an unscheduled payment

The payment request must include the following:

  • payment_type = "unscheduled"

It is recommended to include the payment uuid returned in the initial payment’s response in the previous_payment_uuid field to reference the original SCA-authorised transaction and improve approval rates.

To improve your approval rates and chargeback processes, we recommend that you include the charge_reason field and set it to one of the following:

  • resubmission – Use when the original purchase has occurred, but you could not get authorization at the time that goods or services were provided.
  • delayed_charge – Use when there is a delayed charge.
  • no_show – Use when the cardholder entered into an agreement to purchase but they failed to meet the terms of the agreement.
  • reauthorisation – Use when an additional purchase was made after the original purchase, typically for delayed or split orders.

Request Example

POST https://sandbox-api.lightningpay.me/api/v2/cards/create_payment
{
  "amount": 100,
  "currency": "AUD",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "external_id": "order_test_xxx",
  "return_url": "https://example.com",
  "capture": false,
  "payment_type": "unscheduled",
  "charge_reason": "delayed_charge",
  "previous_payment_uuid": "7PPPMXIGH",
  "webhook_notification": {
    "endpoint_url": "https://merchant.com/webhook",
    "authorization_header": "Bearer xxxxxx"
  }
}

⚠️ Important Note
Unscheduled payments using the Create Payment via Card Information may require 3DS authentication. If the response includes pay_code.3ds_url, redirect the customer to complete authentication.

Response Example

{
  "uuid": "7PPPMXIGH",
  "name": "Testing",
  "email": "[email protected]",
  "external_id": "wc_order_6C1hcvg4T7Pom",
  "status": "authorised",
  "pay_code": {
    "3ds_url": "https://3ds-auth.example.com/verify"
  },
  "currency": "AUD",
  "amount": 100,
  "total": 100,
  "paid_amount": 0,
  "is_refundable": true,
  "payment_method": "card",
  "expired_at": "",
  "webhook_notification": {
    "endpoint_url": "https://webhook.site/456adb8f-4407-4bce-90fe-2c431db19696",
    "authorization_header": "****"
  },
  "refund_information": null,
  "sender_details": {
    "card": {
      "card_type": "card",
      "card_brand": "visa",
      "card_last_4": "1111",
      "card_country": "US"
    }
  },
  "capture": false,
  "payment_type": "unscheduled",
  "token": {
    "id": "tok_dfe1988a1ffc0d6562d3",
    "type": "card"
  },
  "created_at": "2025-05-28T04:22:21.567+0000"
}

🔔 Webhook Notifications​

When the payment status changes (e.g., pending → authorised → received),
Hello Clever will send a webhook event to your configured endpoint.

See the Webhook Documentation for:

  • Webhook object structure
  • Token inclusion after authorisation
  • Setting up webhooks and webhook security

🧠 Notes​

  • The token returned in both the response and webhook can be reused for future payments without re-entering card details.
  • Ensure your server is PCI DSS compliant before handling raw card data.
  • Use HTTPS and secure header authentication for all API calls.
  • For client-side integrations, use the JavaScript SDK instead.

📊 Payment Statuses​

StatusMeaning
pendingCustomer started a new payment but hasn't proceeded yet
authorisedPayment has been authorised, ready to be captured
waitingPayment has been approved, awaiting funds to settle
receivedFunds have been received
expiredPayment session expired before completion
return_pendingRefund request initiated, awaiting processing
partially_refundedPartial refund has been issued to the customer
return_receivedFull amount has been refunded to the customer
return_expiredRefund expired (after 10 days)
return_rejectedRefund request was denied
failedPayment failed due to an error or decline
in_disputeCustomer has raised a dispute, under review
dispute_lostDispute has been resolved in customer's favour