Softlemon Merchant API

Introduction

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

Base URL: https://api.sandbox.softlemons.com/

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 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.

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

amount

number

required

Transaction amount.

Example:

12.5

currency

string

required

Transaction currency.

Example:

GBP

transaction_type

required

Transaction type.

Must be one of:

sale
auth

Example:

sale

vault_token

string

The tokenized_id of an existing record in the payment_instruments table.

Example:

architecto

card

object

required

Card details object.

number

string

required

Card number.

Example:

4111111111111111

exp_month

string

required

Card expire month.

Example:

exp_year

string

required

Card expire year.

Example:

cvv

string

required

Card CVV number.

Example:

111

name

string

Cardholder name.

Example:

John Doe

reference

string

Merchant reference for this transaction.

Example:

order-10001

merchant_id

integer

Required for partner API keys. Omit for merchant API keys.

Example:

123

success_url

string

Example:

http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

error_url

string

Example:

http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

customer

object

Customer details object.

merchant_customer_id

string

required

Merchant's ID of the customer.

Example:

architecto

first_name

string

required

Customer's first name.

Example:

architecto

last_name

string

required

Customer's last name.

Example:

architecto

string

required

Customer's email address.

Example:

gbailey@example.net

phone

string

Customer's phone number.

Example:

architecto

address

string

Customer's address.

Example:

architecto

city

string

Customer's city.

Example:

architecto

postal_code

string

Customer's postal code.

Example:

architecto

country_code

string

Customer's country code.

Example:

ip_address

string

Customer's IP address.

Example:

198.51.100.5

card_verification_data

object

3DS verification data object.

integer

ID of existing 3DS verification.

Example:

status

string

required

3DS verification status.

Example:

full_auth

cavv

string

required

CAVV response code.

Example:

jI3JBkkaQ1p8CBAAABy0CHUAAAA=

xid

string

XID.

Example:

A1B2C3D4E5F6G7H8I9J0

ds_trans_id

string

required

3DS transaction id.

Example:

8e187327-492c-446b-9b45-62debe6456c5

three_ds_version

string

3DS version number.

Example:

2.1

eci

string

Electronic Commerce Indicator.

Example:

Auth

Bearer

Headers

Body

{ "amount": 12.5, "currency": "GBP", "transaction_type": "sale", "vault_token": "architecto", "card": { "number": "4111111111111111", "exp_month": "12", "exp_year": "29", "cvv": "111", "name": "John Doe" }, "reference": "order-10001", "merchant_id": 123, "success_url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html", "error_url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html", "customer": { "merchant_customer_id": "architecto", "first_name": "architecto", "last_name": "architecto", "email": "gbailey@example.net", "phone": "architecto", "address": "architecto", "city": "architecto", "postal_code": "architecto", "country_code": "GB", "ip_address": "198.51.100.5" }, "card_verification_data": { "id": 16, "status": "full_auth", "cavv": "jI3JBkkaQ1p8CBAAABy0CHUAAAA=", "xid": "A1B2C3D4E5F6G7H8I9J0", "ds_trans_id": "8e187327-492c-446b-9b45-62debe6456c5", "three_ds_version": "2.1", "eci": "05" } }

Received response

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\": \"architecto\",
    \"card\": {
        \"number\": \"4111111111111111\",
        \"exp_month\": \"12\",
        \"exp_year\": \"29\",
        \"cvv\": \"111\",
        \"name\": \"John Doe\"
    },
    \"reference\": \"order-10001\",
    \"merchant_id\": 123,
    \"success_url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",
    \"error_url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",
    \"customer\": {
        \"merchant_customer_id\": \"architecto\",
        \"first_name\": \"architecto\",
        \"last_name\": \"architecto\",
        \"email\": \"gbailey@example.net\",
        \"phone\": \"architecto\",
        \"address\": \"architecto\",
        \"city\": \"architecto\",
        \"postal_code\": \"architecto\",
        \"country_code\": \"GB\",
        \"ip_address\": \"198.51.100.5\"
    },
    \"card_verification_data\": {
        \"id\": 16,
        \"status\": \"full_auth\",
        \"cavv\": \"jI3JBkkaQ1p8CBAAABy0CHUAAAA=\",
        \"xid\": \"A1B2C3D4E5F6G7H8I9J0\",
        \"ds_trans_id\": \"8e187327-492c-446b-9b45-62debe6456c5\",
        \"three_ds_version\": \"2.1\",
        \"eci\": \"05\"
    }
}"

