Slikair API DOC - V2

JSON in, JSON out. Authenticate with a merchant-token header and send a unique Idempotency-Key on create calls.

Version 2.0https://devsilo.xyz/api/v2support@slikair.com

Overview

The slikair Payments API

This page documents the Slikair V2 API only: environments, authentication, the merchant JWT used for tokenization, every endpoint group, webhook events, schema tables and the code tables you need when handling responses and notifications.

Schema tables are based on the provided Slikair V2 OpenAPI path, webhook, security and component files.

Slikair API DOC - V2

Version 2.0

https://devsilo.xyz/api/v2

Environments

Sandbox first, then live

Sandbox

https://devsilo.xyz/api/v2

Mirrors live behaviour for testing with the Demo provider. Note that sandbox does not support payouts.

Live

Provided by the slikair team

Your live account and base URL are provided by the slikair team when you are ready to go live.

Authentication

merchant-token on every call

All requests and responses are JSON.
Standard HTTP verbs and status codes are used.
Authenticate every call with a merchant-token header.
Create calls require a unique Idempotency-Key header per payment attempt.

Scheme	Type	Where to find it
merchant-token	apiKey — header	Authenticates API requests. Found in My Account > Integration settings.
merchant_id	apiKey-style credential identifier	Provided by slikair. Found in My Account > Integration settings.
merchant_site_id	apiKey-style site identifier	Provided by slikair. Found in My Account > Integration settings.

Merchant JWT

Signed card data for tokenization

The tokenization endpoints /payment/create/tokenization and /payment/create/token require a merchant_jwt.
The JWT is a standard header.payload.signature string.
The payload is read for card data or the stored token reference.
The signature is verified downstream by the payment gateway and the Card Data Vault.
JWTs are signed with EdDSA (Ed25519); include kid in the header for the key id.
The signing key is provisioned during onboarding; contact support@slikair.com to enable tokenization and obtain it.
iat must be within 120 seconds of server time.

Tokenize (op = tokenize)

jti	Unique JWT id
op	tokenize
sub	merchant_id
iat	Issued-at, within 120 seconds of server time
cardholder_number	Card number
cardholder_name	Cardholder name
cardholder_exp_month	Expiry month
cardholder_exp_year	Expiry year

Pay with token (op = decrypt)

jti	Unique JWT id
op	decrypt
sub	merchant_id
iat	Issued-at, within 120 seconds of server time
token	Stored card token reference

Endpoints

Payment, tokenization and payout sessions

Payment sessions

Create a customer payment and read its current state.

POST/payment/createCreate PaymentcreatePaymentV2

Initiates a payment transaction. The request structure varies by payment_method.

Headers

merchant-tokenContent-TypeIdempotency-Key

Request schema

V2PaymentRequest

Responses

200	V2PaymentResponse
400	V2ErrorResponse
401	V2ErrorResponse
500	V2ErrorResponse

Examples

credit_cardcryptoopen_bankingblikgooglepayapplepayinterac

Example — credit_card

curl -X POST https://devsilo.xyz/api/v2/payment/create \
  -H "merchant-token: $SLIKAIR_MERCHANT_TOKEN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "9e07802d51264b02b4b3ef09dfb94219",
    "merchant_site_id": "1234",
    "payment_method": "credit_card",
    "device_ip": "203.0.113.10",
    "amount": 99.99,
    "currency": "EUR",
    "email": "john.doe@example.com",
    "request_id": "order-1001",
    "country": "NLD",
    "first_name": "John",
    "last_name": "Doe",
    "notification_link": "https://example.com/webhook",
    "success_url": "https://example.com/success",
    "pending_url": "https://example.com/pending",
    "fail_url": "https://example.com/fail",
    "back_url": "https://example.com/cart",
    "mobile": "+31600000000",
    "address": "Main Street 1",
    "city": "Amsterdam",
    "zipCode": "1011AB",
    "state": "NH",
    "birthDate": "1990-01-01",
    "cardNum": "4111111111111111",
    "cardHolder": "John Doe",
    "cardExpireMonth": "12",
    "cardExpireYear": "2030",
    "cardCvv": "123"
  }'

POST/payment/get-statusGet Payment StatusgetPaymentStatusV2

