Spreedly Gateway
See example of integrating Spreedly Gateway.
A single Spreedly gateway provides many methods, like: credit_card, credit_card with 3DSecure, sprel (for offsite payment). Therefore, you can use one Spreedly gateway for all the payment types. To learn about the details, see Spreedly Gateway documentation.
Gateway configuration
To start with the configuration, make sure you have the Spreedly environment credentials prepared.
To create a gateway on Spreedly side, execute the following request:
curl --location --request POST 'https://core.spreedly.com/v1/gateways.xml' \
--header 'Content-Type: application/xml' \
--header 'Authorization: Basic {SPREEDLY_TOKEN}' \
--data-raw '<gateway>
<gateway_type>test</gateway_type>
</gateway>'
The SPREEDLY_TOKEN is a result of base64 of environment_key:access_secret.
Result: after sending the request you should get a response that contains the token value.
<gateway>
<token>5S0kV27BrZ0Z48TdGK7v10Y7ojB</token>
...
</gateway>Store the token value for the next steps in the configuration. If you lose the token value at any point, use the following request to get it:
curl --location --request GET 'https://core.spreedly.com/v1/gateways.json' \
--header 'Authorization: Basic {SPREEDLY_TOKEN}'Credit card configuration
To configure a new payment mode in the payment gateway service, execute the following request:
curl --location --request POST 'https://api.emporix.io/payment-gateway/my-tenant/paymentmodes/config' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {EMPORIX_AUTH_TOKEN}' \
--data-raw '{
"code": "credit_card",
"active": true,
"provider": "SPREEDLY",
"configuration": {
"Spreedly/GatewayToken": "{SPREEDLY_GATEWAY_TOKEN}",
"Spreedly/EnvironmentKey": "{SPREEDLY_ENVIRONMENT_KEY}",
"Spreedly/AccessSecret": "{SPREEDLY_ACCESS_SECRET}",
"Spreedly/PaymentMethodType": "credit_card"
}
}'SPREEDLY_GATEWAY_KEY - Spreedly gateway token that was returned when you configured the payment gateway on the Spreedly side.
SPREEDLY_ENVIRONMENT_KEY - Spreedly environment key that you got from Emporix support team.
SPREEDLY_ACCESS_SECRET - Spreedly secret key that you got from Emporix support team.
Credit card configuration with 3DS
Prerequisite
To start with the 3DS configuration, you need to create a Merchant Profile and an SCA Provider.
Obtain the Merchant Profile token by executing the following request:
curl --location --request POST 'https://core.spreedly.com/v1/merchant_profiles.json' \
--header 'Authorization: Basic {SPREEDLY_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchant_profile": {
"description": "Spreedly",
"visa": {
"acquirer_merchant_id": "spreedlys_mid",
"merchant_name": "Spreedly",
"country_code": "276",
"mcc": "5978"
},
"mastercard": {
"acquirer_merchant_id": "spreedlys_mid",
"merchant_name": "Spreedly",
"country_code": "276",
"mcc": "5978"
}
}
}'Response: you should get a json with the merchant_profile.token value. Make sure to save the value as it's needed in the next configuration steps.
Obtain the SCA provider token by executing the following request:
curl --location --request POST 'https://core.spreedly.com/v1/sca/providers.json' \
--header 'Authorization: Basic {SPREEDLY_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"sca_provider": {
"merchant_profile_key": "{MERCHANT_PROFILE_TOKEN}",
"type": "test",
"sandbox": true,
"mastercard": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional"
},
"visa": {
"acquirer_bin": "4444444444",
"merchant_url": "https://spreedly.com",
"merchant_password": "optional",
"merchant_brand_id": "optional"
}
}
}'Response: you should get a json with the sca_provider.token value. Make sure to save the value as it's needed in the next configuration steps.
Configuration
To configure a new payment method with the 3DS in the payment gateway service, execute the following request:
curl --location --request POST 'https://api.emporix.io/payment-gateway/my-tenant/paymentmodes/config' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {EMPORIX_AUTH_TOKEN}' \
--data-raw '{
"code": "credit_card_3ds",
"active": true,
"provider": "SPREEDLY",
"configuration": {
"Spreedly/GatewayToken": "{SPREEDLY_GATEWAY_TOKEN}",
"Spreedly/EnvironmentKey": "{SPREEDLY_ENVIRONMENT_KEY}",
"Spreedly/AccessSecret": "{SPREEDLY_ACCESS_SECRET}",
"Spreedly/SignatureSecret": "{SPREEDLY_SIGNATURE_SECRET}",
"Spreedly/PaymentMethodType": "credit_card",
"Spreedly/SCAProviderToken": "{SPREEDLY_SCA_PROVIDER}",
"Spreedly/TestScenario" : "{TEST_SCENARIO}"
}
}'SPREEDLY_GATEWAY_KEY - Spreedly gateway token that was returned when you configured the payment gateway on the Spreedly side.
SPREEDLY_ENVIRONMENT_KEY - Spreedly environment key that you got from Emporix support team.
SPREEDLY_ACCESS_SECRET - Spreedly secret key that you got from Emporix support team.
SPREEDLY_SIGNATURE_SECRET - Spreedly signature secret that you got from Emporix support team.
SPREEDLY_SCA_PROVIDER - The
sca_provider.tokenyou got in the previous request.TEST_SCENARIO - This value should be provided only for testing purposes (it shouldn’t be provided for production configuration). Valid options are:
authenticated,not_authenticatedandchallenge. We recommend testing the flow especially with thechallengemode, where an additional offsite step is required when an order is being created.
Spreedly Sprel
Spreedly Sprel is an off-site payment, which means that the payment is finished outside of your storefront. In this situation, the payment provider needs to know where the end user should be redirected when the payment is done. Therefore, you need to provide a {REDIRECT_URL} value in the configuration, for example: https://storefront.emporix.io/my-tenant/payment-callback.
To create this payment method, execute the following request:
curl --location --request POST 'https://api.emporix.io/payment-gateway/my-tenant/paymentmodes/config' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {EMPORIX_AUTH_TOKEN}' \
--data-raw '{
"code": "sprel",
"active": true,
"provider": "SPREEDLY",
"configuration": {
"Spreedly/GatewayToken": "{SPREEDLY_GATEWAY_TOKEN}",
"Spreedly/EnvironmentKey": "{SPREEDLY_ENVIRONMENT_KEY}",
"Spreedly/AccessSecret": "{SPREEDLY_ACCESS_SECRET}",
"Spreedly/SignatureSecret": "{SPREEDLY_SIGNATURE_SECRET}",
"Spreedly/PaymentMethodType": "sprel",
"Spreedly/RedirectURL": "{REDIRECT_URL}"
}
}'SPREEDLY_GATEWAY_KEY - Spreedly gateway token that was returned when you configured the payment gateway on the Spreedly side.
SPREEDLY_ENVIRONMENT_KEY - Spreedly environment key that you got from Emporix support team.
SPREEDLY_ACCESS_SECRET - Spreedly secret key that you got from Emporix support team.
SPREEDLY_SIGNATURE_SECRET - Spreedly signature secret that you got from Emporix support team.
REDIRECT_URL - The URL of your storefront, where the user should be redirected after the payment is completed.
Storefront implementation
This is an example of how you can configure your storefront payment support for the Payment Gateway service.
Credit cards
Add a button that opens Spreedly Express modal.
<button className='large-primary-btn' onClick={openModal}>Enter Payment Info</button>There's a 'onClick' handler configure, the handler should open the Spreedly modal:
const openModal = (event) => {
window['SpreedlyExpress'].openView()
}Configure an
initfunction, it should be invoked when a page/component is rendered.
window['SpreedlyExpress'].init(paymentMode.environmentKey, {
"amount": cart.subtotalAggregate.grossValue + ' ' + cart.subtotalAggregate.currency,
"company_name": "PowerZone",
"sidebar_bottom_description": "Total Price",
}, {
"customerId": cart.customerId
});Configure Spreedly listener.
window['SpreedlyExpress'].onPaymentMethod(function(token, paymentMethod) {
// store token, because it should be send in the checkout request
window['SpreedlyExpress'].unload()
});Adjust the checkout request, by adding the following payment information to the payload:
{
...
"paymentMethods" : [
{
"provider": "payment-gateway",
"customAttributes": {
"token": "HXCA1VgWm2EYDdhZ8gFgUxUhwlI",
"modeId": "f44f71a4-b632-4c9e-a9fc-27b97551d1d7",
"customer": "17071158"
}
}
]
...
}The provider should always be
payment-gatewayif you’re using payment-gateway service.The token is the token returned by Spreedly express.
The
modeIdis the payment-mode identifier - the id returned by Payment Gateway service.The customer is the customer identifier.
Response:
{
"orderId": "EON1005",
"paymentDetails": {
"externalPaymentHttpMethod": null,
"authorizationToken": "aPF9mGbmqApxWmCBeMHduxccL9G",
"externalPaymentRedirectURL": null
},
"checkoutId": null
}The thing that may be needed for you is paymentDetails section. In case of on-site payment no further action is required.
Credit cards with 3DS
Adjust Spreedly listener.
window['SpreedlyExpress'].onPaymentMethod(function(token, paymentMethod) {
let browserInfo = window['Spreedly'].ThreeDS.serialize('4')
// store the browserInfo, because it should be send in the checkout
// store token, because it should be send in the checkout request
window['SpreedlyExpress'].unload()
});Adjust the checkout request by adding the following payment information to the payload:
{
...
[
{
"provider": "payment-gateway",
"method" : "credit_card",
"customAttributes": {
"token": "YqLX1WVg7lUpTaJWFOVkL6XxNJq",
"modeId": "3005fcfc-8e5e-4253-8309-39e6045970e0",
"customer": "17071158",
"browserInfo": "eyJ3aWR0aCI6Mzg0MCwiaGVpZ2h0IjoyMTYwLCJkZXB0aCI6MjQsInRpbWV6b25lIjotMTIwLCJ1c2VyX2FnZW50IjoiTW96aWxsYS81LjAgKE1hY2ludG9zaDsgSW50ZWwgTWFjIE9TIFggMTBfMTVfNykgQXBwbGVXZWJLaXQvNTM3LjM2IChLSFRNTCwgbGlrZSBHZWNrbykgQ2hyb21lLzExNC4wLjAuMCBTYWZhcmkvNTM3LjM2IiwiamF2YSI6ZmFsc2UsImxhbmd1YWdlIjoiZW4tR0IiLCJicm93c2VyX3NpemUiOiI0IiwiYWNjZXB0X2hlYWRlciI6InRleHQvaHRtbCxhcHBsaWNhdGlvbi94aHRtbCt4bWwsYXBwbGljYXRpb24veG1sIn0="
}
}
]
...
}The provider should always be
payment-gatewayif you’re using payment-gateway service.The token is the token returned by Spreedly express.
The customer is the customer identifier.
The
browserInfois the one that was generated in theonPaymentmethodlistener.
When the checkout is done and the order is completed, it should be checked if the 3DS challenge is needed. You can check that by adding the
htmlcode and JS part.
Html code:
<div id="device-fingerprint" className="hidden"></div>
<div id="challenge-modal" className="hidden fitToModal">
<div id="challenge" className=''></div>
</div>JS part:
const [challenge, setChallenge] = useState(true)
useEffect(() => {
if(payment?.paymentMode?.scaProviderToken) {
var lifecycle = new window['Spreedly'].ThreeDS.Lifecycle({
environmentKey: {SPREEDLY_ENVIRONMENT_KEY},
hiddenIframeLocation: 'device-fingerprint',
challengeIframeLocation: 'challenge',
transactionToken: {AUTHORIZATION_TOKEN},
challengeIframeClasses: '3dsModal'
})
var on3DSstatusUpdatesFn = function(threeDsStatusEvent) {
if (threeDsStatusEvent.action === 'succeeded') {
setChallenge(false)
} else if (threeDsStatusEvent.action === 'error') {
// present an error to the user to retry
} else if (threeDsStatusEvent.action === 'finalization-timeout') {
// present an error to the user to retry
} else if (threeDsStatusEvent.action === 'challenge') {
setChallenge(true)
document.getElementById('challenge-modal').classList.remove('hidden');
}
}
window['Spreedly'].on('3ds:status', on3DSstatusUpdatesFn)
lifecycle.start()
} else {
setChallenge(false)
}
}, [])If a challenge is needed, then an appropriate modal is displayed. Emporix system is notified about the result of the operation by an appropriate callback that is sent directly to the payment-gateway service by Spreedly.
Spreedly Sprel
To use Spreedly Sprel as the off-site payment solution, you have to generate a token in Spreedly. You can do this in two ways:
Display a button that does the form submission - as described in PayPal Commerce Platform Offsite Payments.
Execute the following (an example in react):
const generateToken = () => {
var formData = new FormData();
formData.append("redirect_url", window.location.href)
formData.append("environment_key", {SPREEDLY_ENVIRONMENT_KEY})
formData.append("payment_method_type", "sprel")
axios({
method: "post",
url: "https://core.spreedly.com/v1/payment_methods.json",
data: formData,
headers: { "Content-Type": "multipart/form-data" },
})
.then(function (response) {
storeToken(response)
})
.catch(function (response) {
storeToken(response)
});
}
const storeToken = (response) => {
const url = new URL(response.request.responseURL)
const token = url.searchParams.get("token")
setPayment({
provider: 'payment-gateway',
mode: "offsite",
method: 'sprel',
customAttributes: {
token : token,
modeId : paymentMode.id,
customer : cart.customerId
}
})
}All the payment information is stored, because we need this value during the checkout call. The payment object during the checkout request should look like:
{
...
"paymentMethods": [
{
"provider": "payment-gateway",
"mode": "offsite",
"method": "sprel",
"customAttributes": {
"token": "8Ny2OGn1dwzPBuBdwSej95qAuHN",
"modeId": "227fed5b-e91a-473e-88ea-3b0e85db8408",
"customer": "17071158"
}
}
]
...
}Response:
{
"orderId": "EON1011",
"paymentDetails": {
"externalPaymentHttpMethod": "GET",
"authorizationToken": "nzQPTC2skR6Fb3LgOagBmVGCBC",
"externalPaymentRedirectURL": "https://core.spreedly.com/sprel/5S0kV27BrZ0Z47TdGK4v1OI7ojB/checkout/nzQPTC2skR6Fb3LgOagBmVGCBC"
},
"checkoutId": null
}Pay attention to the paymentDetails.externalPaymentRedirectURL value. To finish the payment, you should redirect the user to the URL. Emporix payment gateway is notified about the result of the payment process by Spreedly callback functionality.
Last updated
Was this helpful?