$client = new \GuzzleHttp\Client();
$url = 'https://api.sandbox.softlemons.com/api/v1/transactions';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'amount' => 12.5,
            'currency' => 'GBP',
            'transaction_type' => 'sale',
            'vault_token' => 'architecto',
            'card' => [
                'number' => '4111111111111111',
                'exp_month' => '12',
                'exp_year' => '29',
                'cvv' => '111',
                'name' => 'John Doe',
            ],
            'reference' => 'order-10001',
            'merchant_id' => 123,
            'success_url' => 'http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html',
            'error_url' => 'http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html',
            'customer' => [
                'merchant_customer_id' => 'architecto',
                'first_name' => 'architecto',
                'last_name' => 'architecto',
                'email' => 'gbailey@example.net',
                'phone' => 'architecto',
                'address' => 'architecto',
                'city' => 'architecto',
                'postal_code' => 'architecto',
                'country_code' => 'GB',
                'ip_address' => '198.51.100.5',
            ],
            'card_verification_data' => [
                'id' => 16,
                'status' => 'full_auth',
                'cavv' => 'jI3JBkkaQ1p8CBAAABy0CHUAAAA=',
                'xid' => 'A1B2C3D4E5F6G7H8I9J0',
                'ds_trans_id' => '8e187327-492c-446b-9b45-62debe6456c5',
                'three_ds_version' => '2.1',
                'eci' => '05',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

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"
    }
}

Capture Transaction

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

Example:

application/json

URL Parameters

transaction_id

integer

required

The ID of the transaction.

Example:

Body Parameters

amount

number

Transaction amount.

Example:

12.5

Auth

Bearer

Headers

URL Parameters

Body

{ "amount": 12.5 }

Received response

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"
    }
}

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

Example:

application/json

URL Parameters

transaction_id

integer

required

The ID of the transaction.

Example:

Body Parameters

amount

number

Transaction amount.

Example:

12.5

reason

string

Reason for refund.

Example:

architecto

Auth

Bearer

Headers

URL Parameters

Body

{ "amount": 12.5, "reason": "architecto" }

Received response

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\": \"architecto\"
}"

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"
    }
}

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

Example:

application/json

URL Parameters

transaction_id

integer

required

The ID of the transaction.

Example:

Auth

Bearer

Headers

URL Parameters

Received response

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"
    }
}

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

Example:

application/json

URL Parameters

transaction_id

integer

required

The ID of the transaction.

Example:

Body Parameters

amount

number

Transaction amount.

Example:

12.5

reason

string

Reason for refund.

Example:

architecto

Auth

Bearer

Headers

URL Parameters

Body

{ "amount": 12.5, "reason": "architecto" }

Received response

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\": \"architecto\"
}"

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"
    }
}

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.

Headers

Authorization

Example:

Bearer {YOUR_AUTH_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

amount

number

required

Transaction amount.

Example:

12.5

currency

string

required

Transaction currency.

Example:

GBP

card

object

required

Card details object.

name

string

required

Cardholder name.

Example:

John Doe

number

string

required

Card number.

Example:

4111111111111111

exp_month

string

required

Card expire month.

Example:

exp_year

string

required

Card expire year.

Example:

cvv

string

Must be at least 3 characters. Must not be greater than 4 characters.

Example:

iyvd

auth_url

string

required

Authorization callback url.

Example:

http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

Auth

Bearer

Headers

Body

{ "amount": 12.5, "currency": "GBP", "card": { "name": "John Doe", "number": "4111111111111111", "exp_month": "12", "exp_year": "29", "cvv": "iyvd" }, "auth_url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html" }

Received response

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\": \"29\",
        \"cvv\": \"iyvd\"
    },
    \"auth_url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\"
}"

Example response:

{
    "success": true,
    "message": "3DS authentication completed (frictionless)",
    "code": "",
    "data": {
        "id": 166,
        "amount": 12,
        "currency": "EUR",
        "version": null,
        "eci": "05",
        "cavv": "AAABA0UREQAAAAAAAAAAAAAAAAA=",
        "xid": null,
        "ds_trans_id": "6b66be83-f692-405c-9079-92f7182af5e5",
        "status": "full_auth",
        "auth_type": "frictionless",
        "challenge_url": "https://softlemon.com/api/3ds/callback",
        "post_url": null,
        "html": null,
        "created_at": "2025-06-12 09:47:15",
        "updated_at": "2025-06-12 09:47:15"
    }
}