Technical Specifications

1. Integration solutions

1.1 Hosted Payment Page?

• In the most basic terms, a hosted payment page (also known as External Checkout, Third-Party Checkout, External Payment Page or Checkout page) is one of the most common ways to accept online payments.

• It is a third-party checkout web form that handles electronic transactions (payments made with credit and debit cards).

• In exchange for a small transaction fee, these Hosted Checkout Pages will take care of the entire transaction process: payment information collection, sensitive data protection, and transaction security.

1.2 Embedded Checkout?

Embedded checkout gives the shopper the seamless appearance of staying on your site while they make payment.

The checkout page is embedded in your website using an HTML <iframe> tag. This tag creates a frame in your web page and then the checkout page is embedded within that frame.

1.3 Get ShopBase Payment Key

https://partners.shopbase.com/payment-gateways

After Create Gateway

Click Test

ShopBase Payment Key

2. FLOW

2.1 Integration Flow

• ShopBase partner will receive ShopBase Payment key after successfully registering Payment integration.

• Partner's payment provider will use ShopBase Payment key for signing mechanism when send/receive requests to/from ShopBase

• To start using the Payment Provider, merchants have to register with Payment Gateway and take Gateway's credentials. Merchants should enter those credentials to ShopBase payment settings.

• Checkout flow:

  • ShopBase sends a request to endpoints of Payment Provider according to ShopBase format and Shopbase signing mechanism.

  • After taking the request, the Payment Provider can ask ShopBase to get Gateway's credentials and then send Gateway's requests to Gateway's format and Gateway's authenticate mechanism.

2.2 Sequence Diagram

2.2.1 Hosted Payment Page

1. First, the buyer needs to fulfill the information: shipping address, billing information, shipping method... and choose your provider as the payment method. When the buyer clicks the Place Order button, ShopBase submits to the Redirect API with the POST method and the x-www-form-urlencoded format.

2. Your provider performs a signature validation to ensure that the request is sent from ShopBase. Your provider displays on the checkout page and lets buyers confirm their payment.

3. Your provider redirects to x_url_complete with GET method and all required parameters. ShopBase will validate the data and create the Order.

4. ShopBase will redirect to the Thank-you page to inform the buyer that the payment is complete.

5. Your provider needs to make a POST request to x_url_callback. It informs ShopBase that the payment has completed with the same response parameters as when it was redirected. It also ensures that the Order will be created even if the buyer goes offline before being redirected to ShopBase.

6. ShopBase records the payment and responses with a 200 HTTP status to the provider.

2.2.2 Embeded Checkout

1. First, the buyer needs to fulfill the information: shipping address, billing information, shipping method... and choose your provider as the payment method. ShopBase will embed your Iframe Url to block Payment method on the checkout page.

2. Your iframe should display the card element (or whatever element), so the buyer can interact with it.

3. When the buyer provides card details and clicks Place Order, ShopBase will post a message into the iframe with request values.

4. Your iframe should request your provider server to confirm payment and obtain gateway authorization reference

5. Your iframe post message to ShopBase with required response values.

6. ShopBase will request to ShopBase server to verify payment status with your provider server, then create an Order.

7. ShopBase server displays the order information to the client with the Thank you page to indicate that the order has been paid successfully.

8. We suggest your provider make a POST request to x_url_callback. It informs ShopBase that the payment has completed with the same response parameters when posting the message on iframe. It also ensures that the Order will be created even if the buyer loses the connection before the ShopBase Server receives the payment information.

2.2.3 Post-Purchase

What is post-purchase?

To help merchants who want to motivate customers after they bought something from the store. ShopBase designed a feature called Post-Purchase. This feature can re-engage customers who just complete a purchase and catch them on the site when they are most likely to buy or to comply with other requests.

How to implement it?

Almost, has the same normal flow, but still has some differences.

After the first purchase is completed, we will send a new authorization with x_reference has the same value with the first authorization and x_post_purchase is true. These have some different ways to process Post-Purchase, it depends on the flow which you choose for implementation.

• For Hosted payment page flow, we will redirect the customer to Gateway payment page, and use Redirect API with the same x_reference and x_post_purchase is true.

• For ​Embedded checkout flow, we will send update-authorization request use Order management API ​with the same x_reference and x_post_purchase is true.

At this step, the gateway needs to capture this second authorization and return a new transaction id. And note that, ShopBase only accepts the update-authorization once within 10 minutes after the first authorization. Authorization cannot be updated twice​.

3. API reference

