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.
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.
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.
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.
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.
Your provider redirects to x_url_complete
with GET method and all required parameters. ShopBase will validate the data and create the Order.
ShopBase will redirect to the Thank-you page to inform the buyer that the payment is complete.
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.
ShopBase records the payment and responses with a 200 HTTP status to the provider.
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.
Your iframe should display the card element (or whatever element), so the buyer can interact with it.
When the buyer provides card details and clicks Place Order, ShopBase will post a message into the iframe with request values.
Your iframe should request your provider server to confirm payment and obtain gateway authorization reference
Your iframe post message to ShopBase with required response values.
ShopBase will request to ShopBase server to verify payment status with your provider server, then create an Order.
ShopBase server display the order information to the client with the Thank you page to indicate that the order has been paid successfully.
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.
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 | |
| unsigned int | 10023456 | ShopBase payment account ID, for getting Gateway Credentials. |
| decimal | 89.99 | |
| iso-4217 | USD | |
| ascii string | 19783 | Unique token for current checkout (checkout token) |
| unicode string | Widgets Inc | To display shop name on Hosted checkout page |
| true/false | true | Indicates whether or not this request should be processed in test mode (if supported). |
| url | | URL to which a callback notification should be sent asynchronously. |
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. |
Note: Optional with iframe | url | | URL to which customer must be redirected upon successfully completing payment flow. |
| true/false | false | Indicates whether or not this request is for making post purchase. |
| nested | [{"name":"Ipad", "quantity":1, "price":2399.00}] | To display purchase items on Hosted checkout page |
| unicode string | 241 Spadina Ave | |
| unicode string | | |
| unicode string | Toronto | |
| unicode string | ShopBase | |
| CA | | |
| unicode string | +1-613-987-6543 | |
| unicode string | ON | |
| unicode string | M5T 3A8 | |
| unicode string | boris.slobodin@example.com | |
| unicode string | Boris | |
| unicode string | Slobodin | |
| unicode string | +1-613-987-6543 | |
| unicode string | 241 Spadina Ave | |
| unicode string | | |
| unicode string | Toronto | |
| unicode string | ShopBase | |
| CA | | |
| unicode string | Boris | |
| unicode string | Slobodin | |
| unicode string | +1-416-123-4567 | |
| unicode string | ON | |
| unicode string | M5T 3A8 | |
Note: Require if using iframe flow | fixed choice | authorize | Possible values: |
Response values
Key | Type | Example | Note |
| unsigned int | 10023456 | Echo request's |
| decimal | 89.99 | Echo request's |
| iso-4217 | USD | Echo request's |
| unicode string | 123 | Unique reference for payment issued by the payment processor. |
| ascii string | 19783 | Echo request's |
| fixed choice | authorization | The valid values are |
| fixed choice | completed | Valid values are |
| true/false | true | Echo request's |
| iso-8601 in UTC | 2014-03-24T12:15:41Z | Time of transaction completion. UTC Time: YYYY-MM-DDTHH:MM:SSZ |
| ascii string | Billing address could not be verified. | A custom error message displayed to the customer. |
| 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 | |
| fixed choice | iframe_update | Update the iframe of payment block |
| number | 100 | Resize iframe height to 100px |
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 | |
| unsigned int | 10023456 | ShopBase payment account ID, for getting Gateway Credentials |
| decimal | 89.99 | |
| iso-4217 | USD | |
| integer | 19783 | ShopBase order id |
| ascii string | 450789469 | Unique reference for payment issued by the payment processor. |
| true/false | true | Indicates whether or not this request should be processed in test mode (if supported). |
| url | | URL to which a callback notification should be sent asynchronously. |
| fixed choice | capture | The valid values are |
| unicode string | #123 | Only available on request type = |
Response values
Key | Type | Example | Note |
| unicode string | 123 | Unique reference for payment issued by the payment processor. |
| ascii string | 19783 | Echo request's |
| fixed choice | capture | The valid values are |
| fixed choice | completed | Valid values are |
| iso-8601 in UTC | 2014-03-24T12:15:41Z | Time of transaction completion. UTC Time: YYYY-MM-DDTHH:MM:SSZ |
| ascii string | Billing address could not be verified. | A custom error message displayed to the customer. |
| ascii string | ACCOUNT_RESTRICTED | An error code to be log on ShopBase |
This API is the endpoint to retrieve information of 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 | |
| unsigned int | 10023456 | ShopBase payment account ID, for getting Gateway Credentials. |
| ascii string | 19783 | Checkout token or order id depends on |
| ascii string | 450789469 | Unique reference for payment issued by the payment processor. |
| true/false | true | Indicates whether or not this request should be processed in test mode (if supported). |
| fixed choice | capture | The valid values are |
| fixed choice | completed | Valid values are |
Response values
Same as Redirect API Response value
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 | |
| json | | The json object contains Payment Gateway credentials. |
Response values
Key | Type | Example | |
| fixed choice | valid | The valid values are valid, invalid, restricted. |
It provides gateway's credentials for your provider.
Request values
Key | Type | Example | |
| unsigned int | 10023456 | ShopBase payment account ID, for getting Gateway Credentials. |
Response values
Key | Type | Example | |
| json | | The json object contains Payment Gateway credentials. |
| ascii string | Invalid signature | A custom readale error message. |
| ascii string | invalid_signature | An error code |
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).
message
is a string of all key-value pairs that start with x_
prefix, sorted alphabetically, and concatenated without separators.
Note:
Resulting codes must be hex-encoded and passed as 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.
| 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 |
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.
| 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 |
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.
When handling requests from payment providers, ShopBase will have 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.
Embedded iframe needs to share the same style with ShopBase and support responsive.
You need to ensure rendering speed, API process speed.