Shva

Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications in this section to integrate with Shva.

API Version

Minimum required API version: 1.1.0

Payment Methods

The following table lists all supported payment methods.

Payment MethodPayment Method TypeNotes
American ExpressCards
Apple Pay - Decrypted TokeneWallet
DINERSCards
IsracardCards
JCBCards
MAESTROCards
MASTERCARDCards
PLCardsLocal cards, for example, a gift card from Leumicard or Isracard.
VISACards

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.

FeatureSupported
3DS 2.0 ExternalNo
3DS 2.0 PaymentsOS-handledNo
3DS 2.0 Provider-handledNo
3DS 2.0 Self-handledNo
InstallmentsYes
Level 2 and 3 DataNo
Multi-seller PaymentsNo
Network TokensNo
Payment FacilitatorNo
PayU RiskNo
Pre-authorizationNo
Retrieve Supported Payment MethodsNo
Retrieve Supported PlansNo
Statement Soft DescriptorYes
Stored Credentials FlagNo
Transaction Processing without CVVYes

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.

Supported requests for card transactions.
RequestPartial/MultipleModeNotes
AuthorizePartial and multiple are not supportedSynchronous
Capture Partial is supportedAsynchronous
  • Capture requests are not supported with an automatic payment initialization request.
  • Partial captures are not supported with installments.
Charge Not ApplicableAsynchronousCharge requests are not supported with an automatic payment initialization request.
CreditPartial and multiple are not supportedAsynchronous
Refund Multiple is supportedAsynchronous
Void Not ApplicableSynchronousVoid after capture on the same day is supported (before the nightly batch). Void requests are not supported with automatic payments.
Supported requests for eWallet transactions.
RequestPartial/MultipleModeNotes
AuthorizePartial and multiple are not supportedAsynchronous
CapturePartial and multiple are not supportedAsynchronous
Charge Not ApplicableAsynchronous
Refund Multiple is supportedAsynchronous
Void Not ApplicableSynchronousVoid after capture on the same day is supported (before the nightly batch). Void requests are not supported with automatic payments.

Setup Procedures

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

ConfigurationRequired/Optional
In the PaymentsOS Control Center create 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. See Creating a Provider Configuration below. Required
In the PaymentsOS Control Center, create webhooks to be notified when a transaction changes its status.

Note: Many of your API requests will remain in a pending status until the nightly batch, and some may remain in that status for some time after that.
Required
In the PaymentsOS Control Center create a business unit (in the live environment). Use the provider configuration that we created for you as the default provider.Required
Enable automatic payments if desired. Your account needs to be activated by Shva to support ‘Horaat Keva’ and must be activated to support J5 with TranType= 11Optional

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.

Last modified April 30, 2023