Payment Systems

Integrate a payment provider system to your e-commerce system.

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 start with the Payment Gateway solution, you need to have a Spreedly environment. To get the environment, contact the Emporix support team. After the team creates the environment, you should get 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, inter alia, Spreedly gateway and Paypal Commerce.

To learn more about gateways supported by Spreedly, see the Spreedly Gateways documentation.

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 https://api.emporix.io/checkout/{TENANT}/checkouts/orders POST request, with the paymentMethod field including the following information:

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: https://api.emporix.io/payment-gateway/{TENANT}/paymentmodes/frontend.

• 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: https://api.emporix.io/payment-gateway/{TENANT}/paymentmodes/frontend.

  • 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.

With this flow, the payment authorization is done during the checkout process. The response to the checkout request contains the paymentDetails object:

{
    "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 https://api.emporix.io/checkout/{TENANT}/checkouts/orders POST request, with the paymentMethod field including the following information:

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.

{
  "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 https://api.emporix.io/payment-gateway/{TENANT}/payment/frontend/authorize payment-gateway endpoint:

{
  "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: https://api.emporix.io/payment-gateway/{TENANT}/paymentmodes/frontend

• creditCardToken - A mandatory field when a tokenized payment method is used.

Response from the endpoint:

{
    "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 documentation. For examples of configuration possibilities with Emporix, see:

• Spreedly Gateway
• 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:

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:

[
    {
        "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 documentation.

For examples of configuration possibilities with Emporix, see:

• Spreedly Gateway
• 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:

curl 'https://api.emporix.io/payment-gateway/my-tenant/paymentmodes/frontend' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer {CUSTOMER_TOKEN}' \

Response:

[ {
"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:

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:

{
...
  "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.