Softlemon Merchant API

Introduction

Production-ready merchant integration endpoints for admin-provisioned API keys.

This documentation covers the merchant integration surface for admin-provisioned API keys.

Use these endpoints when a merchant is processing payments for its own account.

API keys are created by your SoftLemon admin team and delivered securely. Self-service onboarding and API key generation are not currently available.

3D Secure Integration Flow

SoftLemon uses a server-managed 3DS flow. You do not need to handle CAVV, ECI, or DS Transaction IDs yourself.

Step 1 — Initiate 3DS Verification

POST /api/v1/3ds/verify with card details, amount, currency, and auth_url (your frontend return URL).

Step 2 — Handle the response

  • Frictionless: The response returns immediately with status: full_auth. Use the returned id in Step 4.
  • Challenge: The response includes a challenge_url. Redirect the cardholder to this URL to complete the bank challenge.

Step 3 — Cardholder completes challenge (if applicable)

After the cardholder completes the challenge, they are redirected to your auth_url with query parameters:

?card_verification_id={id}&status=full_auth (or status=failed)

Step 4 — Initiate the transaction

POST /api/v1/transactions with card_verification_data.id set to the verification ID from Step 1 or the redirect.

"card_verification_data": { "id": 43 }

The API automatically retrieves the stored 3DS authentication data (CAVV, ECI, etc.) and passes it to the payment gateway.

3D Secure test cards

Use these sandbox cards when testing POST /api/v1/3ds/verify.

Scheme Flow Returns method data Card number Expected result
Visa Frictionless Y 4200000000000091 Successful frictionless authentication.
Visa Frictionless Y 4200000000000109 Attempted authentication.
Visa Frictionless N 4200000000000026 Successful frictionless authentication.
Visa Frictionless N 4200000000000059 Attempted authentication.
Visa Error N 4012001037461114 Technical error.
Visa Error N 4012001037141112 User not enrolled.
Visa Not Applicable N/A 4532497088771651 Card not participating.
Visa Challenge Y 4200000000000042 Challenge flow.
Visa Challenge Y 4200000000000067 Challenge flow.
Visa Challenge N 4200000000000018 Challenge flow.
Visa Challenge N 4200000000000075 Challenge flow.
Mastercard Frictionless Y 5200000000000007 Successful frictionless authentication.
Mastercard Frictionless Y 5200000000000023 Attempted authentication.
Mastercard Frictionless N 5200000000000056 Successful frictionless authentication.
Mastercard Frictionless N 5200000000000006 Attempted authentication.
Mastercard Error N 5434580000000006 Technical error.
Mastercard Error N 5457350076543210 User not enrolled.
Mastercard Not Applicable N/A 5497260847316287 Card not participating.
Mastercard Challenge Y 5200000000000015 Challenge flow.
Mastercard Challenge Y 5200000000000049 Challenge flow.
Mastercard Challenge N 5200000000000064 Challenge flow.
Mastercard Challenge N 5200000000000072 Challenge flow.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Use the API key provisioned by your SoftLemon admin team. Self-service onboarding and API key generation are not currently available.

Transactions

Initiate Transaction

POST
https://api.sandbox.softlemons.com
/api/v1/transactions
requires authentication

Initiate a new transaction (sale or auth).

Merchant API keys can call this endpoint for their own account. Partner API keys can also call this endpoint, but they must include merchant_id for a merchant linked to that partner. Capture, refund, and void operations remain merchant-only.

