PayPal

See example of integrating Paypal.

Introduction

The integration with PayPal supports both in-checkout and post-checkout payment approaches. To learn about the details, see the PayPal Commerce Platform Gateway Guide documentation.

In-checkout flow

Payment done during the checkout requires an https://api.emporix.io/checkout/{TENANT}/checkouts/orders POST request, with the paymentMethods field including the following information:

paymentMethods : [
  {
    "provider": "payment-gateway",
    "method": "paypal",
    "customAttributes": {
      "token": "Akon8nPXtz0oahVYEqPsoI7pz4l",
      "modeId": "92d77b2b-9385-43ad-a859-55176fbcbd2f",
      "customer": "61443563"
    }
  }
] 

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

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.

When the user finishes the whole flow on the PayPal side, the Emporix payment gateway is notified about the result of the operation by a callback. It may take around one minute as this is an asynchronous operation.

The diagram shows how PayPal sequence looks like when it's integrated with Emporix for the in-checkout flow:

Post-checkout flow

The post-checkout approach assumes that a customer does a checkout without pointing to any payment methods. This stage happens after the checkout, when an actual order is already created.

Payment done after the checkout requires an https://api.emporix.io/checkout/{TENANT}/checkouts/orders POST request, with the paymentMethods 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 - Identifier of the customer that does the checkout and payment.

  • deferred - Should be set to true.

For this flow the payment authorization is NOT done automatically during the checkout process. Therefore, as a response of the checkout request you can receive the following response with missing paymentDetails fields:

{
  "orderId":"EON1775",
  "paymentDetails":null,
  "checkoutId":null
}

When an order is placed, the storefront should display all the available payment options and allow the user to choose the relevant one, in this case PayPal. Having the payment option chosen and all payment details provided, storefront should invoke the following payment-gateway endpoint: https://api.emporix.io/payment-gateway/{TENANT}/payment/frontend/authorize POST:

{
  "order": {
      "id":"EON1775"
  },
  "paymentModeId":"ef48f439-1c3c-42ff-807d-ef4cac237745",
  "creditCardToken":"9QpMHzNNZDCHVF47hL9ZDP18RFr"
}

• Order id - A mandatory field, it needs to be an order created by a customer that invokes the authorization endpoint. Otherwise, a validation error is returned.

• paymentModeId - payment mode identifier - Reflect the payment mode ID that you received from GET: https://api.emporix.io/payment-gateway/{TENANT}/paymentmodes/frontend.

• creditCardToken - The field should contain the token received by the Spreedly library.

Response:

{
    "successful": true,
    "paymentTransactionId": "afddff82-de4e-45b8-8de5-3f722b81116b",
    "authorizationToken": "2IKNTd5K2HlYqjmGt8n7JgICWuG",
    "requiresExternalPayment": true,
    "externalPaymentRedirectURL": "https://www.paypal.com/checkoutnow?token=49C50265AF458692S",
    "externalPaymentHttpMethod": "GET"
}

Pay attention to the paymentDetails.externalPaymentRedirectURL value. To finish the payment, you should redirect the user to the relevant URL, payment flow on the PayPal website.

When the user finishes the whole flow on the PayPal side, the Emporix payment gateway is notified about the result of the operation by a callback. It may take around one minute as this is an asynchronous operation.

The diagram shows how PayPal sequence looks like when it's integrated with Emporix for the post-checkout flow:

Gateway configuration

1. To start with the gateway configuration, execute the following request:

curl https://core.spreedly.com/v1/gateways.xml \
--header 'Authorization: Basic {SPREEDLY_TOKEN}' \
-H 'Content-Type: application/xml' \
-d '<gateway>
  <gateway_type>paypal_commerce_platform</gateway_type>
  <login>client id</login>
  <password>secret</password>
</gateway>'

• SPREEDLY_TOKEN - Is a result of the base64 of environment_key:access_secret.

• client_id and secret can be fetched directly from your PayPal account. For more information, see PayPal Gateway Credentials documentation.

Result:

<gateway>
    <token>5S0kV27BrZ0Z47TdGK4v1OI7ojB</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}'

1. To configure the Emporix Payment Gateway service, execute the following request:

curl --location --request POST 'https://api.emporix.io/payment-gateway/{TENANT}/paymentmodes/config' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {EMPORIX_AUTH_TOKEN}' \
--data-raw '{
    "code": "paypal",
    "active": true,
    "provider": "SPREEDLY",
    "configuration": {
        "Spreedly/GatewayToken": "{SPREEDLY_GATEWAY_KEY}",
        "Spreedly/EnvironmentKey": "{SPREEDLY_ENVIRONMENT_KEY}",
        "Spreedly/AccessSecret": "{SPREEDLY_ACCESS_SECRET}",
        "Spreedly/PaymentMethodType": "paypal",
        "Spreedly/RedirectURL": "{REDIRECT_URL}",
        "Spreedly/SignatureSecret": "{SPREEDLY_SIGNATURE_SECRET}"
    }
}'

• EMPORIX_AUTH_TOKEN - The standard access token. To check how to get the token see OAuth Service documentation.
• 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 the Emporix support team.

• SPREEDLY_ACCESS_SECRET - Spreedly secret key that you got from the Emporix support team.

• REDIRECT_URL - The URL to your storefront where the user is redirected when the payment is done.

• SPREEDLY_SIGNATURE_SECRET - Spreedly signature secret that you got from the Emporix support team.

Storefront implementation

To use Paypal payment, 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", "paypal")
    
    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")
    window.console.log("TOKEN", token)
    setPayment({
      provider: 'payment-gateway',
      mode: "offsite",
      method: 'paypal',
      displayName: 'Paypal',  
      customAttributes:  {
        token : token,
        modeId : paymentMode.id,
        customer : props.customerId
      }
    })
  }

The payment information is stored because it's needed during the checkout call. The payment object during the checkout request should look like:

{
...
"paymentMethods": [
  {
      "provider": "payment-gateway",
      "method": "paypal",
      "customAttributes": {
          "token": "8Ny2OGn1dwzPBuBdwSej95qAuHN",
          "modeId": "227fed5b-e91a-473e-88ea-3b0e85db8408",
          "customer": "17071158"
      }
  }
]
...
}

Result:

{
    "orderId": "EON1011",
    "paymentDetails": {
        "externalPaymentHttpMethod": "GET",
        "authorizationToken": "nzQPTC2skR6Fb3LgOagBmVGCBC",
        "externalPaymentRedirectURL": "https://www.paypal.com/checkoutnow?token=2KY55219L2352861G"
    },
    "checkoutId": null
}