Retrieves the current status of a payment transaction.

Headers

merchant-tokenContent-Type

Request schema

V2GetPaymentStatusRequest

Responses

200	V2GetPaymentStatusResponse
400	V2ErrorResponse	Validation error
401	V2ErrorResponse	Unauthorized

Example request

{
  "merchant_id": "9e07802d51264b02b4b3ef09dfb94219",
  "payin_id": "b0f8f0f4-1f5d-4d1a-8f0e-9c1d2e3f4a5b"
}

Tokenization

Vault card data with a merchant-signed JWT, then charge the stored token.

POST/payment/create/tokenizationCreate Payment TokenizationcreateTokenization

Initiates a credit-card payment and vaults the card for later use with /payment/create/token. The tokenization result arrives asynchronously at tokenization_notification_url. Credit cards only, consent must be true, and card data is supplied inside merchant_jwt.

Headers

merchant-tokenContent-TypeIdempotency-Key

Request schema

V2TokenizationRequest

Responses

200	V2PaymentResponse
400	V2ErrorResponse
401	V2ErrorResponse
500	V2ErrorResponse

Examples

credit_card_tokenize

Example — tokenization JWT payload

{
  "jti": "e0f0a2f4-6f1e-4a5b-9a0e-1f2c3d4e5f60",
  "op": "tokenize",
  "sub": "9e07802d51264b02b4b3ef09dfb94219",
  "iat": 1735689600,
  "cardholder_number": "4111111111111111",
  "cardholder_name": "John Doe",
  "cardholder_exp_month": "12",
  "cardholder_exp_year": "2030"
}

POST/payment/create/tokenCreate Payment with TokencreateWithToken

Charges a vaulted card by redeeming the token inside merchant_jwt. No PAN, cardholder name or expiry is sent; CVV is collected on every charge. The merchant_jwt payload uses op=decrypt, sub and token.

Headers

merchant-tokenContent-TypeIdempotency-Key

Request schema

V2PayWithTokenRequest

Responses

200	V2PaymentResponse
400	V2ErrorResponse
401	V2ErrorResponse
500	V2ErrorResponse

Examples

pay_with_token

Example — pay-with-token JWT payload

{
  "jti": "b71c9f0a-2c33-4d7e-8f61-52a0d9c7e311",
  "op": "decrypt",
  "sub": "9e07802d51264b02b4b3ef09dfb94219",
  "iat": 1735689600,
  "token": "tok_9f8c1b2a3d4e"
}

Payout sessions

Send funds to the consumer and track the payout state.

POST/payouts/createCreate payoutcreatePayoutV2

Creates a payout withdrawal with multiple methods and modes. Sandbox does not support payouts.

Headers

merchant-tokenContent-TypeIdempotency-Key

Request schema

V2PayoutRequest

Responses

200	V2PayoutResponse
400	V2PayoutCreateError
401	V2PayoutError
500	V2PayoutError

Examples

credit_cardcryptoopen_bankingfps

Example — credit_card payout

{
  "merchant_id": "9e07802d51264b02b4b3ef09dfb94219",
  "site_id": "1234",
  "method": "credit_card",
  "mode": "direct",
  "amount": 50.00,
  "currency": "EUR",
  "merchantReference": "payout-2001",
  "country": "NLD",
  "notificationUrl": "https://example.com/payout-webhook",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+31600000000"
  },
  "paymentDetails": {
    "method": "credit_card",
    "cardNum": "4111111111111111",
    "cardHolder": "John Doe",
    "cardExpireMonth": "12",
    "cardExpireYear": "2030"
  }
}

POST/payouts/get-statusGet Payout StatusgetPayoutStatusV2

Retrieves the payout status by payout ID.

Headers

merchant-tokenContent-Type

Request schema

V2PayoutStatusRequest

Responses

200	V2PayoutStatusResponse
400	V2PayoutError
500	V2PayoutError

Webhooks

Direct Merchant Notifications

