Shva

Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications described below.

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
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 1.0 ExternalYes
3DS 1.0 InternalNo
3DS 2.0 ExternalNo
3DS 2.0 InternalNo
InstallmentsYes
Level 2 and 3 DataNo
Retrieve Supported Payment MethodsNo
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.

RequestPartial/MultipleModeNotes
AuthorizePartial and multiple are not supportedSynchronous
Capture Partial is supportedAsynchronousCapture requests are not supported with an automatic payment initialization request.
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.

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, register 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 support@zooz.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.

Note

Please do not change or delete the Shva provider configurations that we create for you.

Implementing Automatic Payments

Note

Automatic payments are not supported with installments

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": {
    ... 
  },
  ...
}

Store the Payment Request ID

Make sure to store the identifier of the initial Create Payment request. You will need to pass this identifier in each automatic payment transaction, so that PaymentsOS can relate each automatic payment to the initial payment to which it belongs.

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

The total number of automatic payments to be executed is unknown

If you do not know the total number of automatic payments that will be executed, then you can choose to pass the stnd_order_total_number field with a value of 999.

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

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

Note

This option is not supported when using installments.

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"
      }
    }
}

Note

You can still capture an amount that differs from the original authorization amount, without passing in the preauthorization_hold parameter. Beware that this is not officially supported, however, and may cause unexpected results.

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.

results matching ""

    No results matching ""