Link Postman :https://www.postman.com/warped-meteor-302495/workspace/shopbase/collection/16061299-c34173f3-40af-487c-bf80-d3aea05e13d4

3.1 Redirect API + Iframe postMessage

It is used in the checkout flow to redirect to a hosted checkout page or embed an iframe in an embedded checkout page.

Request values

Key	Type	Example
x_account_id Required.	ascii string	10023456	ShopBase payment account ID, for getting Gateway Credentials.
x_amount Required.	decimal	89.99
x_currency Required.	iso-4217	USD
x_reference Required.	ascii string	19783	Unique token for current checkout (checkout token)
x_shop_name Required.	unicode string	Widgets Inc	To display shop name on Hosted checkout page
x_test Required.	true/false	true	Indicates whether or not this request should be processed in test mode (if supported).
x_url_callback Required.	url		URL to which a callback notification should be sent asynchronously.
x_url_cancel Required. Note: Optional with iframe	url		URL to which customer must be redirected when they wish to quit payment flow and return to the merchant's site.
x_url_complete Required. Note: Optional with iframe	url		URL to which customer must be redirected upon successfully completing payment flow.
x_post_purchase	true/false	false	Indicates whether or not this request is for making post purchase.
x_purchase_items	nested	[ { "name": "Shirt", "quantity": 2, "price": 10, "url": "https://q-payment-test.onshopbase.com/products/shirt-1", "image": "https://img.btdmp.com/10243/10243285/products/1636621679424.jpg", "options": [ { "label": "Size", "value": "L" }, { "label": "Color", "value": "Red" } ] } ]	To display purchase items on Hosted checkout page
x_customer_billing_address1	unicode string	241 Spadina Ave
x_customer_billing_address2	unicode string
x_customer_billing_city	unicode string	Toronto
x_customer_billing_company	unicode string	ShopBase
x_customer_billing_country	iso-3166-1 alpha-2	CA
x_customer_billing_phone	unicode string	[phone]
x_customer_billing_state	unicode string	ON
x_customer_billing_zip	unicode string	M5T 3A8
x_customer_email	unicode string	[e-mail]
x_customer_first_name	unicode string	Boris
x_customer_last_name	unicode string	Slobodin
x_customer_phone	unicode string	[phone]
x_customer_shipping_address1	unicode string	241 Spadina Ave
x_customer_shipping_address2	unicode string
x_customer_shipping_city	unicode string	Toronto
x_customer_shipping_company	unicode string	ShopBase
x_customer_shipping_country	iso-3166-1 alpha-2	CA
x_customer_shipping_first_name	unicode string	Boris
x_customer_shipping_last_name	unicode string	Slobodin
x_customer_shipping_phone	unicode string	[phone]
x_customer_shipping_state	unicode string	ON
x_customer_shipping_zip	unicode string	M5T 3A8
x_intent Required. Note: Require if using iframe flow	fixed choice	authorize	Possible values: authorize

Response values

Key	Type	Example	Note
x_account_id Required.	ascii string	10023456	ShopBase payment account ID, for getting Gateway Credentials.
x_amount Required.	decimal	89.99	Echo request's x_amount
x_currency Required.	iso-4217	USD	Echo request's x_currency
x_gateway_reference Required.	unicode string	123	Unique reference for payment issued by the payment processor.
x_reference Required.	ascii string	19783	Echo request's x_reference
x_transaction_type Required.	fixed choice	authorization	The valid values are authorization, capture, refund, void
x_result Required.	fixed choice	completed	Valid values are completed, failed
x_test Required.	true/false	true	Echo request's x_test
x_timestamp Required.	iso-8601 in UTC	2014-03-24T12:15:41Z	Time of transaction completion. UTC Time: YYYY-MM-DDTHH:MM:SSZ
x_message	ascii string	Billing address could not be verified.	A custom error message displayed to the customer.
x_error_code	ascii string	ACCOUNT_RESTRICTED	An error code to be log on ShopBase

Custom iframe message

The following messages can be posted from the iframe to the ShopBase window to modify the iframe container.

Key	Type	Example
x_intent Required.	fixed choice	iframe_update	Update the iframe of the payment block
x_iframe_height	number	100	Resize iframe height to 100px

3.2 Order management API

• These are endpoints used to perform actions such as capture, refund, void order.

• In the Embedded checkout flow, the Payment provider needs to provide more update-authorization endpoint to use in ShopBase's Post-Purchase feature.

Note:

• Only accept the update-authorization once within 10 minutes after the first authorization. An authorization cannot be updated twice.

Request values