Event	Summary	Request schema	Response
v2_payin_notification	PayIn Notification (DMN)Server-to-server notification with the final pay-in result.	V2PayinNotification	200 acknowledges receipt
v2_tokenization_notification	Tokenization Result NotificationDelivered to tokenization_notification_url with the vaulted token and card metadata.	V2TokenizationNotification	200 acknowledges receipt
v2_payout_notification	Payout notificationServer-to-server notification with the payout result.	V2PayoutWebhook	200 acknowledges receipt

Schemas

Request, response and notification objects

Schema tables are based on the provided Slikair V2 OpenAPI path, webhook, security and component files.

V2PaymentRequest

Body of POST /payment/create. Method-specific fields apply per payment_method.

Field	Required	Type	Description	Example
merchant_id	required	string	Merchant identifier from Integration settings.
merchant_site_id	required	string	Site identifier from Integration settings.
payment_method	required	enum	One of the supported V2 payment methods.	credit_card
amount	required	number	2 decimals for fiat, up to 10 decimals for crypto.	99.99
currency	required	string	ISO 4217 currency code.	EUR
email	required	string	Customer email address.
request_id	required	string	Unique merchant reference for the attempt.
country	required	string	ISO 3166-1 alpha-3 country code.	NLD
notification_link	required	string (uri)	Webhook URL for the pay-in notification.
success_url	required	string (uri)	Redirect on success.
pending_url	required	string (uri)	Redirect while pending.
fail_url	required	string (uri)	Redirect on failure.
back_url	required	string (uri)	Redirect when the customer goes back.
device_ip	required	string	Customer device IP address.
first_name	required	string
last_name	required	string
mobile	optional	string	Required for credit_card, credit_card_ftd, interac, blik, googlepay, applepay.
address	optional	string	Required for credit_card, credit_card_ftd, interac, googlepay, applepay.
city	optional	string	Required for the same methods as address.
zipCode	optional	string	Required for the same methods as address.
state	optional	string	Required for credit_card, credit_card_ftd, googlepay, applepay.
birthDate	optional	string	Required for the same methods as state.
cardNum	optional	string	Required for credit_card and credit_card_ftd.
cardHolder	optional	string	Required for credit_card and credit_card_ftd.
cardExpireMonth	optional	string	Required for credit_card and credit_card_ftd.
cardExpireYear	optional	string	Required for credit_card and credit_card_ftd.
cardCvv	optional	string	Required for credit_card and credit_card_ftd.

V2PaymentMethod

Payment method type. Determines which fields are required.

Field	Required	Type	Description	Example
value	required	enum	credit_card \| credit_card_ftd \| open_banking \| crypto \| blik \| googlepay \| applepay \| interac	credit_card

V2PaymentResponse

Field	Required	Type	Description
status	optional	enum	success \| failed
status_code	optional	integer
request_id	optional	uuid / string
payin_id	optional	uuid
redirect_url	optional	string (uri)
created_at	optional	string (date-time)

V2ErrorResponse

Field	Required	Type	Description
status	optional	enum	error
status_code	optional	integer
reason_code	optional	string
error_code	optional	string	5 digits
request_id	optional	uuid / string
message	optional	string
payin_id	optional	uuid \| null
details	optional	object	Field validation errors.

V2GetPaymentStatusRequest

Field	Required	Type	Description	Example
merchant_id	required	string
payin_id	required	uuid	Payment identifier returned on create.

V2GetPaymentStatusResponse

Field	Required	Type	Description
status	optional	enum	initiated \| processing \| succeeded \| failed \| kyc_required \| refunded \| chargeback
status_code	optional	integer
payin_id	optional	uuid
request_id	optional	string
payment_method	optional	string
amount	optional	number
currency	optional	string

V2TokenizationRequest

Body of POST /payment/create/tokenization. Credit cards only.

Field	Required	Type	Description	Example
merchant_id	required	string
merchant_site_id	required	string
payment_method	required	enum	credit_card only.	credit_card
amount	required	number
currency	required	string
email	required	string
request_id	required	string
country	required	string	ISO 3166-1 alpha-3.
first_name	required	string
last_name	required	string
notification_link	required	string (uri)
success_url	required	string (uri)
pending_url	required	string (uri)
fail_url	required	string (uri)
back_url	required	string (uri)
device_ip	required	string
mobile	required	string
address	required	string
city	required	string
zipCode	required	string
state	required	string
birthDate	required	string
cardCvv	required	string	Body field; never tokenized.
merchant_jwt	required	string	Carries the tokenize card data.
consent	required	boolean	Must be true.	true
tokenization_notification_url	required	string (uri)	Receives the tokenization result; separate from notification_link.

