# Payment Systems ## Introduction The Payment Gateway service is a B2B and B2C functionality that you can use for multiple payment methods configuration. Having the integration with Spreedly, Emporix offers a lot of flexibility and possibilities to use a variety of payment providers. Depending on the needs, payments can be configured as on-site and off-site possibilities with no data kept on the Emporix side. ## Features | Features | Benefits | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Configuration of payment strategies** | Simplified integration with payment providers and easy configuration of the solutions using Spreedly as the orchestrator. | | **Payment configuration per site** | You can configure the relevant payment method on site level within the Management Dashboard. | | **Transaction log** | Have a transparent overview within the Management Dashboard about the transaction history for every order. | | **Refund creation** | The merchant customer service can trigger refunds from the Management Dashboard without logging in to several payment provider backoffices. | | **Payment cancellation** | Cancel the payment within the Management Dashboard. | | **Capture** | Provides the flexibility to adapt the capture trigger based on your business, for example: digital products you might want to capture instantly. In other cases, you might need to reserve an amount and capture the final amount later. | ## Prerequisites To enable a payment gateway solution on the storefront, you need to have a Spreedly environment (except for Unzer integration). To get the Spreedly environment, contact the [Emporix support team](mailto:support@emporix.com). After the team creates the environment, you receive the following details: * **Environment key** - public value, you can use it on frontend side * **Access secret** - secret value, you should never reveal it and keep it secure * **Signing secret** - secret value, you should never reveal it and keep it secure Using Spreedly, it's possible to configure a variety of payment gateways, in this section you can check who to work with sample gateways, among others Spreedly gateway or Paypal Commerce. {% hint style="info" %} To learn more about gateways supported by Spreedly, see the [Spreedly Gateways](https://developer.emporix.io/ce/extensibility-and-integrations/payments/spreedly-test-gateway) documentation. {% endhint %} ## Payment approaches With the payment solution, you can use two different approaches: * In-checkout - when the payment is done before an order is placed * Post-checkout - when the payment is done after the order is placed ### In-checkout Payment done during the checkout requires an POST request, with the `paymentMethod` field including the following information: ```json paymentMethods : [ { "provider": "payment-gateway", "method": "card", "customAttributes": { "token": "Akon8nPXtz0oahVYEqPsoI7pz4l", "modeId": "92d77b2b-9385-43ad-a859-55176fbcbd2f", "customer": "61443563", "browserInfo": null } } ] ``` * `provider` - Should always be set to payment-gateway. * `method` - Reflects one of the payment mode codes, depending on the method that you want to choose. You can see the list of available modes after sending the GET request: . * `customAttributes` - It's a set of attributes specific for the particular payment mode * `token` - Credit card token for a tokenized approach. * `modeId` - Payment mode identifier, the ID should reflect the payment mode ID that you receive from GET: . * `customer` - Identifier of a customer that does the checkout and payment. * `browserInfo` - It’s required for 3DS2 approach only. For details check [Spreedly payment gateway](https://developer.emporix.io/ce/extensibility-and-integrations/payments/spreedly-test-gateway). With this flow, the payment authorization is done during the checkout process. The response to the checkout request contains the `paymentDetails` object: ```json { "orderId": "EON1772", "paymentDetails": { "externalPaymentHttpMethod": "GET", "authorizationToken": "AVTqLLj26KFCVQtfOXrAkymfpR9", "externalPaymentRedirectURL": "https://www.paypal.com/checkoutnow?token=2KY55219L2352861G" }, "checkoutId": null } ``` The `externalPaymentRedirectURL` field is populated only in case when a redirect is required. The URL is used to navigate the user in order to finish the payment process. The diagram shows how the in-checkout flow looks like when it's integrated with Emporix:
### Post-checkout Payment done after the checkout requires an POST request, with the `paymentMethod` field including the following information: ```json paymentMethods : [ { "provider": "payment-gateway", "customAttributes": { "customer": "61443563", "deferred": true } } ] ``` * `provider` - Should always be set to payment-gateway. * `customAttributes` - It's a set of attributes specific for the particular payment mode: * `customer` - ID of the customer who does the checkout and payment * `deferred` - should be set to `true` as it indicates the payment is done after the order is placed For this flow, the payment authorisation is NOT done automatically during the checkout process. Therefore, as a response to the checkout request, you can receive the following response without the `paymentDetails` information. ```json { "orderId":"EON1775", "paymentDetails":null, "checkoutId":null } ``` When the order is placed, the storefront should display payment options and allow the users to choose the appropriate one. Having the payment option chosen and all payment details provided, storefront should invoke the payment-gateway endpoint: ```json { "order": { "id":"EON1775" }, "paymentModeId":"ef48f439-1c3c-42ff-807d-ef4cac237745", "creditCardToken":"9QpMHzNNZDCHVF47hL9ZDP18RFr" } ``` * `Order id` - A mandatory field, the ID has to be an order ID created by a customer that invokes the authorization endpoint. Otherwise a validation error is returned. * `paymentModeId` - A payment mode identifier, it should reflect the payment mode ID that you received from GET: * `creditCardToken` - A mandatory field when a tokenized payment method is used. Response from the endpoint: ```json { "successful": true, "paymentTransactionId": "afddff82-de4e-45b8-8de5-3f722b81116b", "authorizationToken": "2IKNTd5K2HlYqjmGt8n7JgICWuG", "requiresExternalPayment": true, "externalPaymentRedirectURL": "https://www.paypal.com/checkoutnow?token=49C50265AF458692S", "externalPaymentHttpMethod": "GET" } ``` The `externalPaymentRedirectURL` field is populated only in case when a redirect is required. The URL is used to navigate the user in order to finish the payment process. The diagram shows how the post-checkout flow looks like when it's integrated with Emporix:
## Gateways configuration Spreedly allows for configuration of multiple payment gateways. For the full list, see the [Supported Gateways](https://docs.spreedly.com/reference/supported-gateways/) documentation.\ For examples of configuration possibilities with Emporix, see: * [Spreedly Gateway](https://developer.emporix.io/ce/extensibility-and-integrations/payments/spreedly-test-gateway) * [Saferpay](https://developer.emporix.io/ce/extensibility-and-integrations/payments/saferpay) ## Storefront implementation This is an example of how you can configure your storefront payment support for the Payment Gateway service. 1. Execute the following request: ```js curl --location --request GET 'https://api.emporix.io/payment-gateway/my-tenant/paymentmodes/frontend' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {CUSTOMER_TOKEN}' ``` * CUSTOMER\_TOKEN - The customer token generated on a storefront. Response: ```json [ { "id": "f44f71a4-b632-4c9e-a9fc-27b97551d1d7", "code": "credit_card", "integrationType": "TOKENIZED", "javascriptUrl": "https://core.spreedly.com/iframe/iframe-v1.min.js", "paymentMethodType": "credit_card", "environmentKey": "NfNg5nQUbBhunpVotluOxQRzOdN" }, { "id": "3005fcfc-8e5e-4253-8309-39e6045970e0", "code": "credit_card_3ds", "integrationType": "TOKENIZED", "javascriptUrl": "https://core.spreedly.com/iframe/iframe-v1.min.js", "paymentMethodType": "credit_card", "environmentKey": "NfNg5nQUbBhunpVotluOxQRzOdN", "scaProviderToken": "a1mCvrg0KDAKtopnvubApHpPRE6" }, { "id": "227fed5b-e91a-473e-88ea-3b0e85db8408", "code": "sprel", "integrationType": "OFFSITE", "paymentMethodType": "sprel", "environmentKey": "NfNg5nQUbBhunpVotluOxQRzOdN" } ] ``` For the configured payment gateways, you can implement the relevant support for them. For details, see the [Spreedly Express](https://docs.spreedly.com/guides/adding-payment-methods/express/) documentation. For examples of configuration possibilities with Emporix, see: * [Spreedly Gateway](https://developer.emporix.io/ce/extensibility-and-integrations/payments/spreedly-test-gateway) * [Saferpay](https://developer.emporix.io/ce/extensibility-and-integrations/payments/saferpay) ### Site specific payment methods You can configure available payment methods separately for every site. 1. Go to Emporix Management Dashboard -> **Settings** -> **Site Settings**.
2. Invoke two endpoints on your storefront to display the payment methods. * Get a list of the payment methods configured for your tenant: ```js curl 'https://api.emporix.io/payment-gateway/my-tenant/paymentmodes/frontend' \ -H 'Accept: application/json, text/plain, */*' \ -H 'Authorization: Bearer {CUSTOMER_TOKEN}' \ ``` Response: ```json [ { "id" : "92d77b2b-9385-43ad-a859-41176fbcbd2f", "code" : "credit_card", "integrationType" : "TOKENIZED", "javascriptUrl" : "https://core.spreedly.com/iframe/iframe-v1.min.js", "paymentMethodType" : "credit_card", "environmentKey" : "Rrg7UfAqQefDY1KGvU4b8OKnhz" }, { "id" : "a8c96773-1cdf-4ea7-b1a2-1453d17f5374", "code" : "sprel", "integrationType" : "OFFSITE", "paymentMethodType" : "sprel", "environmentKey" : "Rrg7UfAqQefDY1KGvU4b8OKnhz" }, { "id" : "9a33c7a5-9535-42af-a936-2fa6ece27579", "code" : "cash_on_delivery", "integrationType" : "EXTERNAL" }, { "id" : "46a76ccc-4a20-471e-9219-e92bba8067e9", "code" : "invoice", "integrationType" : "EXTERNAL" }, { "id" : "ef48f439-1c3c-42ff-807d-ef4cac237745", "code" : "paypal", "integrationType" : "OFFSITE", "paymentMethodType" : "paypal", "environmentKey" : "Rrg7UfAqQefDY1KGvU4b8OKnhz" }, { "id" : "82d77b2b-9385-43ad-a859-55176fbcbd5f", "code" : "credit_card_3ds", "integrationType" : "TOKENIZED", "javascriptUrl" : "https://core.spreedly.com/iframe/iframe-v1.min.js", "paymentMethodType" : "credit_card", "environmentKey" : "Rrg7UfAqQefDY1KGvU4b8OKnhz", "scaProviderToken" : "EyMV4wnFe7xLASdg1DAVA4w7K0W" } ] ``` * Get the site settings: ```js curl 'https://api.emporix.io/site/my-tenant/sites/DE' \ -H 'Accept: application/json, text/plain, */*' \ -H 'Accept-Language: de' \ -H 'Authorization: Bearer {CUSTOMER_TOKEN}' \ ``` Response: ```json { ... "code": "DE", "payment": [ { "id": "92d77b2b-9385-43ad-a859-55176fbcbd2f", "name": "credit_card", "serviceType": "SPREEDLY", "serviceUrl": "", "active": true }, { "id": "a8c96773-1cdf-4ea7-b1a2-1453d17f5374", "name": "sprel", "serviceType": "SPREEDLY", "serviceUrl": "", "active": true }, { "id": "ef48f439-1c3c-42ff-807d-ef4cac237745", "name": "paypal", "serviceType": "SPREEDLY", "serviceUrl": "", "active": true }, ], ... } ``` With the two lists, you can configure the payment methods for a given site.