Key	Type	Example
x_account_id Required.	ascii string	10023456	ShopBase payment account ID, for getting Gateway Credentials
x_amount	decimal	89.99
x_currency	iso-4217	USD
x_reference Required.	integer	19783	ShopBase order id
x_gateway_reference Required.	ascii string	450789469	Unique reference for payment issued by the payment processor.
x_test Required.	true/false	true	Indicates whether or not this request should be processed in test mode (if supported).
x_url_callback Required.	url		URL to which a callback notification should be sent asynchronously.
x_transaction_type Required.	fixed choice	capture	The valid values are update-authorization, capture, refund, void
x_invoice	unicode string	#123	Only available on request type = capture
x_refund_reason	unicode string	admin refunded $150.00 USD	Only available on request type = refund

Response values

Key	Type	Example	Note
x_gateway_reference Required.	unicode string	123	Unique reference for payment issued by the payment processor.
x_reference Required.	ascii string	19783	Echo request's x_reference
x_transaction_type Required.	fixed choice	capture	The valid values are authorize, capture, void, and refund.
x_result Required.	fixed choice	completed	Valid values are completed or failed
x_timestamp Required.	iso-8601 in UTC	2014-03-24T12:15:41Z	Time of transaction completion. UTC Time: YYYY-MM-DDTHH:MM:SSZ
x_message	ascii string	Billing address could not be verified.	A custom error message displayed to the customer.
x_error_code	ascii string	ACCOUNT_RESTRICTED	An error code to be log on ShopBase

3.3 Get transaction info API

This API is the endpoint to retrieve information on one transaction. Payment Provider needs to provide information in accordance with x_transaction_type (authorization, capture, refund or void) that ShopBase requests.

Request values

Key	Type	Example
x_account_id Required.	ascii string	10023456	ShopBase payment account ID, for getting Gateway Credentials.
x_reference Required.	ascii string	19783	Checkout token or order id depends on x_transaction_type
x_gateway_reference Required.	ascii string	450789469	Unique reference for payment issued by the payment processor.
x_test Required.	true/false	true	Indicates whether or not this request should be processed in test mode (if supported).
x_transaction_type Required.	fixed choice	capture	The valid values are authorization, capture, refund, void
x_result Required.	fixed choice	completed	Valid values are completed, failed

Response values

Same as ​Redirect API Response value

3.4 Check Credentials API

The API is the endpoint to check the legitimacy of one set of gateway credentials (it can be used to make transactions and refund transactions). ShopBase will use this endpoint whenever the merchants activate your payment in the ShopBase dashboard.

Request values

Key	Type	Example
x_gateway_credentials Required.	json		The json object contains Payment Gateway credentials.

Response values

Key	Type	Example
x_result Required.	fixed choice	valid	The valid values are valid, invalid, restricted.

3.5 Get Gateway Credentials

It provides gateway's credentials for your provider.

Endpoint: https://api.shopbase.com/api/checkout/payment-credential.json

Request values

Key	Type	Example
x_account_id Required.	ascii string	10023456	ShopBase payment account ID, for getting Gateway Credentials.

Response values

Key	Type	Example
x_gateway_credentials Required.	json		The json object contains Payment Gateway credentials.
x_message	ascii string	Invalid signature	A custom readale error message.
x_error_code	ascii string	invalid_signature	An error code

3.6 Asynchronous callback

• It makes certain that all orders can be completed, even If your gateway and customer connection is disconnected. You can get the callback URL in x_url_callback param.

• In the Embedded checkout flow, If ShopBase's Post-Purchase feature is active, please note that will require a new transaction for second authorization.

Request values

Key	Type	Example	Note
x_account_id Required.	string	10023456	ShopBase payment account ID, for getting Gateway Credentials.
x_amount Required.	decimal	89.99	Echo request's x_amount
x_currency Required.	iso-4217	USD	Echo request's x_currency
x_gateway_reference Required.	ascii string	123	Unique reference for payment issued by the payment processor.
x_reference Required.	ascii string	19783	Echo request's x_reference
x_transaction_type Required.	fixed choice	authorization	The valid values are authorization, capture, refund, void
x_result Required.	fixed choice	completed	Valid values are completed, failed
x_test Required.	true/false	true	Echo request's x_test
x_timestamp Required.	iso-8601 in UTC	2014-03-24T12:15:41Z	Time of transaction completion. UTC Time: YYYY-MM-DDTHH:MM:SSZ
x_message	ascii string	Billing address could not be verified.	A custom error message displayed to the customer.
x_error_code	ascii string	ACCOUNT_RESTRICTED	An error code to be log on ShopBase