V2PayWithTokenRequest

Body of POST /payment/create/token. CVV must be collected on every charge.

Field	Required	Type	Description	Example
merchant_id	required	string
merchant_site_id	required	string
payment_method	required	enum	credit_card only.	credit_card
amount	required	number
currency	required	string
email	required	string
request_id	required	string
country	required	string
first_name	required	string
last_name	required	string
notification_link	required	string (uri)
success_url	required	string (uri)
pending_url	required	string (uri)
fail_url	required	string (uri)
back_url	required	string (uri)
device_ip	required	string
mobile	required	string
address	required	string
city	required	string
zipCode	required	string
state	required	string
birthDate	required	string
merchant_jwt	required	string	Carries the decrypt token data.
cardCvv	required	string	Collected on every charge.

V2PayinNotification

Field	Required	Type	Description
status	optional	enum	processing \| succeeded \| failed \| refunded \| chargeback
status_code	optional	integer
reason_code	optional	string
payin_id	optional	uuid
merchant_reference	optional	string
payment_method	optional	string
amount	optional	number
currency	optional	string
decline_reason	optional	string

V2TokenizationNotification

Field	Required	Type	Description
payin_id	required	uuid
request_id	required	string
status_code	required	integer
token	optional	string	Vaulted card token.
brand	optional	string
last4	optional	string
expDate	optional	string
error_message	optional	string

V2PayoutRequest

Field	Required	Type	Description
merchant_id	required	string
method	required	enum	credit_card \| open_banking \| crypto \| fps
site_id	required	string
mode	required	enum	direct \| hosted
amount	required	number
currency	required	string
merchantReference	required	string
country	required	string
notificationUrl	required	string (uri)
customer	required	V2PayoutCustomer
successUrl	optional	string (uri)
pendingUrl	optional	string (uri)
failureUrl	optional	string (uri)
paymentDetails	optional	V2PaymentDetails	Discriminated by method.

V2PayoutCustomer

Field	Required	Type
firstName	required	string
lastName	required	string
email	required	string
phone	required	string

V2PaymentDetails

Discriminated by method: credit_card → V2CreditCardDetails, open_banking → V2OpenBankingDetails, crypto → V2CryptoDetails, fps → V2FpsDetails.

Field	Required	Type	Description	Example
method	required	enum	credit_card \| open_banking \| crypto \| fps

V2CreditCardDetails

Field	Required	Type	Description
method	required	const	credit_card
cardNum	required	string
cardHolder	required	string
cardExpireMonth	required	string
cardExpireYear	required	string

V2OpenBankingDetails

Field	Required	Type	Description
method	required	const	open_banking
accountName	required	string
iban	required	string
address	required	string
city	required	string
zipCode	required	string

V2CryptoDetails

Field	Required	Type	Description
method	required	const	crypto
convertTo	required	enum	ETH \| USDT \| USDC \| BTC
toAddress	required	string

V2FpsDetails

Field	Required	Type	Description
method	required	const	fps
accountName	required	string
accountNumber	required	string
sortCode	required	string
address	required	string
city	required	string
zipCode	required	string

V2PayoutResponse

Field	Required	Type	Description
status	optional	enum	initiated \| processing \| succeeded \| failed
description	optional	string
timestamp	optional	string (date-time)
payoutId	optional	string
requestId	optional	string

V2PayoutCreateError

Error body returned by POST /payouts/create.

Field	Required	Type	Description	Example
status	required	enum	failed	failed
description	required	string	Human readable error summary.	invalid request
errors	required	string[]	Field level validation errors.	[]
payoutId	optional	integer	Present only when the payout was created before the failure.	123456
reasonCode	required	string	Machine readable reason.	TRANSIENT_ERROR
errorCode	required	string	Numeric error code.	42718

V2PayoutError

Generic payout error body, used by payout status and token flows.

