API integration

Direct integration

Direct integration lets you accept payments using your own payment page.

Interaction flow:

info

Using direct integration requires PCI DSS certification.

If you collect card data yourself, use the following validation:

• Validate the card expiration date.

• Validate the card number using the Luhn algorithm.

• Make sure the entered CVV/CVC contains digits only.
  
  

Direct integration specifics:

1. The payment page must use HTTPS.
2. Each customer's data must be stable and unique.
3. Use the POST HTTP method.
   
   

Request parameters:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	direct
method	METHOD	✅	Payment method (auth or purchase)
amount	Number	✅	Transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identified of order
order_3ds_bypass	String	✅	3-D Secure flow option
cc_number	CC_NUMBER		Card number
exp_month	Number		Card expiration month field
exp_year	Number		Card expiration year field
card_cvv	String		Card CVV
cc_token	String		Card token
network_transaction_id	String		Identifier used by financial networks (Visa, Mastercard, AmEx, etc.) to identify a transaction. This value is present if it is returned by the financial network in the authorization response.
three_d_secure	Object		External 3DS parameters.
products	Array[Product]		Array of products to be paid. The structure of the products parameter must meet the following requirements, depending on whether fiscalization is enabled or not: - If fiscalization is not used. - If fiscalization is used.
customer_id	String		Customer’s identifier in merchant's system
customer_fname	String	✅	Customer’s first name
customer_lname	String	✅	Customer’s last name
customer_patronym	String		Customer’s patronym
customer_email	String	✅	Customer’s email
customer_phone	String	✅	Customer’s phone
customer_ip	String	✅	Customer’s IP address
customer_country	String		Customer’s country (ISO 3166-1 (alpha-2)). For instance, PL-Poland
customer_city	String		Customer's city
properties.state	String		Customer's state
properties.address	String		Customer's address
properties.post_code	String		Customer's postal code
customer_birthday	String		Customer's birthday (format: yyyy-MM-dd)
customer_referrer	URL		Page customer is redirected from.
customer_tax_id	String		Customer's tax identification number
server_url	URL		Webhook notification will be sent to this URL
result_url	URL		Customer will be redirected to this URL after payment.
merchant_mcc	MCC		MCC for this transaction
payload	String		Field for merchant custom data. Max 4000 symbols.
validation_url	String		Preflight request will be sent to this URL
browser_fingerprint	Json	✅	Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
cryptogram	Json		Cryptogram parameters.

Depending on whether the request uses full card data or a token, pass the following parameters:

• Full card data: cc_number, exp_month, exp_year, card_cvv.
• Tokens: cc_token.

info

In addition to tokens received after a card payment, payments are also supported with tokens received during the first payment through Apple Pay or Google Pay™. These tokens are passed in the cc_token parameter.

For example:

"cc_token":"rcr:ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (token after Apple Pay / Google Pay™ payment)
or
"cc_token":"ODJkZjBhNmY2OTMyND7sSjdD0S8TQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv" (token after card payment).

info

If a payment is made with a card for which 3D Secure authentication has already been completed by an external service, the request must include the three_d_secure parameter containing the authentication result:

Parameter	Type	Required	Description
cavv	String	✅	Cardholder Authentication Verification Value. A cryptographic value derived by the cardholder’s bank after successful 3D Secure authentication.
eci	String	✅	Electronic Commerce Indicator. An indicator of the transaction’s authentication level, passed together with the cryptogram.
ds_transaction_id	String	✅	3DS directory service transaction ID. A unique identifier generated by the payment network's Directory Service to track a specific 3D Secure authentication attempt.
status	String	✅	3D Secure Transaction Status. The final result of the authentication process (for example, Y for successful or A for attempted).
version	String		3D Secure Message Version. The specific version of the 3D Secure protocol used for the authentication (for example, 2.1.0 or 2.2.0).

Request example with card data:

$ curl "https://api.wbsettle.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA1 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "EUR",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_number":        "4242424242424242",
      "exp_month":        2,
      "exp_year":         24,
      "card_cvv":         "111",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "pl-PL",
          "browserTimeZone":         "Europe/Warsaw",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Request example with a token:

$ curl "https://api.wbsettle.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA1 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "direct",
      "method":           "purchase",
      "amount":           1,
      "currency":         "EUR",
      "description":      "Order description",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "cc_token":         "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true",
      "customer_referrer": "https://example.com",
      "browser_fingerprint": {
          "browserColorDepth":       "24",
          "browserScreenHeight":     "860",
          "browserScreenWidth":      "1600",
          "browserJavaEnabled":      "false",
          "browserLanguage":         "pl-PL",
          "browserTimeZone":         "Europe/Warsaw",
          "browserTimeZoneOffset":   "-120",
          "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
          "browserIpAddress":        "127.0.0.1",
          "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
      }
    }'

Response parameters:

Parameter	Type	Description
payment_id	UUID	Unique WhiteBoot payment identifier
order_id	String(≤256)	Unique identifier of order
gateway_order_id	GW_ID	Unique order identifier in bank acquirer system.
billing_order_id	BILLING_ID	Unique WhiteBoot billing identifier
transaction_id	UUID	WhiteBoot transaction identifier
pos_id	UUID	Merchant's identifier (POS_ID)
mode	MODE	direct
method	METHOD	Payment method (auth or purchase)
amount	Number	Transaction amount
currency	CURRENCY	Transaction currency (ISO_4217)
description	String(≤2048)	Payment description
status	STATUS	Transaction status
status_code	STATUS_CODE	WhiteBoot payment status code
status_description	STATUS_DESCRIPTION	WhiteBoot payment status code description
user_action_required	Boolean	Either customer action is required to proceed with payment
user_action_url	URL	If user_action_required is true then user should be redirected to this URL
eci	ECI	Electronic Commerce Indicator - authentication result of credit card payment on 3D Secure
mcc	MCC	MCC for this transaction
options_3ds	String	3-D Secure flow option
cc_mask	CC_MASK	Card number mask
cc_token	CC_TOKEN	WhiteBoot card token generated for this card
cc_token_expiration	String	Token expiration timestamp
customer_id	String	Customer’s identifier in merchant's system
customer_fname	String	Customer’s first name
customer_lname	String	Customer’s last name
customer_patronym	String	Customer’s patronym
customer_email	String	Customer’s email
customer_phone	String	Customer’s phone
customer_country	String	Customer’s country (ISO 3166-1 (alpha-2)). For instance, PL-Poland
customer_birthday	String	Customer’s birthday (format: yyyy-MM-dd)
result_url	URL	Customer will be redirected to this URL after payment.
created_at	TIMESTAMP	Timestamp when transaction was created
processing_time	TIMESTAMP	Timestamp when transaction was updated last time
fee	Object	Amount and currency of commission
fixed_fee	Object	Amount and currency of fixed commission (fee), which constitutes a portion of the total commission (fee)
percent_fee	Object	Amount and currency representing the interest commission (fee), which constitutes a portion of the total commission (fee)
payload	String	Field for custom data
bank_short_name	String	Bank short name.
receipt_url	URL	URL link to the receipt for the corresponding transaction.

Response example:

{
  "payment_id":           "9b1392a5-d030-4e85-b02d-9b7191ea2a5e",
  "order_id":             "123",
  "gateway_order_id":     "9B39A076243EB3EBB0925EAA981763AC:158545961",
  "billing_order_id":     "11231231231",
  "transaction_id":       "a8d80c86-0c7b-41bc-b63d-1e78f80edcd9",
  "pos_id":               "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                 "direct",
  "method":               "purchase",
  "amount":               1000,
  "currency":             "EUR",
  "description":          "Order description",
  "status":               "pending",
  "status_code":          "2122",
  "status_description":   "3DS verification is required to finish the transaction.",
  "user_action_required": true,
  "user_action_url":      "http://secure.secure3d.net/s3st?a=start_3ds&tid=a8d81c860c7b41bcb65d1e78f80edcd923ac18d5dd1d4a37e6c7df7d5e4bec74ab5d790b",
  "eci":                  "7",
  "mcc":                  "4900",
  "options_3ds":          "supported",
  "cc_mask":              "424242******4242",
  "cc_token":             "ODJkZjBhNmY2OTMyNDJlN2wjMjFjfTQzOXU3ZDFhYzI6cWJmWHFmMHlzM3hYaXJMWEZv",
  "cc_token_expiration":  "2020-10-10T10:10:22",
  "customer_id":          "123",
  "customer_ip":          "194.183.171.239",
  "customer_fname":       "Tom",
  "customer_lname":       "Hanks",
  "customer_email":       "tom.hanks@example.com",
  "customer_phone":       "+480999999999",
  "customer_country":     "PL",
  "result_url":           "https://example.com/result",
  "created_at":           "2018-10-10T10:10:22.100",
  "processing_time":      "2018-10-10T10:10:23.300",
  "fee": {
                          "amount": 136,
                          "currency": "EUR"
  },
 "percent_fee": {
                          "amount": 126,
                          "currency": "EUR"
  },
  "fixed_fee": {
                          "amount": 10,
                          "currency": "EUR"
  },
  "payload":              "sale=true",
  "bank_short_name":      "Bank name",
  "receipt_url": "https://api.wbsettle.com/public/receipt/12491284012940129402424124124124124ffef3re3rf32f2vf"
}

Some alternative payment methods support variable payment amounts for cases where the payer may pay only part of the transaction amount. In this case, the response additionally contains the following parameters:

Parameter	Type	Description
processed_amount	Number	The amount that was actually paid by the customer and processed by the payment system. It applies to payments where the final payment amount can be changed by the payer.
processed_currency	String(≤256)	Actual currency of payment with processed_amount. It applies to payments where the final payment amount can be changed by the payer.

Response example with variable amounts:

{
  "operation_id":        "f7d0c7cb-af32-441f-b2af-4d90d4da70e1",
  "payment_id":          "fdf1a710-8a34-414c-b023-b7e78104301a",
  "order_id":            "123",
  "transaction_id":      "4f98dc46-ffff-4ba7-a267-286fe7669894",
  "pos_id":              "dc728de1-51ef-4ef1-80f7-3b44b07b5667",
  "mode":                "direct",
  "method":              "refund",
  "amount":              1000,
  "currency":            "EUR",
  "status":              "success",
  "status_code":         "1004",
  "status_description":  "Refund successful.",
  "created_at":          "2018-10-10T10:10:10.100",
  "processing_time":     "2018-10-10T10:10:12.000",
  "processed_amount":    980,
  "processed_currency":  "EUR",
  "fee":   {
                        "amount": 136,
                        "currency": "EUR"
  },
  "percent_fee": {
                        "amount": 126,
                        "currency": "EUR"
  },
  "fixed_fee": {
                        "amount": 10,
                        "currency": "EUR"
  }
}

The request must also include the following payer browser fingerprint data:

Parameter	Type	Description
browserColorDepth	String	Browser's color depth
browserScreenHeight	String	Browser's screen height
browserScreenWidth	String	Browser's screen width
browserJavaEnabled	String	Browser's java enabled
browserLanguage	String	Browser's language
browserTimeZone	String	Browser's timezone
browserTimeZoneOffset	String	Browser's timezone offset
browserAcceptHeader	String	Browser's accept header
browserIpAddress	String	Browser's IP address
browserUserAgent	String	Browser's user agent

Payer browser fingerprint example:

"browser_fingerprint": {
  "browserColorDepth":       "24",
  "browserScreenHeight":     "860",
  "browserScreenWidth":      "1600",
  "browserJavaEnabled":      "false",
  "browserLanguage":         "pl-PL",
  "browserTimeZone":         "Europe/Warsaw",
  "browserTimeZoneOffset":   "-120",
  "browserAcceptHeader":     "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
  "browserIpAddress":        "127.0.0.1",
  "browserUserAgent":        "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
}

Hosted integration

Hosted integration lets you accept payments from customers using the WhiteBoot payment page.

Interaction flow:

To create a payment through hosted integration, use the POST HTTP method.

Request parameters:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	hosted
method	METHOD	✅	Payment method (auth or purchase)
amount	Number	✅	Transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identified of order
order_3ds_bypass	String	✅	3-D Secure flow option
products	Array[Product]		Array of products to be paid. The structure of the products parameter must meet the following requirements, depending on whether fiscalization is enabled or not: - If fiscalization is not used. - If fiscalization is used.
customer_id	String		Customer’s identifier in merchant's system
customer_fname	String		Customer’s first name. The parameter is mandatory for merchants operating in the iGaming sector
customer_lname	String		Customer’s last name. The parameter is mandatory for merchants operating in the iGaming sector
customer_patronym	String		Customer’s patronym
customer_email	String	✅	Customer’s email
customer_phone	String	✅	Customer’s phone
customer_lang	String		Checkout language. Supported values.
customer_country	String		Customer’s country (ISO 3166-1 (alpha-2)). For instance, PL-Poland
customer_city	String		Customer's city
properties.state	String		Customer's state
properties.address	String		Customer's address
properties.post_code	String		Customer's postal code
customer_birthday	String		Customer's birthday (format: yyyy-MM-dd)
customer_tax_id	String		Customer's tax identification number
server_url	URL		Webhook notification will be sent to this URL
result_url	URL		Customer will be redirected to this URL after payment.
merchant_mcc	MCC		MCC for this transaction
payload	String		Field for custom data. Max 4000 symbols.
validation_url	URL		Preflight request will be sent to this URL
order_timeout	Integer		Payment lifespan. Value in seconds

caution

For merchants operating in the iGaming sector, the customer_fname and customer_lname parameters are required in payment requests.

caution

For microfinance merchants, the customer_fname, customer_lname, and either customer_birthday or customer_tax_id parameters are required in payment requests.

Request example:

$ curl -i "https://api.wbsettle.com/api/v1/payment" \
    -H "Content-Type: application/json" \
    -H "X-API-AUTH: CPAY-HMAC-SHA1 ${API_KEY}:${SIGNATURE}" \
    -H "X-API-KEY: ${ENDPOINTS_KEY}" \
    -X POST -d '{
      "pos_id":           "${POS_ID}",
      "mode":             "hosted",
      "method":           "purchase",
      "amount":           1,
      "currency":         "EUR",
      "description":      "description_1",
      "order_id":         "123",
      "order_3ds_bypass": "always",
      "server_url":       "https://callback.blackhole.com/callback",
      "result_url":       "https://example.com/result",
      "payload":          "sale=true"
    }'

A successful request returns an HTTP 303 response with the location header. Redirect the customer to this URL to continue payment.

Response example:

HTTP/2 303
# .. other headers
location: https://api.wbsettle.com/api/v1/checkout/1b806782-3d97-4444-abb9-6e4b45d34663/form

Next steps

To test the payment process:

• Create an account in the merchant portal.
• Use the test project's authentication data.

• Configure webhooks.
• Use test data to receive different operation result codes.
• Handle received errors.

More details are available in the integration checklist.

Going live:

1. Create a live project in the merchant portal.
2. For direct integration, complete PCI DSS certification.
3. When our Compliance team activates the live project, replace the test project authentication data with the live project data.

See also:

• Recurring payments

• Processing refunds
• Payment widget
• Hosted checkout
• Adding payment methods