Shva

API Version

Minimum required API version: 1.1.0

Payment Methods

The following table lists all supported payment methods.

Currencies

ILS, USD, EUR, GBP, AUD, CAD, CHF, DKK, EGP, JOD, NOK, SEK

Features

The following table provides an overview of all supported and non-supported features.

Feature	Supported
3DS 2.0 External	No
3DS 2.0 PaymentsOS-handled	Yes
3DS 2.0 Provider-handled	No
3DS 2.0 Self-handled	No
Installments	Yes
Level 2 and 3 Data	No
Multi-seller Payments	No
Network Tokens	No
Payment Facilitator	No
PayU Risk	No
Pre-authorization	No
Retrieve Supported Payment Methods	No
Retrieve Supported Plans	No
Statement Soft Descriptor	Yes
Stored Credentials Flag	No
Transaction Processing without CVV	Yes

Requests

The following table lists all supported requests for card-based transactions. Use the bodybuilder to create a sample request body for each request type.

• Cards
• eWallet

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

Creating a Provider Configuration

We will create the necessary Shva terminals for you, and connect them to your PaymentsOS account, so that Shva can process your payment requests. We’ll need some input from your side.

Follow these steps:

1. Register with at least one of the local acquirers (Isracard, Cal, or Leumi Card).

2. Contact PaymentsOS support hubtechsupport@payu.com, to request the “Form for opening business terminals in the Shva credit card system”. Fill in the form and return it to us. The form includes your company details, as well as at least one of your “merchant numbers”, registered with one of the local acquirers, etc.

3. We’ll create a provider configuration in your PaymentsOS account, in the PaymentsOS live environment.

Implementing Automatic Payments

An automatic payment (known locally as ‘Hora’at Keva) is an arrangement with a creditor that allows the creditor to periodically withdraw money from a credit card, checking or savings account to pay a bill. It is normally used for regular monthly payments.

While the steps you must follow for implementing automatic payments with Shva are similar to implementing a regular (one-off payment) transaction flow, they differ in the data you must send per request. Let’s take a look at some examples.

Initializing Automatic Payments

The first step in setting-up automated payments is to initialize the automatic payment flow. This involves authorizing the initial request and passing in all required information about each payment in the flow.

Similar to a one-off transaction flow, you must always start by Creating a Payment. Just note that the amount field does not determine the amounts passed in each subsequent automatic payment, so you must pass a value of 1':

{
  "amount": 1,
  "billing_address": {
    ... 
  },
  ...
} 

Next, invoke a Create Authorization request. In the provider_specific_data.shva.additional_details object pass a transaction_type field with a value of automatic_payment_init, as well as a stnd_order_frequency field indicating the frequency (in weeks) at which each payment should be executed (for example, a stnd_order_frequency of 1 indicates that the payment will be executed once every week). You must also pass either a stnd_order_total_number field (indicating the total number of automatic payments that will be executed) or a stnd_order_total_sum field (indicating the total value of all automatic payments combined).

Here’s an example:

...
  "provider_specific_data": {
    "shva": {
      "additional_details": {
        "transaction_type": "automatic_payment_init",
        "stnd_order_frequency": "1",
        "stnd_order_total_number": "25"
      }
    }
  }
...

Sending Subsequent Automatic Payment Requests

Having completed the initial step of initializing the automatic payment flow, we’re all set to send subsequent automatic payment requests. In each Create Payment request, pass the amount of the payment:

{
  "amount": 2500,
  "billing_address": {
    ... 
  },
  ...
} 

Next, invoke the Create Authorization request. In the provider_specific_data.shva.additional_details object, make sure to pass a transaction_type field with a value of automatic_payment. Also pass a stnd_order_number field that indicates the total number of payments done so far (including the current payment), and an automatic_init_payment_id with the identifier of the very first Create Payment request that was invoked when you initialized the automatic flow.

Here’s an example:

...
  "provider_specific_data": {
    "shva": {
      "additional_details": {
        "transaction_type": "automatic_payment",
        "stnd_order_number": "3",
        "automatic_init_payment_id": "f7cdc75d-68d3-4a0b-b6ae-39c5a9a2cbcb"
      }
    }
  }