If you have completed a 3DS verification, include card_verification_data.id with the verification ID. The API automatically retrieves the stored 3DS authentication data (CAVV, ECI, DS Transaction ID) — you do not need to send those fields yourself.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://api.sandbox.softlemons.com/api/v1/transactions" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 12.5,
    \"currency\": \"GBP\",
    \"transaction_type\": \"sale\",
    \"vault_token\": \"vtok_a1b2c3d4e5f6\",
    \"card\": {
        \"number\": \"4111111111111111\",
        \"exp_month\": \"12\",
        \"exp_year\": \"2030\",
        \"cvv\": \"111\",
        \"name\": \"John Doe\"
    },
    \"reference\": \"order-10001\",
    \"merchant_id\": 123,
    \"success_url\": \"https:\\/\\/yoursite.com\\/checkout\\/success\",
    \"error_url\": \"https:\\/\\/yoursite.com\\/checkout\\/error\",
    \"customer\": {
        \"merchant_customer_id\": \"cust-001\",
        \"first_name\": \"John\",
        \"last_name\": \"Doe\",
        \"email\": \"john.doe@example.com\",
        \"phone\": \"+441234567890\",
        \"address\": \"1 High Street\",
        \"city\": \"London\",
        \"postal_code\": \"SW1A 1AA\",
        \"country_code\": \"GB\",
        \"ip_address\": \"198.51.100.5\"
    },
    \"card_verification_data\": {
        \"id\": 43
    }
}"
Example response:
{
    "success": true,
    "message": "Transaction initiated",
    "code": "",
    "data": {
        "id": 2,
        "related_trans_id": null,
        "merchant_id": 1,
        "cardholder_id": 2,
        "amount": 1250,
        "currency": "EUR",
        "status": "auth",
        "transaction_type": "auth",
        "merchant_trans_id": "ORDER-912346",
        "acquirer_trans_id": "514009741995",
        "acquirer_auth_code": "400066",
        "acquirer_ref_num": "741995",
        "ip_address": "172.19.0.7",
        "updated_at": "2025-05-20T09:18:48.000000Z",
        "created_at": "2025-05-20T09:18:47.000000Z"
    }
}
{
    "success": false,
    "message": "Authentication failed",
    "code": "ERR_AUTH_FAILED",
    "data": null
}
{
    "success": false,
    "message": "Validation errors",
    "code": "ERR_VALIDATION_FAILED",
    "data": null,
    "errors": {
        "amount": [
            "The transaction amount must be a number."
        ]
    }
}

Capture Transaction (only applies when transaction_type is auth)

POST
https://api.sandbox.softlemons.com
/api/v1/transactions/{transaction_id}/capture
requires authentication

Capture a previously authorized transaction.

This endpoint is intended for merchant API keys managing their own transactions.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

transaction_id
integer
required

The ID of the transaction.

Example:
16

Body Parameters

Example request: 
curl --request POST \
    "https://api.sandbox.softlemons.com/api/v1/transactions/16/capture" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 12.5
}"
Example response:
{
    "success": true,
    "message": "Transaction captured",
    "code": "",
    "data": {
        "id": 3,
        "related_trans_id": 2,
        "merchant_id": 1,
        "cardholder_id": 2,
        "amount": 1250,
        "currency": "EUR",
        "status": "captured",
        "transaction_type": "capture",
        "merchant_trans_id": "ORDER-912346",
        "acquirer_trans_id": "995140741995",
        "acquirer_auth_code": "400066",
        "acquirer_ref_num": "741995",
        "ip_address": "172.19.0.7",
        "updated_at": "2025-05-20T09:18:48.000000Z",
        "created_at": "2025-05-20T09:18:47.000000Z"
    }
}
{
    "success": false,
    "message": "Authentication failed",
    "code": "ERR_AUTH_FAILED",
    "data": null
}
{
    "success": false,
    "message": "Validation errors",
    "code": "ERR_VALIDATION_FAILED",
    "data": null,
    "errors": {
        "amount": [
            "The capture amount must be a number."
        ]
    }
}

Refund Transaction

POST
https://api.sandbox.softlemons.com
/api/v1/transactions/{transaction_id}/refund
requires authentication

Refund a previously captured transaction.

This endpoint is intended for merchant API keys managing their own transactions.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

transaction_id
integer
required

The ID of the transaction.

Example:
16

Body Parameters

Example request: 
curl --request POST \
    "https://api.sandbox.softlemons.com/api/v1/transactions/16/refund" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 12.5,
    \"reason\": \"Customer returned item\"
}"
Example response:
{
    "success": true,
    "message": "Transaction refunded",
    "code": "",
    "data": {
        "id": 4,
        "related_trans_id": 3,
        "merchant_id": 1,
        "cardholder_id": 2,
        "amount": 1250,
        "currency": "EUR",
        "status": "refunded",
        "transaction_type": "refund",
        "merchant_trans_id": "ORDER-912346",
        "acquirer_trans_id": "514009741995",
        "acquirer_auth_code": "400066",
        "acquirer_ref_num": "741995",
        "ip_address": "172.19.0.7",
        "updated_at": "2025-05-20T09:18:48.000000Z",
        "created_at": "2025-05-20T09:18:47.000000Z"
    }
}
{
    "success": false,
    "message": "Authentication failed",
    "code": "ERR_AUTH_FAILED",
    "data": null
}
{
    "success": false,
    "message": "Validation errors",
    "code": "ERR_VALIDATION_FAILED",
    "data": null,
    "errors": {
        "amount": [
            "The refund amount must be a number."
        ]
    }
}

Transaction Status

GET
https://api.sandbox.softlemons.com
/api/v1/transactions/{transaction_id}/status
requires authentication

Get the status of a transaction.