Response

If request success, Shopbase will return HTTP status 200. Otherwise, you should retry later with a delay time.

3.7 Signing mechanism

All requests and responses must be signed/verified using HMAC-SHA256, where:

• key is ShopBase Payment Key. If Provider uses more than 1 ShopBase Payment Key, ShopBase always uses the older one (compared by activated date).

ShopBase Payment Key

• message is a string of all key-value pairs that start with x_ prefix, sorted alphabetically and concatenated without separators.

Note:

• The result codes must be hex-encoded and passed as the value of x_signature. Make sure to use case-insensitive comparison when verifying the provided x_signature values.

Assuming your HMAC key is iU44RWxeik, the signing mechanisms would look like this:

key = 'iU44RWxeik'
fields = {x_account_id: '10023456', x_amount: 89.99, x_currency: 'USD', x_gateway_reference: '123', x_reference: "19783", x_result: "completed", x_test: "true",  x_timestamp: '2014-03-24T12:15:41Z'}
=> {:x_account_id=>"10023456", :x_amount=>89.99, :x_currency=>"USD", :x_gateway_reference=>"123", :x_reference=>"19783", :x_result=>"completed", :x_test=>"true", :x_timestamp=>"2014-03-24T12:15:41Z"}
message = fields.sort.join
=> "x_account_id10023456x_amount89.99x_currencyUSDx_gateway_reference123x_reference19783x_resultcompletedx_testtruex_timestamp2014-03-24T12:15:41Z"
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), key, message)
=> "49d3166063b4d881b50af0b4648c1244bfa9890a53ed6bce6d2386404b610777"

"x_signature=49d3166063b4d881b50af0b4648c1244bfa9890a53ed6bce6d2386404b610777"

Signature will be sent in HTTP header X-Signature of request.

3.8 Error codes

	Error codes	Description
1	card_declined	Card declined by any reasons (anti-fraud, declined by bank..)
2	processing_error	An error occurred while processing the card. Try again later or with a different payment method.
3	call_issuer	The card has been declined for an unknown reason. The customer needs to contact their card issuer for more information.
4	pick_up_card	The customer's card issuer has declined the transaction and requested that the card be retained as the card may have been reported as lost or stolen
5	invalid_signature
6	account_restricted
7	account_invalid
8	payment_not_supported	Does not support this payment for some reason.
9	missing_param	Missing "x" params

3.9 Other notes

• HTTP 200 indicates successful receipt of a callback by ShopBase. Otherwise, up to 5 retries with an interval of at least 60 seconds are recommended.

• In case the merchant performs the capture/refund/void action from the payment provider dashboard, POST a callback asynchronously to ShopBase payment callback URL to notify ShopBase for syncing the order status.

• ShopBase ignores duplicate requests.

• Here are two git examples for reference

  • Dummy: https://github.com/ShopBaseCom/demo-intergrated-gateway

  • Full integrated gateway demo: https://github.com/ShopBaseCom/asiabill-sdk

4. Testing (for ShopBase simulator)

	Transaction amount	Description
1	99.00~99.99	processing_error when capture
2	101.00~101.99	processing_error when refund

	Credit card number	Description
1	4242 4242 4242 4242	Payment success
2	Other	card_declined

	Account ID	Description
1	invalid	Will be invalid when validate credentials
2	restricted	Will be restricted when validate credentials
3	restricted_payment	Will be restricted when authorize payment

5. Technical requirements

Security

• ShopBase always double-validate all request calls between 2 sides: validate request payload + signature, and validate real data (using payment information from the Get Payment Info API​ to compare). All the data should be validated:

  • x_reference should similar to checkout token and order id of ShopBase

  • x_amount of transaction should matches with the amount of ShopBase

  • x_result should be completed

  • x_test, x_account_id should match with ShopBase's request

• ShopBase payment key, Gateway's credentials are private and hidden in all APIs.

• Messages posted via iFrame need to be defined protocol + host + port strictly to ensure no other parties can eavesdrop. When Payment Provider received the messages via iFrame, you also need to check the origin of the requests to ensure they are sent from ShopBase.

Stability

• When handling requests from payment providers, ShopBase will have a process lock to avoid duplicating requests.

• All the requests to payment providers will be logged by ShopBase (i.e. request, response, error rate, error code) to trace back the problems and statistics.

Usability

• Embedded iframe needs to share the same style with ShopBase and support responsive.

• You need to ensure rendering speed, API process speed.