Field	Required	Type	Description	Example
status	required	enum	failed	failed
description	required	string	Human readable error summary.	invalid request
errors	required	string[]	Field level validation errors.	[]
reasonCode	required	string	Machine readable reason.	INVALID_OR_EXPIRED_TOKEN
errorCode	required	string	Numeric error code.	32201

V2PayoutStatusRequest

Field	Required	Type	Description	Example
merchant_id	required	string
payoutId	required	string

V2PayoutStatusResponse

Field	Required	Type	Description
status	optional	enum	initiated \| processing \| succeeded \| failed
payoutId	optional	string
idempotencyKey	optional	string

V2PayoutWebhook

Field	Required	Type	Description
status	optional	enum	initiated \| processing \| succeeded \| failed
reason	optional	string
payoutId	optional	string
merchantReference	optional	string
amount	optional	number
currency	optional	string
statusCode	optional	string
reasonCode	optional	string

Payment methods

Accepted payment_method values

credit_cardcredit_card_ftdopen_bankingcryptoblikgooglepayapplepayinterac

Payout methods

credit_cardopen_bankingcryptofps

Status codes

Payment and payout statuses

Payment status codes

100	Pending redirect
101	Pending
200	Success
301	User has deposit in progress, please wait 60 seconds
302	Declined due to risk decision
303	Customer reached daily deposit limit for this method
304	KYC rejected
305	User error
306	Customer reached daily decline limit for this method
317	Invalid CVV - CVV should be between 3 or 4 digits long
318	Invalid expiration date - card date must be valid and not expired
319	Invalid cardholder name - card holder should be a minimum of one words
320	BIN block enforced
401	Unsupported country
402	Unsupported currency
500	Provider declined
501	System error
502	Unauthorized
503	No amount in the request
504	Amount is not a valid value
505	Wrong site id
506	Missing payment method
507	Wrong payment method for this provider
508	Wrong payment method
509	Payment method not enabled for site
510	Missing params
511	Invalid checksum
512	Invalid params values
513	User exceeded daily deposit limit by provider
514	Merchant not active - contact support team
515	An unexpected error occurred. Please try again in a few moments.
516	Transaction could not be processed at this time.
517	Credit card failed Luhn validation.
518	There was an issue with this transaction, please try again.

Payout status codes

P100	Payout initiated
P101	Payout processing
P200	Payout succeeded
C402	Invalid or missing required fields in the request
C403	Merchant payout wallet is missing
C404	Currency not supported for payout
C405	Insufficient balance in the wallet for payout
C501	General gateway declined

Reason codes

Machine-readable failure reasons

INVALID_REQUESTINVALID_OR_EXPIRED_TOKENINVALID_MERCHANT_JWTINVALID_CHECKSUMINVALID_PARAMSMISSING_PARAMSSYSTEM_ERRORTRANSIENT_ERRORNO_ROUTE_AVAILABLEINVALID_SITEPAYMENT_METHOD_NOT_ENABLEDMERCHANT_INACTIVEUNSUPPORTED_COUNTRYUNSUPPORTED_CURRENCYMISSING_PAYMENT_METHODINVALID_PAYMENT_METHODINVALID_PAYMENT_METHOD_FOR_PROVIDERINVALID_CARD_DATAINVALID_CVVINVALID_CARD_NUMBERINVALID_EXPIRYINVALID_CARDHOLDER_NAMEINVALID_ADDRESSINVALID_PHONETHREE_DS_FAILEDUSER_ABANDONEDMISSING_AMOUNTINVALID_AMOUNTAMOUNT_BELOW_MINIMUMINSUFFICIENT_FUNDSRISK_BLOCKEDBLACKLISTED_BLOCKEDBIN_BLACKLISTEDEXPIRED_CARDDO_NOT_HONORAUTHENTICATION_FAILEDGENERIC_DECLINEDAILY_LIMIT_EXCEEDEDISSUER_DECLINED_NO_INFORESTRICTED_CARDLOST_OR_STOLEN_CARDCARD_LIMIT_EXCEEDEDCANCELLED_BY_BANKDECLINE_LIMIT_EXCEEDEDGATEWAY_UNAVAILABLEGATEWAY_TIMEOUT

Need something that is not covered here? Talk to an integration engineer.