Merchant API keys can check their own transactions. Partner API keys can check transactions belonging to linked merchants they are allowed to access. Capture, refund, and void operations remain merchant-only even when a partner can read status.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

transaction_id
integer
required

The ID of the transaction.

Example:
16
Example request: 
curl --request GET \
    --get "https://api.sandbox.softlemons.com/api/v1/transactions/16/status" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "message": "Transaction status",
    "code": "",
    "data": {
        "id": 2,
        "related_trans_id": null,
        "merchant_id": 1,
        "cardholder_id": 2,
        "amount": 1250,
        "currency": "EUR",
        "status": "auth",
        "transaction_type": "auth",
        "merchant_trans_id": "ORDER-912346",
        "acquirer_trans_id": "514009741995",
        "acquirer_auth_code": "400066",
        "acquirer_ref_num": "741995",
        "ip_address": "172.19.0.7",
        "updated_at": "2025-05-20T09:18:48.000000Z",
        "created_at": "2025-05-20T09:18:47.000000Z"
    }
}
{
    "success": false,
    "message": "Authentication failed",
    "code": "ERR_AUTH_FAILED",
    "data": null
}

Void Transaction

POST
https://api.sandbox.softlemons.com
/api/v1/transactions/{transaction_id}/void
requires authentication

Void a previously initiated auth transaction.

This endpoint is intended for merchant API keys managing their own transactions.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

transaction_id
integer
required

The ID of the transaction.

Example:
16

Body Parameters

Example request: 
curl --request POST \
    "https://api.sandbox.softlemons.com/api/v1/transactions/16/void" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 12.5,
    \"reason\": \"Customer requested cancellation\"
}"
Example response:
{
    "success": true,
    "message": "Transaction voided",
    "code": "",
    "data": {
        "id": 4,
        "related_trans_id": 3,
        "merchant_id": 1,
        "cardholder_id": 2,
        "amount": 1250,
        "currency": "EUR",
        "status": "voided",
        "transaction_type": "void",
        "merchant_trans_id": "ORDER-912346",
        "acquirer_trans_id": "514009741995",
        "acquirer_auth_code": "400066",
        "acquirer_ref_num": "741995",
        "ip_address": "172.19.0.7",
        "updated_at": "2025-05-20T09:18:48.000000Z",
        "created_at": "2025-05-20T09:18:47.000000Z"
    }
}
{
    "success": false,
    "message": "Authentication failed",
    "code": "ERR_AUTH_FAILED",
    "data": null
}
{
    "success": false,
    "message": "Validation errors",
    "code": "ERR_VALIDATION_FAILED",
    "data": null,
    "errors": {
        "amount": [
            "The void amount must be a number."
        ]
    }
}

Card Verification

Initiate Card Verification

POST
https://api.sandbox.softlemons.com
/api/v1/3ds/verify
requires authentication

Initiate a 3D Secure card verification process.

This endpoint is intended for merchant API keys before a payment request.

The response will indicate either a frictionless flow (cardholder is silently authenticated — use the returned id directly) or a challenge flow (redirect the cardholder to the challenge_url to complete the bank challenge, then use the card_verification_id from the redirect).

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://api.sandbox.softlemons.com/api/v1/3ds/verify" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": 12.5,
    \"currency\": \"GBP\",
    \"card\": {
        \"name\": \"John Doe\",
        \"number\": \"4111111111111111\",
        \"exp_month\": \"12\",
        \"exp_year\": \"2030\",
        \"cvv\": \"123\"
    },
    \"auth_url\": \"https:\\/\\/yoursite.com\\/checkout\\/3ds-complete\"
}"
Example response:
{
    "success": true,
    "message": "3DS authentication completed (frictionless)",
    "code": "",
    "data": {
        "id": 166,
        "amount": 1250,
        "currency": "EUR",
        "version": "2.2.0",
        "eci": "05",
        "cavv": "AAABA0UREQAAAAAAAAAAAAAAAAA=",
        "xid": null,
        "ds_trans_id": "6b66be83-f692-405c-9079-92f7182af5e5",
        "status": "full_auth",
        "auth_type": "frictionless",
        "challenge_url": "https://yoursite.com/checkout/3ds-complete",
        "post_url": null,
        "html": null,
        "created_at": "2025-06-12 09:47:15",
        "updated_at": "2025-06-12 09:47:15"
    }
}
{
    "success": false,
    "message": "Authentication failed",
    "code": "ERR_AUTH_FAILED",
    "data": null
}
{
    "success": false,
    "message": "Validation errors",
    "code": "ERR_VALIDATION_FAILED",
    "data": null,
    "errors": {
        "amount": [
            "The amount is required."
        ]
    }
}