...

Integrating Apple Pay

Integrating Apple Pay involves the following:

• Configuring your Apple Developer Account and adding Apple Pay to your checkout page.

• Integrating Apple Pay with your PaymentsOS transaction flows.

Configuring your Apple Developer Account

Proceed as follows:

1. Configure your Apple Developer Account for Apple Pay. For help, see this Configuring your Environment on the Apple developer site. Note that you will be required to upload a CSR (Certificate Signing Request) certificate as part of the configuration procedures.

2. When setting up your account in step 1, you will generate a apple_pay.cer file. You will need this file to decrypt the payload you receive from Apple when requesting a network token, as explain in the steps that follow.

3. Integrate Apple Pay in your checkout page using Apple’s Javascript API, as explained on the Apple developer site.

Now proceed to integrate Apple Pay with PaymentsOS.

Integrating Apple Pay with PaymentsOS

Shva supports the Apple Pay Decrypted Token Flow. This means that once you’ve requested a network token through Apple Pay, you must first decrypt the payload you receive in order to extract the network token. To do so, use the apple_pay.cer file that was generated when you setup your Apple Pay developer account. Then pass the token to PaymentsOS in the Create Authorization or Create Charge requests.

The following shows a sample request. Notice that you must specify ApplePay as the token provider in the payment_method.token_provider field, and pass the token itself in the payment_method.card_number field. The request will also need to include the network_token_sca_data.cryptogram and network_token_sca_data.eci values received from Apple.

...
{
"payment_method": {
    "source_type": "network_token",
    "type": "untokenized",
    "token_provider": "ApplePay",
    "expiration_date": "22-2030",
    "card_number": "4242424242424242"
  },
"network_token_sca_data": {
    "cryptogram": "US20170163629A1",
    "eci": "05"
  }
}

Considerations when Creating a Charge

The status of “completed” Charge requests will change from pending to succeed, only after Shva’s nightly transaction batch has been processed.

Charge Requests with Automatic Payments

Charge requests are not supported with an automatic payment initialization request.

Considerations when Creating a Capture

Consider the items listed below when creating a Capture.

Status Changes

The status of “completed” Capture requests will change from pending to succeed, only after Shva’s nightly transaction batch has been processed.

Sending a Capture Request with an Amount that Differs from the Authorization Amount

Your business may require that you authorize a transaction without knowing the transaction amount in advance. In this case, add preauthorization_hold with a value of true to the provider_specific_data in your create Authorization request. This will invoke a request for approval pending the final transaction amount. Using this option requires approval of the acquirers you work with.

Here’s an example of a request in which the preauthorization_hold parameter is passed:

"provider_specific_data": {
  "shva": {
      "additional_details": {
        "preauthorization_hold": "true"
      }
    }
}

Captures with Automatic Payments

Capture requests are not supported with an automatic payment initialization request.

Considerations when Creating a Refund

Consider the following when creating a Refund:

• To refund the customer for the full amount when the payment was made in installments, pass in the full amount in the refund request. The customer will be refunded for the payments already made and the remaining installment payments will be cancelled.
• In case of a partial refund when the payment was made in installments, you can refund the customer for the required amount without cancelling the remaining installment payments. If you want to cancel the remaining payments, you need to contact the relevant card company and request that all remaining installments are cancelled.
• Optionally, you can also pass the addendum and addendumsettl fields (as described in the Authorization or Charge request) in a Refund request as well. If you omit these fields in the Refund request, then PaymentsOS will take these fields from the Authorization or Charge request (if provided).
• The status of “completed” Refund requests will change from pending to succeed, only after Shva’s nightly transaction batch has been processed.

Considerations when Creating a Void

Consider the items listed below when creating a Void.

Passing the addendum and addendumsettl Fields

Optionally, you can pass the addendum and addendumsettl fields (as described in an Authorization or Charge request) in a Void request as well. If you omit these fields in the Void request, then PaymentsOS will take these fields from the Authorization or Charge request (if provided).

Voids with Automatic Payments

Void requests are not supported with automatic payments.