Navbar
JSON Node.JS java php C#

Home

Welcome

Welcome to the SafeCharge API developers portal. This API breaks down into few key areas:

SafeCharge’s API is a simple, easy to use, secure and stateless API, which enables online merchants and service providers to process consumer payments through SafeCharge’s payment gateway.

The API supports merchants of all levels of PCI certification, from their online and mobile merchant applications, and is compatible with a large variety of payment options, i.e. payment cards, alternative payment methods, etc.

Using this API reduces the PCI burden from merchant side. A merchant is only required to submit SAQ A-EP form and perform periodical scans by Approved Scanning Vendors (ASV).

This online documentation describes the API’s services and functionality, and is intended for developers by providing all necessary integration information, including the necessary requests and responses.

Please note that while this guide does describe a variety of offered services, additional information about other services such as: SafeCharge’s hosted payment page, back office tool, pay-out services, etc., can be obtained by contacting SafeCharge at integration@safecharge.com

Getting Started - Checkout Page

The quickest way to integrate to SafeCharge and benefit from all our features is via our ‘Hosted Payment’ solution.
With our hosted payment page you only need to call to load our HPP via iFrame or redirect and all features and functionalities are seamlessly integrated.

This method allows the retrieval of a redirect URL to a SafeCharge hosted payment page UI.
Later, you can even do basic customization of your payment page via the Page Builder menu located in the Control Panel. Speak to your account manager for more complex customization.

Steps for using HPP:
1. Authentication Preparation
2. Submit to HPP
3. Handle response

Step 1: Authentication Preparation

To prevent errors that may occur while transferring HTTPS requests, and for SafeCharge to authenticate HTTPS requests, you must create and include an MD5 checksum into your request.
The checksum must be a single string without spaces with the values of the following parameters in the exact order as listed below:
- Secret Key
- Merchant ID
- Currency
- Total amount
- Item list (item_name_1, Item_amount_1, item_quantity_1 to item_name_N, Item_amount_N,item_quantity_N)
- Timestamp


For example: fmIRGJ1nPKJqjjJuCSGesel4BVFRIJJn3J7XpUcWLdsGTOTYRVdkILedgG05nbHt4797923801005868286USD15ball151512011-01-0516:04:26
In this example, the checksum value equals: a2b3d0903b20fe3bc4f2d7a2ea12021e

SafeCharge provides a tool for calculating checksums that is pre-populated with your parameters and their values.

Step 2: Sending the Request

The HTTPS request includes the URL of the payment page and transaction parameters such as the amount of the transaction and the currency.

HTTPS requests must be in the GET name/value pair format (can be in POST as well):

https://ppp-test.safecharge.com/ppp/purchase.do?currency=EUR&item_name_1=Test+Product&item_number_1=1&item_quantity_1=1&item_amount_1=50.00&numberofitems=1&encoding=utf-8&merchant_id=640817950595693192&merchant_site_id=148133&time_stamp=2018-05-15.02%3A35%3A21&version=4.0.0&user_token_id=ran100418_scobd%40mailinator.com&user_token=auto&total_amount=50.00&notify_url=https%3A%2F%2Fsandbox.safecharge.com%2Flib%2Fdemo_process_request%2Fresponse.php&theme_id=178113&checksum=66ce9f4ce1e5f47298e7e5e457d0b21ca8d6a668d549240929924054db6d1a21

Code Sample:

Minimum Required Parameters
The following table displays the required parameters that your website must send to SafeCharge to process a transaction:

FIELDS DESCRIPTION
merchant_id
The vendor’s unique identification number provided by SafeCharge.
merchant_site_id
The vendor website’s unique identification number provided by SafeCharge.
user_token_id
This parameter is a unique identifier for each customer generated by the vendor.
total_amount
The total amount of the transaction.
currency
The ISO code for the currency used in the transaction.
item_name_N
The name of the item.
item_amount
The price of the item number.
item_quantity
The amount of items being purchased.
time_stamp
The GMT time that the transaction took place in the following format:
YYYY-MM-DD HH:MM:SS version
The current version of the payment page.
Currently, the version is=3.0.0.
checksum
The checksum value.

For a complete list of all the parameters you can send SafeCharge, see Input Parameters.

Step 3: Handling Responses

After SafeCharge attempts to process the payment, SafeCharge redirects your customer to a Transaction Outcome page on your site based on the result of SafeCharge’s attempt:

FIELDS DESCRIPTION
Success
SafeCharge redirects the customer to the Success page when SafeCharge successfully processes the transaction.
Pending
SafeCharge redirects the customer to a Pending page until a response is received.
Back
SafeCharge redirects the customer to a Back page when the customer clicks 'Back’ on the payment page.
DMN
The URL of your DMN listener. For more information, see Handling DMNs.

To send your customers to the relevant page, define the URLs for each through the Control Panel Wizard located here.

In addition to redirecting the customer, SafeCharge sends you a response through an HTTPS GET request. This request contains details of the transaction such as the outcome and the payment details of the customer.

There are four sets of parameters that are sent as part of the HTTPS GET request:

PARAMETER SET DESCRIPTION
Transaction
These parameters include the original parameters that you sent to the payment page and define the outcome of the transaction, including the response checksum.
Payment
These parameters include the unprotected payment method information, as provided by the customer on the payment page, such as name on card, expiration data, and the last four digits of the credit card number.
General
These parameters contain the details of the purchase including the item and amount.
Other
These parameters are any custom fields you defined and any other miscellaneous parameters.



Response Checksum Parameter
To ensure that the HTTPS GET request from SafeCharge is authentic, SafeCharge includes the advanceResponsechecksum parameter in the HTTPS GET request. To calculate the checksum, use an MD5 process with the following parameters:
- Secret Key
- totalAmount
- Currency
- responseTimeStamp
- PPP_TransactionID
- Status
- productId



Response Checksum Example
The string made up of the values used in the above example and a sample secret key (AJHFH9349JASFJHADJ9834) and item_quantity_1 (1) would be:

AJHFH9349JASFJHADJ9834115USD2007-11-13.13:22:343453459APPROVEDYourProduct

The calculated checksum would then be:
826fb8c4a2451e86f41df511c46f5a9b

More options
1. Dynamic Descriptor
2. Save the card and starts managing user payments
3. Auth – Settle
4. Subscription


Getting Started - API

This section describes how to quickly set up a server-to-server integration to SafeCharge, which is API based and PCI compliant, and begin processing cards.

Two important things you should know about SafeCharge integration before you start:



If you are PCI compliant and would like to handle card information follow the four steps described below to quickly set up a server-to-server integration to SafeCharge:

Setting Up Server-to-Server Integration to SafeCharge

  1. On your server-side: Authenticate and receive the security token.
  2. On your client-side: Collect payment details), embedded with our web SDK
  3. On your server-side: Submit a payment request.
    In case a full 3D Secure challenge flow is needed, you also must:
  4. On your client-side: Redirect to perform the 3D Secure 2.0 challenge and final payment.

Step 1: Authenticate Server-Side

Before you can start, you must authenticate with SafeCharge using the getSessionToken method.
To authenticate, you need to provide the credential details you have received from SafeCharge - merchantId, merchantSiteId, clientRequestId - and you need to hash them into a checksum to guarantee their consistency. For the checksum hashing, use SHA256 and also include your secret key that was provided to you by SafeCharge.

Once you submit the secret key, you receive the SessionToken that you need to pass on to your client-side to perform the next step.

Step 2: Collect Payment Details Client-Side

On you web page, you are free to design your own payment form to collect all the payment details. To guarantee PCI compliance, embed SafeCharge Web SDK Fields into your payment form on your web page and collect the sensitive card data:

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<form action="/charge" method="post" id="payment-form">
Click to expend to view an example to a full payment form
            <div class="form-row">
                    <label for="card-field-placeholder">
                        Credit or debit card
                    </label>
                    <div id="card-field-placeholder" class="your css-classes">
                    <!-- SFC Card widget will be inserted here. -->
                    </div>
                    <!-- Used to display form errors. -->
                    <div id="scard-errors" role="alert"></div>
            </div>
            <button>Submit Payment</button>
</form>

COPIED
1
2
3
4
5
6
7
8
9
10
11
// Instantiate Safecharge API
var sfc = SafeCharge({
sessionToken : '<sessionToken>', // the received from step 1.
      env: 'test', // the environment you’re running on, prod for production
      merchantSiteId : 152358 // your merchantsite id provided by Safecharge
});

Instantiate Safecharge Fields
var ScFields = sfc.fields({
    fonts: [// { cssUrl: ‘<your url>’}, // include your custom fonts]
       })

COPIED
1
2
var scard = ScFields.create('card', {style: style});
scard.attach(document.getElementById('card-field-placeholder'));

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
sfc.initPayment( {
                                "sessionToken": resOrder.sessionToken,
                                "merchantId": merchantId,
                                "merchantSiteId": merchantSiteId,
                                "userTokenId": "someone@site.com", // optional
                                "clientUniqueId": "695701003",
                                "currency": "EUR",
                                "amount": "35",
                                "paymentOption": scard 
                }, function(result){
                               console.log('it took', Date.now() - start  )
                                console.log(result)
                })

paymentOption

This object holds all the relevant payment option information (credit card information in our case, but can be also for Alternative Payment Methods).

This paymentOption JSON object is the data and the only data you will always have to move between client-side and server-side for any future iteration.

The structure of the object is defined in detail here, but you do not really need to explore or manipulate any of the data it holds. Just move it along from client-side to server-side and vice versa.

Advanced users are welcome to create, explore, and retrieve the information and even manipulate its data.

Step 3: Perform a Payment Server-Side

Once you have received the paymentOption data, you can perform the payment. Submitting a payment request is done via the Payment method, using the paymentOption, the sessionToken (retrieved from Step 1) and the transaction details.

You again have to calculate the checksum.

Parsing the Response

The response contains information about the transaction and about the payment, but most importantly it returns the status of the transaction - transactionStatus.

The transaction status can be:

Step 4 (optional): Perform a 3D Secured Payment Client-Side

A possible response to a payment API request is “Redirect”. This means that the charging process has not yet ended, and you need to perform a 3D Secure Challenge procedure that authenticates the card holder directly with their issuer.

3D Secure Challenge

With a card payment returns a “Redirect” transaction status, you need to perform a 3D Challenge to enable the card issuer to authenticate the end user, based on which chargeback liability shift can be made from you to the issuer.

3D Secured Payment Based on the challenge response, you then need to send a second payment request. This time it is verified with 3D Secure. Using the client-side PaymentFrame, you instruct SafeCharge to perform both actions (the challenge and 3D secured payment) on your behalf, in complete transparency.

Integration Guidelines

The PaymentFrame performs the challenge. It submits the event of the outcome and returns either Success or Failure.

Direct Merchant Notification (DMN) (optional)

Use our DMN webhooks in order to receive the payment notification, in order to verify the response of the payment and receiving extra details of the transaction.

API Guides

SDK

Server SDK (Java)

The methods above a available to be worked with directly, or via our Java Server SDK available here: https://github.com/SafeChargeInternational/safecharge-java

Server SDK (PHP)

The methods above a available to be worked with directly, or via our PHP Server SDK available here: https://github.com/SafeChargeInternational/safecharge-php

Client SDK

The API allows merchants to upload their existing JavaScript and consume the offered services from the client side.

Credit Card Tokenization (Web): PCI certified merchants that can enter card data on their side, can work fully server to server. However, low-level PCI certified merchants, which cannot enter card data on their side, are required to use the client SDK PCI and Tokenization.

Credit Card Tokenization (Native iOS & Android):
JavaScript and UI are offered for the use of mobile native applications. iOS SDK is available at https://github.com/SafeChargeInternational/safecharge-ios. Android SDK is available at:https://github.com/SafeChargeInternational/safecharge_sdk_android .



Apple Pay (Web): In order to enable Apple Pay, the merchant is required to use Apple Pay payment client SDK.

Apple Pay (Native iOS & Android):
Javascript and UI are offered for the use of mobile native applications. iOS and Android SDK will be available soon.

Alternative Payment Method

Follow the steps below for the quickest and most recommended way to complete this:

1. getSession
2. Complete the payment option form.
3. Initiate APM session (only fore redirect based APMs)
4. Redirect to APM

Get Session Token

Each API session starts with the getSessionToken method and receiving a session token. This token is used as the authentication factor with each call to our API.

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
    {
    "merchantSiteId": "{{merchantSiteId}}",
    "merchantId": "{{merchantId}}",
    "clientRequestId": "{{clientRequestId}}",
    "timeStamp": "{{timestamp}}",
    "checksum": "{{checksum}}",
    "sessionToken": "a304446b-4497-43b0-9dc3-36c0bf01bcdd",
    "internalRequestId": 92849032,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "8912193623117089371",
    "merchantSiteId": "125823",
    "version": "1.0",
    "clientRequestId": "20180516131415"
    }
PARAMETER DESCRIPTION
merchantId
The merchant ID provided by SafeCharge.
merchantSiteId
The merchant Site ID provided by SafeCharge.
clientRequestId
The ID of the API request in merchant’s system. This value must be unique.
XXX
This must be sent in order to perform future actions, such as, reconciliation, identify the transaction in the event of any issues, etc.
timeStamp
The local time when the method call is performed in the following format: YYYYMMDDHHmmss
checksum
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.

Render APM Payment Form

With the API you have two approaches to support multiple APMs:

Hard Coded Approach
In case you have simple requirementsf for APMs (only a few APMs, for a few countries), you can simply “hardcode” in your form the input that is required for each of your required methods and how to handle them – redirect or direct.

Holistic/Realtime/Dynamic Approach
On the other hand, if you wish to access many APMs in many countries and to have your payment form automatically detecting the most relevant APM for the specific user, then we suggest using the getMerchantPaymentMethods API method.

Initiate APM Session

To initiate the APM session, you need to call the PaymentAPM method.

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    {
    "merchantSiteId":"{{merchantSiteId}}",
    "merchantId":"{{merchantId}}",
    "sessionToken":"{{sessionToken}}",
    "clientRequestId":"{{clientRequestId}}",
    "userTokenId":"testPayPal",
    "timeStamp":"{{timestamp}}",
    "checksum":"{{checksum}}",
    "currency":"EUR",
    "amount":"100.00",
    "paymentMethod":"apmgw_expresscheckout",
    "addendums":{
        "localPayment":{
        "nationalId":"petka",
        "debitType":"RegularCredit"
        },
    "items":[
        {
        "name":"watch",
        "price":"100.00",
        "quantity":1
        }
        ]
    }
FIELDS DETAILS
Credentials fields
merchantId, merchantSiteId, clientRequestId, timeStamp, checksum
See authentication for details.
paymentMethod
The name of the paymentMethod to be used, as selected by the user. (List of APMs)
If this is a returning user you can send the userPaymentOption field instead.
Amount details
amount, amountDetails, items. See amount handling for details.
Currency
The transaction currency.
Optional fields
For example, user details. See full optional fields list.



The response for this method depends on the type of the APM:
- Direct based APM – The paymentCC processes the transaction and the response returns a list of direct APMs, e.g. iDEAL.
- Redirect APM – The payemntCC retrieves the APM URL to redirect to, e.g. PayPal. For more info, see list of redirect APMs.

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
    {
    "redirectURL":"https://www.sandbox.paypal.com/ca/cgi-bin/merchantpaymentweb?cmd=_express-checkout&token=EC-83H52573LU4022040",
    "orderId":230581332,the
    "userPaymentOptionId":"2101643",
    "userTokenId":"testPayPal",
    "sessionToken":"6f8ef8a8-02ec-4f5b-bd75-12c770dc7344",
    "internalRequestId":92845522,
    "status":"SUCCESS",
    "errCode":0,
    "reason":"",
    "merchantId":"8912193623117089371",
    "merchantSiteId":"125823",
    "version":"1.0",
    "clientRequestId":"20180516122327"
    }
FIELD DETAILS
transactionStatus
The status of a the transaction. For Direct APM only.
Possible values include:
APPROVED
DECLINED
ERROR
redirectURL
The APM’s URL to redirect to. For Redirect APM only.
reason
The error reason, in the event of an error.
AuthCode
The authorization code for an approved transaction.
transactionID
The unique transaction ID assigned by SafeCharge. This ID is needed for future related requests, such as Refund.
userPaymentOptionId
An ID assigned for the processed user’s card for future transaction to performed by the same user. check Returning users.
Optional fields
For example, user details. See full optional fields list.


Example Response
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "reason": "",
    "redirectURL": "https://www.paypal.com//ca//cgi-bin//merchantpaymentweb?cmd=_express-checkout&token=EC-9YL41173YN011321K&useraction=commit",
    "orderId": 33354491,
    "clientRequestId": "A88E8HMQ2",
    "internalRequestId": 9315781,
    "merchantDetails": {
        "customField1": "customField1-valueU",
        "customField2": "customField2-valueU"
        },
    "version": "1.0",APM 
    "merchantSiteId": "126006",
    "merchantId": "2502136204546424962",
    "clientUniqueId": "P1L6Q8CB6Y2G",
    "errCode": 0,
    "userPaymentOptionId": "7698001",
    "sessionToken": "ed20bece-6f73-4ed6-b8a0-79ff62ddc71a",
    "userTokenId": "230811147",
    "status": "SUCCESS"
}

An example of a typical PayPal response is displayed on the right side of your screen.

Response for the APM via DMN

Example Response
COPIED
1
https://secure.safecharge.com/ppp/ExampleDMNURL?ppp_status=OK&PPP_TransactionID=11111111111&userid=UserID&merchant_unique_id=11111222333&customData=CustomData&productId=ptadapter&first_name=First&last_name=Last&email=email@safecharge.com&currency=GBP&Status=APPROVED&cardType=Credit&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Address&address2=&country=United+Kingdom&state=&city=City&zip=12345&phone1=12312312312&phone2=&phone3=&client_ip=123.123.123.123&nameOnCard=MYCard&cardNumber=4****1111&bin=1111111&acquirerId=103&expMonth=06&expYear=19&Token=igjweroifghwqfghwqiugheqriugheqrgiuvherviuerhviuerhvui559990355&ExErrCode=0&ErrCode=0&AuthCode=123123&AvsCode=F&Cvv2Reply=M&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=1111111&requestVersion=4.0.0&message=Success&merchantLocale=en_US&unknownParameters=&payment_method=cc_card&ID=&merchant_id=1111111111111111111&responseTimeStamp=2019-03-25.07%3A14%3A33&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=brebveirvbierbviubreiuvberivu=&transactionType=Sale&externalEmail=&cardCompany=Visa&eci=5&user_token_id=UserToken&user_token=auto&userPaymentOptionId=123121231231&TransactionID=111111111111111111&3Dflow=1&finalFraudDecision=Accept&orderTransactionId=999999999999&totalAmount=10.00&dynamicDescriptor=Bank+Descriptor&Reason=&ReasonCode=0&item_name_1=product&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20181106&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=da95e9c17badb7c6a9447de79e63a9d2&advanceResponseChecksum=af4f8adc26823c20d1bc7370478a4ee7

An example of a typical DMN response is displayed on the right side of your screen.

Supported Payment Methods

APM Unique SafeCharge Names

The following tables provides a list of the supported payment methods.
Payment method names can be sent in getUserUPOs method (paymentMethodName parameter) and paymentAPM method (paymentMethod parameter).
The supported countries and currencies below appears as their ISO country code.
For more information see ISO country code list -> Full list of country codes and ISO currency code list -> Codes in XLS and XML form


Sub Methods

In several cases, payment methods have optimised flows for certain scenarios, e.g. redirect based methods allow a direct server-to-sever payment, without user intervention under certain conditions.
This flows can be invoked by the subMethod class of the request.


PayPal Membership Agreement (“ReferenceTransaction”)
PayPal supports direct server-to-server payment requests instead of the regular redirect flow. This request can be invoked only for re-bill transactions. In another words, a first transaction must be invoked in the regular redirect way, but if it is marked by the subMethod, then any following up transaction can be done server-to-server.
-subMethod should be set to ReferenceTransaction. In both the first and the second transaction.
-No other fields need to be provided.



PayPal Quick Registration
These PayPal features allow you to register your user based on their registration to their PayPal registration.
In order to invoke:
-subMethod should be set to QuickRegistration. In both the first and second transactions. -No other fields need to be provided.
Please contact SafeCharge’s integration team at integration@safecharge.com for further information.



APM Account Identifiers

Some payment methods has their own requirements for identifying their end-users.
Payment methods account fields can be sent in getUserUPOs method (upoData parameter) and paymentAPM method (userAccountDetails parameter).



APM Unique SafeCharge Names (Payin)

NAME NAME IN SAFECHARGE SUPPORTED COUNTRIES SUPPORTED CURRENCIES



APM Unique SafeCharge Names (Payout)

NAME NAME IN SAFECHARGE SUPPORTED COUNTRIES SUPPORTED CURRENCIES

APM Account Identifiers (Payin)



APM Account Identifiers (Payout)



Note that:
For PayPal: If re-billing agreement required, then need to send the value “ReferenceTransaction” in SubMethod field, and also send the numeric value the merchant received from Pay Pal in ReferenceID field.
For Fast Bank Transfer: some parameters are mandatory per country. For more information, please contact SafeCharge’s integration team at integration@safecharge.com

Handling the Direct Merchant Notification

Returning Users

To make your returning customers’ experiences easier and friendlier, we have solutions to implement that save them from having to provide their payment details more than once.

Our PCI certification allows us to safely save card holder details for future use so they do not need to be collected again. To enable this, you have to use the following fields:

  1. userTokenId – A unique ID value to uniquely identify your user. This is submitted during your first transaction with the user details. When the user returns, this is the only user field you need to provide.
  2. userPaymentOption - In the response for the user’s first (and any) transaction, you receive this field to replace the payment option details for future transactions that use the user payment option of the same user, instead of recollecting them.
    • CVV – Since CVV is not allowed to be stored (not even with our level 1 PCI certification), you still need to collect and submit this value with every transaction. This provides an important authentication layer that protects all parties involved.

Rebilling

SafeCharge’s rebilling service enables merchants to create and manage recurring charges for products and services offered to their customers.
The service gives the merchant the flexibility to set payment plans or subscriptions. Moreover, it gives the merchant has the ability to modify, extend or cancel such charging plans.
The service also takes advantage of the card schemes’ card updaters (on supported cards), to ensure frictionless charging of a running subscription, in the event that card details were changed by the card issuer or the customer’s side.

The rebilling service consists of three key components:
- Plan - The recurring-payment conditioning offered by a merchant for a single or a set of products it sells.
- Subscription - The actual recurring payment contract that was set up for a specific consumer.
- Customer - The end-user registered to one or more subscriptions, under one or more payment plans.

createPlan

This method is used for creating a charging plan and to set timing and payment conditions for a certain product or service.

Input Parameters

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "name": "8FGWD0UVL8ZN4GI",
    "description": "Descr",
    "planStatus": "ACTIVE",
    "currency": "EUR",
    "initialAmount": "15.67",
    "recurringAmount": "4.24",
    "startAfter": {
        "day": "3",
        "month": "2",
        "year": "1"
        },
    "recurringPeriod": {
        "day": "1",
        "month": "0",
        "year": "0"
        },
    "endAfter": {
        "day": "6",
        "month": "7",
        "year": "8"
        },
    "timeStamp": "20190228160209",
    "checksum": "eb50508f5cd2e99797a658f686ceb5ea"
}
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
4
{
    "planId":"",
    "status": ""
}
PARAMETER TYPE DESCRIPTION


editPlan

This method is used for editing the charging or timing conditions of a specific rebilling plan.

Input Parameters

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "planId": "3101",
    "name": "EWTDLJ5E8FJA1G6",
    "description": "Darin's Masterplan - Updated",
    "currency": "GBP",
    "initialAmount": "13.67",
    "recurringAmount": "3.24",
    "planStatus": "INACTIVE",
    "timeStamp": "20190228160249",
    "checksum": "264b8be925f75c81b5e64100e1ab6108"
}
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
{
    "status": ""
}
PARAMETER TYPE DESCRIPTION



getPlansList

This method is used to invoke the information of an existing plan.

Input Parameters

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "planId": "101",
    "planStatus": "ACTIVE",
    "currency": "EUR",
    "firstResult": "0",
    "maxResults": "10",
    "timeStamp": "20190228160245",
    "checksum": "14d896db1114aed395d0670f57563c4b"
}
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "total": 1,
    "plans": [
        {
            "recurringAmount": "4.24",
            "startAfter": {
                "month": "2",
                "year": "1",
                "day": "3"
            },
            "recurringPeriod": {
                "month": "0",
                "year": "0",
                "day": "1"
            },
            "merchantId": "2502136204546424962",
            "initialAmount": "15.67",
            "name": "v8SQ1TOWCQ285KON",
            "description": "Darin's Masterplan",
            "planStatus": "ACTIVE",
            "planId": "101",
            "currency": "EUR",
            "endAfter": {
                "month": "7",
                "year": "8",
                "day": "6"
            }
        }
    ],
    "status": "SUCCESS"
}
PARAMETER TYPE DESCRIPTION



createSubscription

This method is used for creating a subscription for consumers that wish to conduct future recurring transactions to consume a certain service or a product.

Input Parameters

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "userTokenId": "230811147",
    "planId": "101",
    "userPaymentOptionId": "6434806",
    "currency": "EUR",
    "initialAmount": "15.67",
    "recurringAmount": "4.24",
    "startAfter": {
        "day": "3",
        "month": "2",
        "year": "1"
        },
    "recurringPeriod": {
        "day": "1",
        "month": "0",
        "year": "0"
        },
    "endAfter": {
        "day": "6",
        "month": "7",
        "year": "8"
        },
    "timeStamp": "20190228160210",
    "checksum": "5ee1a7ed93f721b537457afce3432102"
}



PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
4
{
    "subscriptionId": "928691",
    "status": "SUCCESS"
}
PARAMETER TYPE DESCRIPTION



editSubscription

This method is used for editing the payment or recurrence conditions of a certain rebilling subscription.
A card/user cannot be changed on an existing subscription.

Input Parameters

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "userTokenId": "230811147",
    "planId": "101",
    "subscriptionId": "928711",
    "userPaymentOptionId": "6434806",
    "currency": "GBP",
    "recurringAmount": "4.24",
    "startAfter": {
        "day": "3",
        "month": "2",
        "year": "1"
        },
    "recurringPeriod": {
        "day": "1",
        "month": "0",
        "year": "0"
        },
    "endAfter": {
        "day": "6",
        "month": "7",
        "year": "8"
        },
    "timeStamp": "20190228160252",
    "checksum": "8677537a6721ff6f032bfaac3ea817f4"
}
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
{
    "status": "SUCCESS"
}
PARAMETER TYPE DESCRIPTION



getSubscription

This method is used to invoke the information of an existing subscription.

Input Parameters

Example Request
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    "subscriptions": [
        {
        "updateDate": "20190301085142",
        "recurringAmount": "4.24",
        "recurringPeriod": {
            "month": "0",
            "year": "0",
            "day": "1"
        },
    "planName": "8SQ1TOWCQ285KON",
            "endAfter": {
            "month": "7",
            "year": "8",
            "day": "6"
        },
    "merchantSiteId": "126006",
        "startAfter": {
            "month": "2",
            "year": "1",
            "day": "3"
        },
    "userPaymentOptionId": "6434806",
    "initialAmount": "15.67",
    "subscriptionStatus": "ACTIVE",
    "planId": "101",
    "currency": "EUR",
    "userTokenId": "230811147",
    "subscriptionId": "928811",
    "createDate": "20190301085138"
        }
    ],
    "total": 1,
    "status": "SUCCESS"
}

PARAMETER TYPE DESCRIPTION



cancelPlan

This method is used to cancel an existing plan.
The plan is not deleted on our side, but its status is changed to 'CANCELED’.

Input Parameters

Example Request
COPIED
1
2
3
{

}
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
{

}
PARAMETER TYPE DESCRIPTION



cancelSubscription

This method is used to cancel an existing subscription.
The subscription is not deleted on our side, but its status is changed to 'CANCELED’.

Input Parameters

Example Request
COPIED
1
2
3
4
5
6
7
{
    "merchantId": "2502136204546424962",
    "merchantSiteId": "126006",
    "subscriptionId": "928711",
    "timeStamp": "20190228160208",
    "checksum": "57a772c31b6a947f7a6e1bd3f2939eb8"
}
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
{
    "status": "SUCCESS"
}
PARAMETER TYPE DESCRIPTION



How to Execute

Unlike other API functions, rebilling does not require merchants to obtain a session token. Instead, it uses the checksum to validate the communication’s integrity.

Additionally, in order to perform payment actions for saved cards and returning customers, the following customer/card identifiers are required to be provided with relevant API calls:
1. user_token_id - The merchant’s internal identifier of a customer.
2. UPOID - User Payment Option ID. A unique ID assigned on SafeCharge’s end for each different payment method and card. The value must be sent with the user_token_id in order to inform us regarding what card is required upon the desired action. This value is returned by SafeCharge when creating a new user or a UPO.

An example of a flow of calls by a merchant to our API:
- getSessionToken.do (mandatory)
- CreateUser.do / addUPOcreditCard.do (optional; must be created once per unique card)
- CreatePlan.do (optional; must be created once per plan)
- When setting-up a subscription, the following calls are also required:
- CreateSubscription.do/EditSubscription.do/CancelSubscription.do

PCI and Tokenization

Description

The Payment Card Industry (PCI) Data Security Standard (DSS) is an information security standard for organizations that manage branded credit cards from the major card schemes. The PCI Standard is mandated by the card brands and administered by the Payment Card Industry Security Standards Council PCI DSS compliance is categorised into multiple levels, with each level consisting of its own requirements. A company’s level is determined by its annual card transaction volume and card acceptance channel(s). For most levels, you need to complete a self-assessment questionnaire (SAQ), which varies depending on the level. The SAQ consists of a series of yes/no questions for each PCI DSS requirement, depending on your security posture and practices and the complexity of your business.

There is correlation between the SAQ and PCI and measure of requirements you need to undertake and between the SafeCharge integration method you decide to implement. This comes from how each integration method influences who is collecting and transmitting the card holder information.

SafeCharge Integration Who is Collecting Cardholder Information PCI Implication
Pure API
Merchant, on its form
Fill in the detailed SAQ-D. committing to certain security measures, quarterly scans
Hosted Payment Page
SafeCharge, on our hosted page
You are required to submit the simplest SAQ-A form, that specifies how you are outsourcing PCI to SafeCharge
Web SDK Fields
SafeCharge collects it directly form the merchant page
You are required to submit the simplest SAQ-A form, that specifies how you are outsourcing PCI to SafeCharge
cardTokenization / safecharge.js
Merchant collects it and passes it to SC directly from the frontend
Fill in the moderate SAQ-A EP (shorter than the SAQ-D) committing to certain security measures, quarterly scans

safecharge.js

safecharge.js is a JavaScript library for building payment flows. It allows you to collect sensitive data from the user and create representative Tokens for safely sending that data to your servers. This allows a PCI descoped way to collect and process card numbers.

SafeCharge Web SDK Fields

This SDK is a set of components for building checkout flows, ready to collect user data. It tokenizes the sensitive data from within the SafeCharge Fields without needing to communicate with your server.

Features

For step by step guide please refer to SafeCharge Fields.

3D Secure Overview

Introduction

What is 3D Secure 2.0?

As part of the new PSD2 and Strong Customer Authentication (SCA) regulations, a new standard of protecting e-commerce transactions has been introduced.

As the share of e-commerce and especially mobile transactions is growing, the industry has been suffering from high chargeback ratios and low approval ratios compared to card present transactions. With the introduction of 3D Secure 2.0, this gap should be minimised.

To support businesses in maximizing their conversions after the enforcement of strong customer authentication, SafeCharge enables dynamic implementation of 3D Secure 2.0. This entails making real-time intelligent decisions about whether or not to take advantage of strong customer authentication exemptions and push for higher conversion.

The SCA mandate requires 3D Secure to be applied to all electronic payments – including proximity, remote and mobile payments – within the European Economic Area (EEA). The strong customer authentication mandate is complemented by some limited exemptions that aim to support a frictionless customer experience when transaction risk is low.

3D Secure 2.0 supports the transfer of rich data for transactions enabling possible risk-based decisions regarding whether to authenticate or not. This means that based on certain criteria, the end user may or may not be asked to perform a ‘challenge’ to ensure their authenticity. The consumer experience has also been simplified and enhanced thanks to the elimination of the preliminary enrolment process and by not requiring the end user to remember as many passwords.

Some of the main advantages of 3D Secure 2.0 compared to 3D Secure 1.0 are: - Better user experience - Multiple device support, including mobile in-app support - Enhanced data exchange to enable Risk Based Authentication - Stronger and easier user authentication

Audience

This document serves as a guide for existing SafeCharge merchants that process transactions via SafeCharge’s REST API service. This guide instructs these merchants on how to transition from 3D Secure 1.0 to 3D Secure 2.0 by detailing the additional parameters needed and should be used in addition to the current integration guides.

Strong Customer Authentication

In 3D Secure 1.0, users could share their static password for 3D authentication, and there was a risk that their password could be stolen. With strong customer authentication implemented using 3D Secure 2.0, user authentication is nearly flawless. During the authentication with their card issuing bank, cardholders are required to supply two of the following three categories of information: - What the customer is: That can be a fingerprint, facial features, DNA signature, iris format, or voice patterns. - What the customer knows: This can be a password, sequence, PIN, pass phrase, or even a personal fact, like the name of their first pet. - What the customer has: This can be a mobile phone, badge, token, wearable device, or smart card.

Frictionless vs Challenge Customer Authentication

During the 3D Secure 2.0 authentication, the issuer performs a risk-based analysis to determine whether a transaction should be challenged. A challenge means that the user is presented with an authentication screen of the issuer that follows the Strong Customer Authentication rules. Issuer risk analysis is performed based on the data collected during the transaction, such as device information, transaction information, time zone and various other parameters. If an issuer determines that the transaction is low-risk, a frictionless indicator is returned in the authentication response. Frictionless flow means that the transaction is considered 3D authenticated and a liability shift applies, without the need of the user challenge screen.

It is highly recommended that merchants send as many optional parameters as possible during the authentication, as it increases the chance of frictionless flow and better user conversion.

Strong Customer Authentication Exemptions

Not every transaction is subject to strong customer authentication. For example, low-risk and low-value transactions worth less than 30 EUR are exempt. But if low risk payments adding up to over 100 EUR are made on the card, or more than five consecutive transactions take place, strong customer authentication applies. For low-risk transaction exemptions, the risk of a transaction is based on the average fraud levels of the card issuer and the acquirer processing the transaction.

Another type of exemption is applied in a case of merchant whitelisting, i.e. during authentication, when a cardholder can choose to whitelist the merchant. In such case, all subsequent transactions between the specific cardholder and the merchant are exempted.

The intent of PSD2 is to make SCA a requirement for all online transactions. However, there are some exemptions to this mandate, and for any given transaction your acquirer can set an exemption that is most appropriate.

Exclusions and Exemptions

Exemption for Low-Value Remote Payments

This exemption applies to remote transactions up to €30, with a maximum €100 cumulative sum or 5 consecutive transactions since SCA was last applied.

The issuer is allowed to choose alternatively between the €100 cumulative sum or 5 consecutive transactions for applying the exemption.

This means that SCA must apply only to the sixth and subsequent transactions exceeding the cumulative sum of €100.

Exemption for Low-Value Contactless Payments

Exemptions are provided for low-value contactless transactions (LVTs) up to €50 with a maximum €150 cumulative sum or 5 consecutive transactions.

Transaction Risk Assessment (TRA) Exemptions

3D Secure 1.0 Fallback

While European Issuers should implement 3D Secure 2.0 protocol by September 2019, issuers outside of Europe may not yet support it.

A merchant should be able to fall back to 3D Secure 1.0 protocol if 3D Secure 2.0 is not supported.

Issuers worldwide are expected to support 3D Secure 2.0 by the end of 2020.

The merchant is required to support both 3D Secure 1.0 flow and 3D Secure 2.0 flow.

After the Init call that checks if the card is enrolled in 3D Secure 2.0, the merchant needs to continue with 3D Secure 1.0 or 3D Secure 2.0 Authentication.

Recurring Transactions

Special rules of Strong Customer Authentication apply to subscription transactions. SCA/3D Authentication should be applied for the first authorization that initiated the transaction. The liability shift is applied for this transaction. The frequency of the subscription and expiry date should be sent during the authorization. These parameters should be part of the subscription agreement with the cardholder. If the subscription parameters are about to change, a new agreement should be performed with the cardholder, including SCA authentication. For the subsequent MIT transactions, no SCA is applied as there is no interaction with the cardholder, nor does the liability shift. The first transaction reference, which initiated the subscription, should be sent along with the authorization.

Liability Shift

With 3D Secure 2.0 Authentication applied, a transaction receives a liability shift from fraud related chargebacks, just like 3D Secure 1.0.

A liability shift of 3D Secure 1.0 transactions continues to apply, until the official sunset date, which has not yet been set.

The change in merchant protection when comparing 3D Secure 2.0 Authentication vs 3D Secure 1.0 is that when authentication results are returned by server attempts on behalf of a directory server that is not available, the transaction still receives a liability shift.

3D Secure Guide

This section explains how to handle 3D Secure with SafeCharge.

Best Practice Integration

The quickest and seamless way, and also the most recommended way to handle 3D Secure is to follow our Getting Started section. It gives you a step-by-step guide and lets SafeCharge handle the 3D Secure complexity using our Web SDK. To sum up the steps you need to perform the following:

For complete detail, please refer to Getting Started.

Special 3D Secure Handling

The following parameters should be applied when implementing subscription/recurring transactions.

For the first transaction that initiated the subscription, the 3D flow should apply.

The first call to payment must include the following parameters:

  1. Under the threeD class (paymentOption.card.threeD)
    rebillExpiry
    rebillFrequency

  2. Under the storedCredential class (paymentOption.card. storedCredentials)
    storedCredentialsMode =2

The second call to payment (in case of a challenge) should also include under the storedCredential class (paymentOption.card. storedCredentials)

storedCredentialsMode =2 3. For subsequent transactions sent by the merchant, no 3D Authentication is applied.

Any call to the payment transaction must include the field:
isRebill =2



Server Only Flow

If you prefer to perform a API only integration, namely, not use or only partly use our Web SDK, you need to understand the full 3D Secure flow and be familiar with its details.

  1. Authentication using the getSessionToken method. Initialises the security token.
  2. On the client side you have to display the payment form and collect card details.
  3. Initialization using the initPayment method. This method does the following:
    • Retrieves the 3D secure version of the card
    • 3D 2.0: Returns the 3D method URL information, which is required for the next step.
  1. If 3D 2.0: On the client-side you have to implement the 3D Secure method URL and collect the 3D Browser information.
  2. Payment - You need to submit the relevant 3D Secure information, by populating the input paymentOption.threeD field (full field set is here)
  3. If a challenge is required, perform the challenge.
  4. Perform the second payment request.

GetSession and InitPayment

The first two steps are the invocation of those two methods:

  1. getSessionToken – Server-side call and initiates the authentication with SafeCharge. Complete reference is @ getSessionToken
  2. initPayment – Client-side call to and to verify the 3D secure 2.0 information. Complete reference is @ initPayment

Method URL Handling

According to 3D Secure 2.0, the issuer can request that you perform the “Method Url”. This is a URL in which you need to implement in a form, allowing the Issuer to collect thumbnail the browsing information directly.

The sample code shows how to embed the retrieved methodUrl and methodPayload field values in the web form.

COPIED
1
2
3
4
<form name="frm" method="POST" action={paymentOption.card.threeD. methodURL}>
<input type="hidden" name=" threeDSMethodData" value={paymentOption.card.threeD. methodPayload}
</form>

The ACS/ISSUER posts the “three.methodData" that contains the Base64 encoded JSON with the threeServerTransID.

Example:

3D Payment Complete Input

(including the 3D Secure browsing information)

This section explains how to use the payment method for 3D secure. For a complete description of the payment method please refer to payment.

The following table details the full list of 3D Secure fields to be sent with the payment method. All the following fields are placed under the threeD class, under the card class, and under the paymentOption class.

Example:

Performing a Challenge and Parsing CReq

Before performing a challenge, you should first verify if a challenge is indeed required. This is done by examining the response of the preceding payment request. In case the response transactionStatus is Redirect, it means a challenge is required; otherwise you get a transaction response (approved, declined or error).

To perform a challenge, redirect the user to the Issuer Authentication URL as received in the paymentOption.card.threeD.acsUrl field. Once a challenge is completed, the ACS/Issuer posts a CRes JSON object (encoded in Base64) to the notificationURL field supplied at the Payment

The Cres message contains the outcome of the challenge.

Field Description
threeDSServerTransID
The 3DS Server Transaction ID, which is the same as in the InitAuth3D response.
acsTransID
The ACS Transaction ID, as generated by the issuer.
messageExtension
Optional data necessary to support requirements not otherwise defined in the 3-D Secure.
messageType
The message type. (Cres)
messageVersion
The 3DS protocol version used for the authentication.
transStatus
The transaction status. Possible values:
Y – challenge/authentication succeeded
N – challenge/authentication failed

CRes Example

Second Call to Payment

The second call to payment is the same as the first call. The only differences are as follows:

Input

Output

Parameter Type Description
authenticationStatus
String(1)
This field is returned only from the SECOND payment.
Indicates whether a transaction qualifies as an authenticated transaction or as an account verification.
Possible values:
Y = Authentication Verification Successful.
N = Not Authenticated/Account Not Verified; Transaction denied.
U = Authentication/Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
C = Challenge Required; Additional authentication is required using the CReq/CRes.
D = Challenge Required; Decoupled Authentication confirmed.
R = Authentication/Account Verification Rejected; Issuer is rejecting
Note: The Final CRes message can contain only a value of Y or N.
Note: If the 3DS Requestor Challenge Indicator = 06 (No challenge requested; Data share only), then a Transaction Status of C is not valid.
whiteListStatus
string
Did this consumer define this merchant as whitelist or not. If the consumer defined the merchant, then this is the reason why the challenge did not happen.
Possible values:
Y = 3DS Requestor is whitelisted by cardholder
N = 3DS Requestor is not whitelisted by cardholder
E = Not eligible as determined by issuer
P = Pending confirmation by cardholder
R = Cardholder rejected
U = Whitelist status unknown, unavailable, or does not apply
cavv
String28
A cryptogram created by the issues that serve as a proof that the merchant is entitled for this authentication.
eci
String
This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed.
The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant.
Possible ECI data values are:
ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated
ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program
ECI = 7: payment authentication was not performed
Note: In this method eci is returned in response only in case its value is 1 or 6 or 7.

Apple Pay

Certificates

Below are the required actions to be completed in order to obtain the Apple Pay certificates from Apple:

Apple Pay Certification

  1. Log in to https://developer.apple.com/
  2. Click on the Certificates, IDs & Profiles option.
  3. From the newly opened screen select Merchant IDs and click on the (+) button.
  4. Select an ID and enter a short description.
  5. Once the ID is created, a confirmation screen appears. It is recommended that the merchant ensures that the entered data is valid.
  6. Click the Register button. If the registration is successful a screen showing ‘Registration complete’ appears.
  7. Click on the row with the newly created ID and choose the Edit button and the options to create Identity and Payment Processing Certificates are shown. On this page the process of adding/verifying domains can be started.


Creating a Payment Processing Certificate

  1. From the Edit screen of the Merchant IDs panel choose the Create Certificate button.
  2. Answer “No” to the question “Will payments associated with this Merchant ID be processed exclusively in China?” and click Continue and the next screen contains the instructions on how to create the CSR (and the accompanying it public and private keys), using the Keychain Access tool in the Mac OS.
  3. Launch the Keychain Access tool on the Apple device that you are using to create the certificates.
  4. From the drop-down menu in Keychain Access select Certificate Assistant and then Request a Certificate From a Certificate Authority… and the Certificate Assistant window appears.
  5. Enter the company information.
    Don’t forget to check the “Let me specify key pair information” check-box and select the “Saved to disk” radio button and then click Continue, and the certificate assistant now asks for the Key Pair information. Always follow the instructions shown on the Apple website! At the moment, the following type should be chosen: Key Size – 256 bits; Algorithm: ECC.
  6. Click Continue and Done on the next screen.
  7. Once the above steps are completed a certificate signing request (.csr) file is created. This is the file that needs to be uploaded to the Apple’s web page.
  8. From the Browse dialog choose the file by clicking on the Choose File… button and click Continue. If the certificate creation is successful, a screen appears allowing the signed .cer file to be downloaded. Click on the Download button and save the file to the disk.


  9. To install the certificate in your keychain, double-click the downloaded certificate file (with a .cer extension) and the certificate appears in the My Certificates category in the Keychain Access. The login keychain is the default if no other keychain was chosen.
  10. Right click on the imported certificate it then choose “Export “PAIR_NAME”” to export the signed pair. Select the “.p12” as type and save the file.





Creating Identity Certificate
The identity certificate is needed when merchants want to process Apple Pay payments that originate from within a web page instead of the SafeCharge Mobile SDK, since Apple needs to verify the ownership of the domain from which the payment is initialised. One identity certificate may be used to identify multiple domains.

  1. From Merchant IDs select the desired ID for creating the identity certificate. Choose the Create Certificate button found in the Merchant Identity Certificate box.
  2. The steps for creating and exporting the certificates are the same as for Payment Processing Certificates with the only difference being that the following type should be chosen: Key Size – 2048 bits; Algorithm: RSA.The exported “.p12” file must be sent to SafeCharge.

Adding Domains to the Apple Merchant ID
To use the “Apple Pay on the Web”, each of the domains from which the payment request is made should be verified. The verification is done by uploading a file on a specified location on the merchant’s website.

  1. Select the Add Domain button from the Merchant IDs screen and the Register Merchant Domain window appears.
    Note that, there are a few requirements to the server on which the domain runs (e.g. the merchant server must support the TLS 1.2 protocol and the pages must be served via https). More information can be found here: https://developer.apple.com/reference/applepayjs. The above link also contains complete guide on how to verify the domain.
  2. From the Register Merchant Domain window enter the desired domain to be verified and should press Continue.
  3. Download the file generated by Apple and upload it to the path shown in the screen. Once the file is uploaded the client must click on the Verify button. The uploaded file must be publicly accessible via https.


Dynamic Server to Server JS Button Solution

Apple Pay on the web enables consumers to access payment details that are stored in an e-wallet. If a consumer is using Safari on their iPhone or iPad, they are shown a model payment sheet, when they tap “Buy with Apple Pay” on a merchant’s site. If a consumer is using Safari on their Mac, and has an iOS device in range, the device prompts them to authorise the payment, which is sent to the browser.

Minimum Requirements

iOS device:
1. Safari running on iOS 10 or later.
2. A valid card in an e-wallet.

Mac device:
1. Safari running on macOS Sierra or later.
2. An iPhone (not an iPad, which is not supported by Safari) with a card in its e-wallet paired to the Mac with Handoff. Instructions can be found on Apple’s Support website.

Instructions

  1. Include CDN located SafeCharge provided Java Script file in your code.

For using it, always begin by including the library. Add a script tag to your page to get started.

COPIED
1
<script type="text/javascript" src=" https://cdn.safecharge.com/safecharge_resources/v1/sc_api_applepay.min.js"></script>


2. Create a button handler.

Merchant initialises the button handler. Once the button is clicked, the overlay appears.

It displays data and allows the user to enter data, for example: currency, amount and also line items to be shown to the user, billing address, shipping address etc. (per merchant decision).

This handler also calls a function defined in safecharge.js, which handles the session and fetches the decrypted data from the device.


3. Create a result handler.

Merchant must define the callback function that receives the authorised payment token (mobileToken), address optional fields and a completion function.

They are returned by the method defined in safecharge.js called by the button handler.


4. Passing information from frontend to backend.

Merchant to send the data gathered by the button handler to merchant server.


5. Call processing method with required information.

Merchant should POST received data to merchant’s server where paymentCC or dynamic3D are invoked with suitable externalTokenProvider request parameters values.

It is required to pass these additional parameters: externalTokenProvider=ApplePay, mobileToken=the encrypted data generated by Apple, gathered from the device before by a function defined in safecharge.js.

Note that currency and amount MUST match the ones stored in the mobileToken. The result is returned to the merchant server.


6. Passing information from backend to frontend.

The button handler calls the completion function received earlier to indicate whether the transaction succeeded (with parameter true) or failed (with parameter false).

This is in order to close the overlay in the appropriate manner so the user is informed regarding the transaction result.

Example Code

 


Static Server to Server JS Button Solution

Apple Pay on the web enables consumers to access payment details that are stored in an e-wallet. If a consumer is using Safari on their iPhone or iPad, they are shown a model payment sheet, when they tap “Buy with Apple Pay” on a merchant’s site. If a consumer is using Safari on their Mac, and has an iOS device in range, the device prompts them to authorise the payment, which is sent to the browser.

Minimum Requirements

iOS device:
1. Safari running on iOS 10 or later.
2. A valid card in an e-wallet.

Mac device:
1. Safari running on macOS Sierra or later.
2. An iPhone (not an iPad, which is not supported by Safari) with a card in its e-wallet paired to the Mac with Handoff. Instructions can be found on Apple’s Support website.

Instructions
1. Add code to validate Apple Pay compatibility on the site before the page loads.
(Here’s how: https://developer.apple.com/reference/applepayjs/applepaysession):



2. Add Apple Pay button to the payment page page.
(Here’s how: https://developer.apple.com/reference/applepayjs/applepaysession) and include the following attributes in the tag:

COPIED
1
<button id="apple-pay-button" trxStatus="[function_to_call_when_transaction_completes]">Pay</button>


3. Include the code shown below in the payment page (link to SafeCharge’s live/production environment:

COPIED
1
<script src="https://secure.safecharge.com/ppp/purchase.do?time_stamp=[time_stamp]&currency=[currency]&total_amount=[total_purchase_amount]&item_name_X=[X_digit_>0;_name_of_the_item]&item_amount_X=[X_digit_>0;_total_amount_to_pay_for_item_X]&item_quantity_X=[X_digit_>0;_number_of_item_X]&version=3.0.0&merchant_id=[your_merchant_ID]&merchant_site_id=[your_merchant_site_ID]&country=[country]&checksum=[calculated_checksum]&openState=js&payment_method=ppp_ApplePay"></script>


4. The JavaScript that is attached to the Apple Pay button and handles your transaction is returned.

Hosted Payment Page iFrame Solution using iOS SDK

This solution is relevant for a merchant which is integrated to SafeCharge hosted payment page using the iOS SDK, which allows the merchant to present the hosted payment page within the merchant iOS mobile application. The relevant parameter for Apple Pay is openState=sdk.
For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.

Hosted Payment Page iFrame Solution

This solution is relevant for a merchant which is integrated to SafeCharge hosted payment page while presenting it as an an iFrame in it’s own page.

The below must be implemented by the merchant.
For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
1. The merchant must include SafeCharge JS script on top of the merchant’s web site.
2. The merchant must include SafeCharge iFrame directly on the merchant’s web site (not nested in other iFrame).
3. The SafeCharge JS script https://cdn.safecharge.com/safecharge_resources/v1/sc_applepay.min.js must be included before SafeCharge iFrame is initiated.


HTML example:

COPIED
1
2
3
4
5
6
7
8
9
10
11
<head><script src="https://cdn.safecharge.com/safecharge_resourcse/v1/sc_applepay.min.js"></script>
</head>
<body><div>
        <iframe name="sc_frame" src="https://secure.safecharge.com/ppp/purchase.do..."> </iframe>
    </div></body>

Notifications (using DMN)

Handling DMNs

When a transaction request is sent to SafeCharge, SafeCharge communicates with the consumer’s bank to transfer the payment from the consumer’s account to the merchant’s account. Once SafeCharge receives a response from the bank, SafeCharge notifies the merchant of the transaction request via DMN.

DMNs are useful for determining when an error occurred on the consumer’s side by verifying that the SafeCharge server completed the transaction. Occasionally, there might be cases when the response coming through the Success or Error page is lost. When this occurs, the consumer is not aware of the transaction outcome. Since the DMN is received directly from SafeCharge, the merchant can contact the consumer to notify them of the status of the transaction.

Integrating DMNs

When integrating with SafeCharge’s DMN, the SafeCharge server executes an HTTPS request directly to the web server without passing through the consumer’s browser. To integrate with the DMN, merchants must supply SafeCharge with the IP address of the URL that leads to the callback entry point of the server. This is usually a small module/application, which constantly listens and waits for incoming HTTPS requests from SafeCharge’s server. When the SafeCharge server sends data via the DMN, SafeCharge executes an HTTPS GET or HTTPS POST request to the server URL provided and includes the relevant parameters in the HTTPS GET/HTTPS POST request.

For example, if the following URL is supplied to the DMN: http://myserver.com/SafeCharge/dmn/listen.do

The SafeCharge server calls back by using the HTTPS GET/HTTPS POST request to this URL. The request includes all relevant data for the HTTPS GET/HTTPS POST parameters. If using HTTP GET, the body remains empty. If HTTP POST was used, the parameters are sent in the body. If required to switch merchant configuration between HTTPS GET and HTTPS POST, need to contact SafeCharge’s integration team at integration@safecharge.com

For example, the SafeCharge server executes the following HTTPS GET/HTTPS POST request to the merchant’s server to send the response via the DMN channel:
http://myserver.com/SafeCharge/dmn/listen.to?ppp_status=OK&PPP_TransactionID=547&TransactionID=45402&userid=111&merchant_unique_id=234234unique_id&customData=342dssdee&productId=12345product_id&first_name=Diyan&last_name=Yordanov&email=dido%40domain.com&totalAmount=47.25&currency=USD&Status=APPROVED

SafeCharge sends DMNs from the following IP addresses:

Test: IP DMN server range is: 91.220.189.12–91.220.189.16 / 52.16.211.57, 52.17.110.204

Live: SafeCharge has several IP addresses for live DMN servers. A listener should be prepared to receive messages from the following IP addresses, in the event that one server is down: 194.247.167.32 / 87.120.10.184 - 87.120.10.187

When using the DMN, SafeCharge recommends that merchants use the merchant_unique_id parameter.
The merchant_unique_id parameter enables mapping between responses coming from DMN data.

In order to integrate DMN’s, provide SafeCharge with the IP and URL of the DMN listener in use. Also, create a DMN response checksum. (For more information; see “Authenticating a DMN Response Checksum” below.)

Receiving DMNs

In the event that the IP address of a DMN listener must be changed, merchants must notify SafeCharge in advance to avoid an interruption of the service. When the DMN notification is sent to a DMN listener, the SafeCharge server expects the merchant’s server to respond with Status code 200 – OK. After the DMN successfully sends a DMN notification, all transactions that were successfully sent in that notification are recorded in the SafeCharge database as Processed/Sent.

If a notification is not successfully sent, the SafeCharge database records the status of the transaction notification as In Retry, and the DMN attempts to resend the notification in every 15 minutes for 24 hours. If the DMN fails to send the notification in each retry attempt over a 24 hour period, the DMN ceases to attempt to resend the notification and records the status of the notification as Failed.

APMs and DMNs

After processing transactions with an APM, SafeCharge returns a DMN that includes the result of the transaction in the parameter status and the parameter payment_method, which identifies the payment method that the consumer selected.

There are three possible values of the status parameter:
1. Approved: The transaction was processed and approved by the APM processor.
2. Declined: The transaction was processed by the APM processor and declined.
3. Pending: The transaction is being processed by the APM processor.

Transactions are processed synchronously and asynchronously depending on the APM. When an APM processes the transaction asynchronously, the length of time that passes before the transaction is processed can range between several seconds to several days. Once the final result (Approve or Decline) is received from the APM processor, SafeCharge sends the merchant an additional DMN call containing the same transaction data as the previous DMN call, with the exception of the status parameter that is now updated and contains the final status of the transaction.

Authenticating a DMN Checksum

To authenticate a DMN callback, SafeCharge includes a checksum among the HTTPS parameters in the DMN. This checksum should be used to verify that the DMN callback was sent by SafeCharge. The checksum uses SHA256 encryption just as the checksum generated when sending HTTPS POST requests to SafeCharge’s server.

The HTTPS parameter containing the DMN checksum is named advanceResponseChecksum.

The advanceResponseChecksum checksum value is generated based on the merchant’s secret key and a few additional parameters, and must be verified by the merchant. A match between the sent value and the calculated value indicates that the DMN callback is authentic.

To Authenticate a DMN Response Checksum:

1. Concatenate the following parameters in the exact order as follows:
The merchant secret key followed by the parameters received from the DMN callback:
totalAmount, currency, responseTimeStamp (in GMT), ppp_TransactionID, Status, productId
(If this parameter was not sent to SafeCharge, then concatenate all item names instead; for example Testproduct1 and Testproduct2).

2. Use SHA256 encryption on the result string of the concatenation. Use encoding passed from the merchant site to create the SHA256 encryption. The default encoding is UTF-8 (unless the encoding input parameter specifies otherwise).
Once the DMN response is received from SafeCharge, compare the SHA256 result to the advanceResponseChecksum parameter in the DMN callback.

Example Of DMN Response Checksum:

Below is an example of a checksum generated when authenticating a DMN response checksum. If a checksum matches, then DMN callback is authentic.

The merchant is given:
Secret Key: AJHFH9349JASFJHADJ9834
totalAmount: 115
currency: USD
responseTimeStamp: 2016-11-13.13:22:34
ppp_TransactionID: 3453459
Status: APPROVED
productId: Your Product

After concatenation you have the following string: AJHFH9349JASFJHADJ9834115USD2016-11-13.13:22:343453459APPROVEDYour Product

The calculated checksum is: 6501f10efbfc9599d3e79fc0e24a5662e60292b0025834d0e2d09c58945aedbb

Note that, space characters might appear in the returned string as plus characters. For example the string appears as: AJHFH9349JASFJHADJ9834115USD2016-11-13.13:22:343453459APPROVEDYour+Product and its matching checksum is then: 8b7033116c2868405c8efbf23bf0c112f10fccce81ec241dea583a0b26950d3e

DMN Parameters

The following table contains a list of Deposit DMN parameters that SafeCharge sends to the merchant server.

PARAMETER MANDATORY DESCRIPTION
ppp_status
Yes
The status of the transaction. OK indicates that the transaction was approved. Pending occurs only for APM transactions when the final status is not immediately returned. FAIL indicates that the transaction was declined or there was an error.
PPP_TransactionID
Yes
A unique 64 bit number that identifies the SafeCharge payment page transaction.
totalAmount
Yes
Total amount of items contained in the consumer’s purchase sent to the payment page. For merchants with the currency conversion feature enabled, the value of this parameter is the original total amount of items before the currency is converted.
currency
Yes
The currency, as selected by the consumer, that was sent. For merchants with currency conversion enabled, the value of this parameter is the original currency that was sent to the payment page.
convertedCurrency
No
The final currency, as selected by the consumer, in which the transaction was processed through the acquirer bank. This feature is only available for merchants with currency conversion enabled.
convertedAmount
No
The final amount of the transaction after the consumer converted the currency. This is the amount that was processed through the acquirer bank. This feature is only available for merchants with currency conversion enabled.
responsechecksum
Yes
Deprecated checksum parameter.
advanceResponseChecksum
Yes
Advanced response checksum that ensures that the DMN callback is authentic.
transactionID
No
A unique 64 bit number that identifies the fiscal transaction in the SafeCharge payment gateway. If no fiscal transaction actually occurred, then the ppp_status is FAIL and this parameter is left empty.
transactionType
No
The type of transaction; Sale, Auth, Settle, Credit or Void . This service is only available upon request.
Status
No
Status of the SafeCharge Payment Gateway fiscal transaction; Approved, Success, Declined, Error, Pending. If no fiscal transaction actually occurred, the ppp_status is FAIL and this parameter is left empty.
userPaymentOptionId
No
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
No
The transaction ID of the transaction in the event that an external service is used.
userid
No
The value that was initially passed as the userid parameter when making the HTTPS POST request to the payment page.
customData
No
The ID that was initially passed as the customData parameter during the first request.
productId
No
The ID that was initially passed as the productId parameter during the first request.
first_name
No
First name of the user processing the transaction, if provided.
last_name
No
Last name of the user processing the transaction, if provided.
email
No
Email of the user processing the transaction, if provided.
externalEmail
No
For PayPal only. The registered email address that is returned from the PayPal account.
cardCompany
No
The name of the credit card company. The possible values are Visa, Amex, MasterCard, Diners, Diners, Discover, JCB, LaserCard, Maestro, Solo, and Switch. This value is provided when the value of the payment_method parameter is cc_card or dc_card.
customFieldX
No
Fifteen custom fields that may be used by replacing X with 1 to 15. The customFieldX that was initially passed as the customFieldX parameter during the first request.
invoice_id
No
The invoice_id that that was initially passed as the invoice_id parameter during the first request.
address1
No
Street address of the user processing the transaction, if supplied.
address2
No
Street address of the user processing the transaction, if supplied.
country
No
The country of the user processing the transaction, if supplied.
state
No
State of the user processing the transaction, if supplied.
city
No
City of the user processing the transaction, if supplied.
zip
No
ZIP of the user processing the transaction, if supplied.
phone1
No
Phone number of the user processing the transaction, if supplied.
Phone2
No
Alternate phone number of the user processing the transaction, if supplied.
Phone3
No
Alternate phone number of the user processing the transaction, if supplied.
nameOnCard
No
Name on card used to process the transaction, if supplied.
cardNumber
No
The masked card number used to process the, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
expMonth
No
Expiration month of the card used to process the transaction, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
expYear
No
Expiration year of the card used to process the transaction, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
Token
No
Tokens are strings of random digits, letters, and symbols characters that represent a single credit card number. When a merchant submits their consumers’ full credit card number, SafeCharge provides a token in the response representing the consumers’ credit cards.
tokenId
No
Deprecated ID of the token. Used in combination with the token.
orderTransactionId
No
This value helps to identify individual transactions that are related to the same orderID.
3dflow
No
This parameter indicates whether the transaction was processed through the 3D Secure flow or not. 0=Not processed through 3D Secure. 1=Processed through 3D Secure.
promoCode
No
This value is a promotional code to apply discounts to products or services. SafeCharge does not apply any discounts and only returns the value sent in the HTTPS request.
ExErrCode
No
Error indication. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the specific error.
ErrCode
No
When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
errApmCode
No
The error code returned from an APM.
errApmDescription
No
The error description returned from an APM.
errScCode
No
The error code returned by SafeCharge for an APM transaction.
errScDescription
No
The error description returned by SafeCharge for an APM transaction.
AuthCode
No
Authorization code, up to 35 characters, returned for each approved and pending transaction.
acquirerId
No
The acquiring bank’s unique ID. The value 0 represents an invalid bank code.
bin
No
The first six digits from the credit card number used for identifying the processing bank.
shippingCountry
No
Shipping country of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingState
No
Shipping state of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingCity
No
Shipping city of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingAddress
No
Shipping address of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingZip
No
Shipping ZIP code of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingFirstName
No
Shipping first name of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingLastName
No
Shipping last name of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingPhone
No
Shipping phone of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingCell
No
Shipping mobile phone of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingMail
No
Shipping email of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
Total_discount
No
The sum of the values in the item_discount_X parameter.
total_handling
No
The handling parameter that the merchant passed to SafeCharge in the HTTPS POST request.
total_shipping
No
The shipping parameter that the merchant initially passed as the shipping parameter during the first request.
total_tax
No
The total tax parameter that that the merchant initially passed during the first request.
buyButtonProductBundleId
No
Contains the ID of the product bundle when the buy button payment is processed.
merchant_site_id
Yes
The ID, provided by SafeCharge, which uniquely defines a particular merchant customization.
requestVersion
Yes
The version of the request.
message
Yes
A message from SafeCharge about the transaction that has been completed.
merchantLocale
No
The language of the payment page. The possible values of this parameter is provided below: English(US): en_US / English(UK): en_UK / German: de_DE / Chinese(PRC): zh_CN / Hebrew: iw_IL / French: fr_FR / Dutch(Standard): nl_NL / Greek: el_GR / Indonesia: in_ID / Italian: it_IT / Japanese: ja_JP / Korean: ko_KR / Lithuanian: lt_LT / Spanish: es_ES / English(Canada): en_CA / English(Australia): en_AU / Russian: ru_RU / Arabic: ar_AA / Norwegian: no_No/ Portuguese: pt_BR / Swedish: sv_SE / Turkish: tr_TR / Slovenian: sl_SI / Danish: da_DK / Romanian: ro_RO / Bulgarian: bg_BG / Polish: pl_PL / Hungarian: hu_HU / Vietnamese: vi_VL
unknownParameters
No
When an unknown parameter is sent to SafeCharge, i.e. a misspelled parameter, SafeCharge returns this parameter whose value is the unknown parameter. This enables the merchant to identify and correct any erroneous parameters.
payment_method
Yes
The payment method used for this transaction such as cc_card, dc_card, giro, etc. For a complete list, see the NAME IN SAFECHARGE column in the APM Account Identifiers table.
ID
No
Hebrew ID.
merchant_id
Yes
The unique merchant ID supplied by SafeCharge.
responseTimeStamp
Yes
The time set by SafeCharge (in GMT) that the response is received from the Gateway in the format YYYY-MM-DD.HH:MM:SS for example: 2019-01-10.15.38.40
buyButtonProductId
No
Contains the ID of the product when the ‘buy button payment’ was processed.
dynamicDescriptor
Yes
Dynamic descriptor passed to the SafeCharge gateway for the current transaction.
Reason
No
The reason that the Gateway request was returned if the transaction fails. See Gateway specification. N/A is returned if it is not a regular transaction.
ReasonCode
No
The reason code that the Gateway request was returned if the transaction fails. See Gateway specification. N/A is returned if it is not a regular transaction.
item_name_X
Yes
The item name that was passed as the item_name_X parameter when making the initial request to the Public Payment Page. N/A is displayed if it is not a regular transaction.
item_number_X
No
The item number that was passed as the item_number_X parameter when making the initial request. N/A is displayed if it is not a regular transaction.
item_amount_X
Yes
The item amount that was passed as the item_amount_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_quantity_X
No
The item quantity that was passed as the item_quantity_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_discount_X
No
The item discount that was passed as the item_discount_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_handling_X
No
The item handling that was passed as the item_handling_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_shipping_X
No
The item shipping that was passed as the item_shipping_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
appliedPromotions
No
Indicates that the purchase was completed using a promotion or coupon. This parameter contacts all successfully applied promotion codes. If more than one promotion was used, the promotion names are separated by a # character.
client_ip
Yes
The IP address from which the client made the purchase.
uniqueCC
No
A unique value assigned to the credit card number.
user_token_id
No
This is a unique identifier for each consumer generated by the merchant.
ExternalAccountID
No
This is the consumer’s username or unique identifier provided by the APM. This value is not returned for all APMs.
APMReferenceID
No
This is SafeCharge’s reference identifier for each APM.
webMasterId
No
The webMasterID passed in the request.
finalFraudDecision
No
This parameter indicates the final fraud analysis decision made by SafeCharge Risk Management. Possible values are Accept; The transaction is redirected for processing, Reject; The transaction is rejected due to a Fraud Filter.
SystemID
No
The value of this parameter is a numeric identifier generated by SafeCharge for the fraud analysis service/tool.
SystemName
No
The value of this parameter is an internal SafeCharge name for the fraud analysis service/tool.
SystemDecision
No
The Risk decision. It may be one of the following predefined string values:- None No decision was rendered. - Accept Transaction is recommended for processing. - Reject Transaction is rejected due to a high probability of fraud. - Review Transaction should be manually reviewed before processing. - Error An error has occurred during the analysis and no decision is rendered.
Rules
No
This parameter lists all the rules that were activated by the transaction as part of SafeCharge’s fraud checks. This parameter is only returned when the value of the SystemDecision parameter is Reject or Review. The format of the value of the Rules parameter is URL encoded. For example: rules=ID%3D1000000260%2CDescription%3DCC+is+changing+more+than+1+Email+Last+24+H+Review+general / In the URL encoded response: %2C represents & and separates the multiple rule values while %3D represents ’=’.
CVV2Reply
No
CVV2 (card verification value) response. Possible values:
M = CVV2 Match
N = CVV2 No Match
P = Not Processed
U = Issuer is not certified and/or has not provided Visa the encryption keys.
S = CVV2 processor is unavailable.
AVSCode
No
The AVS (address verification) response. The following values may be returned:
A = The street address matches, the ZIP code does not.
W = Whole 9-digits ZIP code match, the street address does not.
Y = Both the 5-digits ZIP code and the street address match.
X = An exact match of both the 9-digits ZIP code and the street address.
Z = Only the 5-digits ZIP code match, the street code does not.
U = Issuer Unavailable
S = Not Supported
R = Retry
B = Not Authorized (declined)
N = Both street address and ZIP code do not match.
cardType
No
The type of card used in the transaction. Possible values; ‘credit’ or ‘debit’.
upoRegistrationDate
No
The date that the UPO was registered in the following format: YYYMMDDHHmmss
isPartialApproval
No
Indicate if the transaction was requested for partial approval (1) or not (0).
requestedAmount
No
In case of partial approval transaction, represent the amount requested. It can be greater than the amount that was able to be processed (totalAmount).
requestedCurrency
No
In case of partial approval transaction, represent the currency of the amount requested. It should be the same as the currency of the amount processed (currency).
isRebilling
No
Indicates whether this is a regular transaction or a recurring/re-billing transaction. Possible values: 0 - this is a regular transaction. 1 - this is a recurring/re-billing transaction.
autoSettleMode
No
Automatic settle feature available for merchants working in an Auth-Settle mode. Possible values: TIME – automatic settle done after a specific time frame after Auth, RISK – automatic settle done per “Accept” risk decision, RISK-TIME - combination of both time and risk options described before. If automatic settle not performed then parameter returns empty.
isExternalMpi
No
Allow the merchant to provide the 3D Secure authentication result in the request to SafeCharge. Possible values: 1 - external MPI is used. 0 - external MPI is not used.
cavv
No
The card holder authentication verification value. Relevant for external MPI.
xid
No
The transaction identification value. Relevant for external MPI.
eci
No
The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated; ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program; ECI = 7: payment authentication was not performed.
type
No
The type of the notification. Possible values: DEPOSIT, WITHDRAWAL, KYC, or DOCUP.
KYC and DOCUP are only relevant for merchants implementing SafeCharge’s KYC solutions.
clientRequestId
No
ID of the API request in merchant’s system. This value must be unique. Can be used in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
relatedTransactionId
No
The ID of the related transaction used in case it was required for processing.
merchant_unique_id
No
If transaction sent through SafeCharge payment page, this parameter is populated by the ID of the transaction in the merchant’s system.
clientUniqueId
No
If transaction sent through SafeCharge API, this parameter is populated by the ID of the transaction in the merchant’s system.
externalTokenProvider
No
External token provider is a type of entity in the payment industry with its own flow (for example: Visa Checkout, Apple Pay). This indicates which external token provider was used in current transaction.
isDecrypeService
No
External token provider is a type of entity in the payment industry with its own flow(for example: Visa Checkout). This indicates whether the payments gateway decrypted the external token data provided, which was required for processing.

Errors and Declines

Status and Error Indications

The payment process consists of three stages:

Stage 1: The API itself (status/error parameters: status, errCode, reason).

Stage 2: The payment gateway and banks in the event of a credit card transaction (status/error parameters: transactionStatus, gwErrorCode, gwErrorReason, gwExtendedErrorCode).

Stage 3: The APM in the event of alternative payment methods transaction (status/error parameters: paymentMethodErrorCode, paymentMethodErrorReason).

In each one of these stages, errors can occur. All of these parameters are returned to provide merchants with the information arriving from all stages.

API Response Codes

ERRCODE REASON
1000
General Error
1001
Invalid checksum
1004
Missing or invalid CardData data
1007
Invalid name on card
1010
Invalid user token
1011
Missing or invalid UserPaymentOption data
1013
Invalid merchant Id.
1014
{0}Invalid country code.
1019
Validation Error
1021
Invalid timestamp
1022
Invalid merchant site id
1023
User payment option is not enabled
1024
UPO limit per user exceeded
1028
Invalid card issuer
1029
Invalid expired date
1038
Communication error
1040
Invalid or missing amount
1041
Invalid or missing amount currency
1055
Single UPO validation failed
1056
User management is off
1057
Invalid order id
1058
Requested operation can not be performed on this order
1059
Ambiguous payment data
1060
Missing or invalid payment data
1061
Invalid card token
1062
Invalid cvv
1063
Total amount does not match items amount sum
1064
Invalid session token. There can be only one order per session token.
1065
Invalid token
1066
Invalid request
1067
Invalid or missing transaction type
1068
Payment method is not enabled
1069
Session expired
1070
The currency is not supported by the merchant payment option settings
1071
Invalid request amount. The amount of the payment3D request is unequal to the amount of the Auth3D order.
1072
Missing or Invalid PA Response.
1073
Invalid Order Currency. The currency of the payment 3D request and the currency of the Auth3D order are different.
1074
The user payment option is expired.
1075
Invalid language code.
1076
Unsupported payment method
1077
API rebilling is disabled
1078
Missing user payment option config
1079
Rebilling is only allowed with user payment option.
1080
Invocation of this method is forbidden
1081
IP Address is blocked
1082
Invalid value of relatedTransactionId
1083
ekycUserDetails: The date of birth is invalid
1084
UserDetails: The date of birth is invalid
1085
Invalid request parametter value. The value of isPartialApproval should be empty or equal to 0 or 1
1086
Sending of cardData block is not allowed.
1087
Invalid request xss content
1088
Invalid clientRequestId. It should be provided when api setting is set to check it for uniqueness.
1089
There is another transaction with this clientRequestId.
1091
The transaction was processed by another merchant or merchant site.
1092
The transaction does not support the requested operation
1093
Missing message text!
1094
Invalid message locale!
1095
Invalid results range
1096
Unknown status
1097
Invalid value of account info field {0} in request.
1098
Missing account info field {0} in request.
1099
Payment method already registered!
1101
{0}Invalid state.
1102
No such product descriptor
1103
The subscription plan id is invalid
1104
Temporary card token is forbiden for this method.
1105
UserDetails: firstname, lastname, email, address, zip and country are mandatory
1107
Invalid methodCode
1108
Invalid casino
1109
Invalid email
1110
Invalid locale code
1111
External Error. Error received from IMS. IMS error message: {0}.
1112
Registration failed
1113
{0}The state is not from the country
1114
Invalid verification status
1115
Invalid verification method
1116
Payment account details not found by IMS.
1117
Invalid dynamic3DMode. The allowed values are: (off, on).
1118
Invalid isDynamic3D. The allowed values are: (0, 1).
1120
ekycUserDetails: invalid identificationType
1121
Merchant not verified.
1122
Merchant site disabled.
1123
Invalid items count with open amount
1124
Merchant site is not configured to execute Managed3D transaction.
1125
UPO Payment method is not supported by this method.
1126
When using rebilling, isDynamic3D must be equal to 1 and dynamic3DMode must be OFF.
1127
When using externalMPI, isDynamic3D must be equal to 1 and dynamic3DMode must be OFF.
1128
Invalid type: {0}.
1129
KYC Document Upload disabled.
1130
Country could not be extracted from the request.
1131
The originUrl = [{0}] is not valid!
1132
The transaction has been already automatically settled.



Gateway Response Codes

This table contains the error response codes sent in response and DMNs along with their descriptions.
The first three rows consist of the mapping of the error codes (gwErrCode, gwExtendedErrCode) to the corresponding response status field (transactionStatus).

ERRORCODE EXERRCODE DESCRIPTION
0
0
APPROVED
-1
0
DECLINED (Refer to the Decline Reasons below)
0
0
PENDING
-1100
greater than 0
ERROR (Filter error, Please refer to Filter Error Codes below)
<0
!=0
ERROR (Gateway/Bank Error)
-1001
0
Invalid Login
-1005
0
IP out of range
-1203
0
Timeout/Retry



Gateway Filter Error Codes

This table contains the possible filter codes (gwExtendedErrCode) and their descriptions. ErrCode (gwErrCode) for all filter errors is -1100.
Contact tech-support for more information.

EXERRCODE DESCRIPTION
001
Invalid expiration date.
1002
Expiration date has already passed.
1101
Invalid card number (alpha numeric).
1102
Invalid card number (length).
1103
Invalid card number (MOD 10).
1104
Invalid CVV2.
1105
Auth Code/Trans ID/Credit card number mismatch.
1106
Credit amount exceeds total charges.
1107
Cannot credit this credit card company.
1108
Invalid interval between authorization and settle.
1109
Unable to process this credit card company.
1110
Unrecognized credit card company.
1111
This transaction was charged back.
1112
Sale/Settle was already credited.
1113
Terminal is not ready for this credit card company.
1114
Black listed card number.
1115
Illegal BIN number.
1116
Custom Fraud Screen Filter.
1118
‘N’ cannot be a Positive CVV2 reply.
1119
‘B’/’N’ cannot be a Positive AVS reply.
1120
Invalid AVS.
1121
CVV2 check is not allowed in Credit/Settle/Void.
1122
AVS check is not allowed in Credit/Settle/Void.
1124
Credits total amount exceeds restriction.
1125
Format error.
1126
Credit amount exceeds limit.
1127
Limit exceeding amount.
1128
Invalid transaction type code.
1129
General filter error.
1130
The bank’s required fields are blank or incorrect.
1131
This transaction type is not allowed for this bank.
1132
Amount exceeds bank limit.
1133
Gateway required fields are missing.
1134
AVS processor error.
1135
Only one credit per sale is allowed.
1136
Mandatory fields are missing.
1137
Credit count exceeded credit card company restriction.
1138
Invalid credit type.
1139
This card is not supported in the CFT Program.

Gateway Decline Reasons

This table contains the possible decline reasons received in the decline reason (gwErrorReason).

ERRCODE EXERRCODE DECLINE REASON DESCRIPTION
-1
0
Call issuer
Refers to the issuer. It is possible that such transactions could be authorised with voice AuthCode.
-1
0
Invalid merchant
General decline message. Typically, this does not indicate any general issue with the merchant or MID. This decline reason is usually the result of an issue regarding an internal standard.
-1
0
Pick-up card
This is a general decline message from the issuer indicating that the consumer should retrieve the card. This message may be received when the card is reported as lost/stolen.
-1
0
Do not honor
The most common and general issuer decline code. This code is generated by the issuer when no specific decline reason/code is returned.
-1
0
External Error in Processing
This is a general error message. When receiving this error, the transaction may succeed when trying again later.
-1
0
Pick up card, special condition (fraud account)
This is a general decline message from the issuer indicating that the consumer should retrieve the card. This message may be received when the card is reported as lost/stolen.
-1
0
Invalid transaction
The most common and general issuer decline code. This code is generated by the issuer when no specific decline reason/code is returned.
-1
0
Invalid amount
This decline code is the result of an issue with the transaction amount. This code may be triggered as a result of the currency or financial reasons such as insufficient funds.
-1
0
Invalid card number
The transaction could not be processed with the provided credit card number. This may indicate that the card number does not exist.
-1
0
No such issuer
This decline code indicates that there is a problem with the credit card number, for example, the credit card BIN doesn’t match the range of any issuer in the acquirer’s list.
-1
0
Unable to locate record in file
The transaction failed due to a technical issue. When receiving this error, the transaction may succeed when trying again later.
-1
0
File temporarily not available
The transaction failed due to a technical issue. When receiving this error, the transaction may succeed when trying again later.
-1
0
Format error
For MasterCard or Maestro Card, this decline code may be the result of an invalid CVV number or a CVV number that could not be verified. This decline code may also be generated as the result of a 3D Secure-related issue, for example, the issuer requires transactions to be 3D secured and the transaction was processed through a non-3D Secure account.
-1
0
No credit account
This usually indicates that there is an issue with the account connected to the credit card, for example, the account is expired, canceled, or does not exist.
-1
0
Lost card, pick-up
This decline code is returned when the card is listed as lost on the issuer’s side.
-1
0
Stolen card, pick-up
This decline code is returned when the card is listed as stolen on the issuer’s side.
-1
0
Insufficient Funds
The credit card holder lacks sufficient funds to complete the transaction.
-1
0
No checking account
This usually indicates that there is an issue with the account connected to the credit card, for example, the account is expired, canceled, or does not exist.
-1
0
No savings account
This usually indicates that there is an issue with the account connected to the credit card, for example, the account is expired, canceled, or does not exist.
-1
0
Expired card
The credit card is no longer valid or was canceled. It is also possible that the expiration date does not match the card details.
-1
0
Incorrect PIN
This decline code is similar to other PIN-based declines, and may indicate that the card is being blocked due to a security issue, such as exceeding the limit of PIN entry attempts at a point of sale.
-1
0
Transaction not permitted to cardholder
The issuer did not allow this transaction against this card based on internal reasons, such as the transaction originated from a specifically restricted industry or country.
-1
0
Transaction not permitted on terminal
The issuer rejected the transaction based on its technical origin or requester. When this error reoccurs, it may indicate that there is a technical issue on the acquirer’s side.
-1
0
Suspected fraud
The transaction is suspected to be fraudulent.
-1
0
Exceeds withdrawal limit
The transaction amount exceeds the permitted amount for this card or account.
-1
0
Restricted card
The card is marked as restricted on the issuer’s systems.
-1
0
Error in decryption of PIN block
The decline code is the result of a security violation and may indicate that the card has been restricted.
-1
0
Exceeds withdrawal frequency
The transaction amount or count exceeds the permitted frequency for this card or account.
-1
0
Invalid transaction; contact card issuer
A general decline message likely indicating that the transaction was rejected for financial reasons, as well as the issuer’s internal standards.
-1
0
PIN not changed
The transaction was declined as a result of the PIN code.
-1
0
PIN tries exceeded
The card was blocked on the issuer’s system due to an excessive amount of PIN entry attempts at the point of sale. This decline code may be returned during an online transaction even though the PIN is not entered for online transactions. This message may be received when a card was blocked following a card-present transaction.
-1
0
Invalid “To” account specified
This decline code is also known as ‘Unsolicited Reversal’, and might mean that the ‘to’ [debit] account does not exist, is not connected to the card, or card was restricted.
-1
0
Invalid “From” account specified
The ‘from’ [credit] account does not exist.
-1
0
Invalid account specified
This indicates that there is an issue with the account associated to the credit card number, for example, the number does not exist or is invalid.
-1
0
System not available
This indicates that there was a technical issue preventing the completion of this transaction.
-1
0
Cryptographic error found in PIN
This decline code is similar to other PIN-based declines, and may indicate that that the card is being blocked due to a security issue, such as exceeding the limit of PIN entry attempts at a point of sale.
-1
0
Cannot verify PIN
The transaction was declined as a result of the PIN code.
-1
0
PIN unacceptable. Retry.
The transaction was declined as a result of an unacceptable PIN code.
-1
0
Issuer or switch inoperative
The acquirer was unable to complete the transaction on the issuer’s side, for example, as a result of a timeout.
-1
0
Routing error
This indicates that the transaction request could not reach the authorizing destination (scheme/issuer). This may indicate that the credit card type is not processed by the acquirer.
-1
0
Transaction cannot be completed
The issuer could not complete the authorization of this transaction. If this occurs again, the cardholder should try contacting the issuer.
-1
0
Duplicate transaction
Indicates that a transaction was sent twice.
-1
0
Timeout/Retry
A timeout occurred between the acquirer and the issuer.
-1
0
Invalid CVV2
The transaction was rejected as a result of the CVV2 and usually indicates that CVV2 provided does not match the credit card number. This code is relevant for Visa only.
-1
0
Revocation of Authorization Order
This decline code may indicate that the cardholder requested to discontinue recurring transactions.
-1
0
Revocation of All Authorizations Order
This decline code may indicate that the cardholder requested to discontinue recurring transactions.

Testing

Overview

Before taking your integration live, you’ll need to test it thoroughly in SafeCharge’s integration environment.
Run the requests to see that you are sending them correctly and receiving your expected responses and DMNs.

Test Card Numbers

While testing, it is required to use the test cards.
These cards are only valid on SafeCharge’s integration environment and don’t involve any actual transfer of funds.
The test card numbers do NOT work on SafeCharge’s production environment.

Valid Test Cards

Visa MasterCard AMEX/Diners
4000020951595032 (US)
4000022756305864 (US)
4000023104662535
4000027891380961
5333300989521936
5333302221254276
2221008123677736
2221004483162815
375510513169537
375510288656924
375510379996452
375510082116984



Invalid Test Cards

Decline Reason Visa MasterCard AMEX/Diners Decline Message Returned
Decline
4000319872807223 (UK)
4001152882620768 (UK)
5333418445863914 (Russian Federation)
5001638548736201 (UK)
375521501910816
Please try again or contact issuer.
External Error in Processing
4000128449498204 (US)
2421005222147551
5333423768173347 (US)
5100976565928800 (UK)
375522679892992
3D error. Please try again.
Acquirer Validation
4000135814550378 (US)
4002992849179815 (UK)
5333435197139699 (US)
2321003321743868
375523500980436
Please try again or contact tech-support.
Lost/Stolen
4000157454627969 (US)
4006263458925039 (UK)
5333452804487502 (US)
5101118611779692 (UK)
375525991062202
Please contact tech-support.
Do Not Honor
4000164166749263 (India)
4008370896662369 (UK)
5333463046218753 (US)
2521003720448414
375526064276158 (Germany)
Issuer declined your payment. Please try again or contact issuer.
Insufficient Funds
4000173946194872 (India)
4008384424370890 (UK)
5333475572200849 (US)
2621004207038727
375527639875136 (Ireland)
Insufficient funds. Please try a lower amount.
Exceeds Withdrawal Limit
4000189336416410 (India)
4008393407151342 (UK)
5333482348715142 (US)
5101816227444177 (UK)
375528929838107 (Ireland)
Issuer declined your payment. Please contact issuer.
Extends Withdrawal Frequency
4000196948974975 (India)
4008440870955798 (UK)
5333498929343773 (South Korea)
5101825328239980 (UK)
375529856696120 (Ireland)
Issuer declined your payment. Please contact issuer.
Invalid Transaction
4000203016321921 (US)
4008802936968463 (UK)
5333502383316074 (Puerto Rico)
5102142055892794 (UK)
375530796593260
Please try again or contact support.
Format Error
4000212384978055 (US)
4013174568112171 (UK)
5333518577223892 (US)
5104144116585811 (UK)
375531494255517 (Indonesia)
Please try again or contact support.
Issuer or Switch Inoperative
4000229544877670 (US)
4013431659421782 (UK)
5333527145351713 (Costa Rica)
5105096854968022 (UK)
375532604034750
Issuer inoperative. Please try again or contact support.
Timeout/Retry
4000234977370839 (US)
4013448790173098 (UK)
5333532915594096 (US)
5114352303130899 (UK)
375533558061005 (Greece)
Please try again.
Expired Card
4000247422310226 (US)
4016403454164542 (UK)
5333540337444022 (US)
5116554857721084 (UK)
375534876707683 (Greece)
Expired card. Please check expiration date.
Transaction Not Permitted To Cardholder
4000254588011960 (US)
4018402405178583 (UK)
5333554636535091 (US)
2720988042111675
375535264614027 (Greece)
Issuer declined your payment. Please contact issuer.
Transaction Not Permitted on Terminal
4000269084739575 (US)
4018415418260230 (UK)
5333562868563707 (US)
5116819173651897 (UK)
375536629108788 (Greece)
Issuer declined your payment. Please contact issuer.
Restricted Card
4000273652260030 (US)
4018445028360724 (UK)
5333578626428553 (US)
5116828963987577 (UK)
375537795464104 (Greece)
Issuer declined your payment. Please contact issuer.

For the complete list of test cards, please contact SafeCharge’s integration team at integration@safecharge.com

Test APM Credentials

The table below contains alternative payment (APM) credentials that you can use during testing.
These credentials are only valid on SafeCharge’s integration environment and don’t involve any actual transfer of funds.
The test credentials do NOT work on SafeCharge’s production environment.

Payment Method Name User/Account Password
PayPal
ralphv3@safecharge.com
pz31W9f8w1
PayPal
Ralphv5@safecharge.com
d4V5Q8eD68
Neteller
451323763077
315508
Neteller
454651018446
270955
PaySafeCard
0000 0000 0990 3207
N/A
Sofort
12345678
PIN 123, TAN 12345
Sepa
IBAN: DE86120300001019407863
BIC: BYLADEM1001
Sepa Payouts
IBAN: DE07444488880123456789
N/A

Ideal, Neosurf, and WebMoney APMs do not require credentials to generate emulator responses.

Authentication

/getSessionToken

This method receives a merchant request and returns a unique session token. The unique token is created upon the initial successful authorization and represents the client session. It also contains an expiration date, as well as information about user granted privileges. For subsequent calls to the session, the token must be provided for validation to ensure that it is still active and valid.




Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getSessionToken.do
Example Request
COPIED
1
2
3
4
5
6
7
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "timeStamp": "20170118191622",
    "checksum": "58fc84fe0fccf3be3f77278884a868d5b26cd35d3a27a80e30603a65ff5ddd17"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp
String
(14)
Yes
The local time when the method call is performed in the following format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
(36)
The returned session identifier returned. To be used as an input.
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
clientRequestId
String
(20)
ID of the API request in merchant’s system.
internalRequestId
String
(20)
SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS, ERROR.
errCode
String
(11)
The error code in the event of an error.
reason
String
(400)
The error reason in the event of an error (i.e. failure in checksum validation, timeout from processing engine, etc.).
version
String
(10)
The current version of the merchant request. Current version is 1.

Processing Methods

Tokenization Methods

SafeCharge Fields

This guide walks you through the implementation steps you need to follow to develop your payment web page. This is basically a JavaScript code that:
- Initialises SafeCharge Web SDK and the Fields objects.
- Plants the payment SafeCharge Fields in your payment form for secure collection.
- Stylizes the SafeCharge Fields, using style classes with your own look and feel.
- Collects the card holder information - Submits the card information for tokenization.


Once submitted for tokenization using the getToken() method, a token (ccTempToken) is retrieved. You pass the token to your server-side to be used for processing using our API.  

Simple Card Integration

  1. Import the safecharge.js library.

COPIED
1
<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>


2. Create a simple container for your form.

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
    <form action="/charge" method="post" id="payment-form">
                <div class="form-row">
                        <label for="card-field-placeholder">
                            Credit or debit card
                        </label>
                        <div id="card-field-placeholder" class="some initial css-classes">
                        <!-- SFC Card widget will be inserted here. -->
                        </div>
                        <!-- Used to display form errors. -->
                        <div id="scard-errors" role="alert"></div>
                </div>
                <button>Submit Payment</button>
    </form>


3. Customise by defining classes for sizes and states. SafeCharge Fields implements these classes and you can stylize the fields by setting these classes.

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
        .SfcFields {
            background-color: #feff8c;
            height: 42px;
            padding: 10px 12px;
            border-radius: 4px;
            border: 1px solid transparent;
            box-shadow: 0 1px 3px 0 #e6ebf1;
            -webkit-transition: box-shadow 150ms ease;
            transition: box-shadow 150ms ease;
        }

        .sfc-empty {
            background-color: #fecd58 !important;
        }
        .sfc-empty.sfc-focus  {
            box-shadow: 0 1px 3px 0 #cfd7df;
            background-color: #fe8423 !important;
        }
        .sfc-focus {
            box-shadow: 0 1px 3px 0 #cfd7df;
            background-color: #feb1c7 !important;
        }

        .sfc-complete {
            background-color: #34fa29 !important;
        }

        .sfc-invalid {
            border-color: #fa755a;
        }

        .SfcFields--webkit-autofill {
            background-color: #fefde5 !important;
        }


4. Instantiate the Safecharge Web SDK that hosts SafeCharge Fields.

COPIED
1
2
3
4
5
    var sfc = SafeCharge({
        sessionToken : '09f29859-caf0-4cf7-abba-69e1bc81c6e4', // sessionToken generated by your server
        env: 'prod', // the environment you’re running  on
        merchantSiteId : 152358 // your merchantsite id provided by Safecharge
    });


5. Instantiate SafeCharge Fields.

COPIED
1
2
3
4
5
6
    var ScFields = sfc.fields({
        fonts: [
                { cssUrl: 'https://fonts.googleapis.com/css?family=Source+Code+Pro' }, // include your custom fonts
        ],
        locale: 'de'// you can set your users preferred locale, if not provided we will try to autodetect
    })


6. You can create custom styles for the fields and their states.


7. Create a card field and attach to the DOM.

COPIED
1
2
    var scard = ScFields.create('card', {style: style});
    scard.attach(document.getElementById('card-field-placeholder'));


8. Send the card to be tokenized by SafeCharge using the getToken method.
In return you get a result containing the paymentOption structure that contains the ccTempToken required for the server-side call to the dynamic3D API method.

COPIED
1
2
3
4
5
6
7
8
9
    sfc.getToken(scard).then(function(result) {
        // Stop progress animation!
        if (result.status === 'SUCCESS') {
            // use result.paymentOption.ccTempToken to pass on to the dynamic3D REST
        } else {
            // Otherwise, re-enable input. Handle error

        }
    });

Three-Part Card Fields Integration

In addition to the integration described above, SafeCharge Fields offers the same solution, but having the SafeCharge Card Field divided into its three building blocks: card number, expiration and CVV. This allows more flexibly with the payment form layouts.

  1. Import safecharge.js

COPIED
1
<script src="https://cdn.safecharge.com/safecharge_resources/v1/websdk/safecharge.js"></script>


2. Create a template for the three-part SafeCharge Fields.

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<form action="/charge" method="post" id="payment-form">
        <div class="row">
            <div class="field">
                <div id="card-number" class="input"></div>
                <label for="card-number" data-tid="scwsdk_fields_examples.form.card_number_label">Card number</label>
                <div class="underline"></div>
            </div>
        </div>
        <div class="row">
            <div class="field col6">
                <div id="card-expiry" class="input empty"></div>
                <label for="card-expiry" data-tid="scwsdk_fields_examples.form.card_expiry_label">Expiration</label>
                <div class="underline "></div>
            </div>
            <div class="field col6">
                <div id="card-cvc" class="input empty"></div>
                <label for="card-cvc" data-tid="scwsdk_fields_examples.form.card_cvc_label">CVC</label>
                <div class="underline "></div>
            </div>
        </div>
        <button>Submit Payment</button>
    </form>


3. Instantiate SafeCharge Web SDK.

COPIED
1
2
3
4
5
var sfc = SafeCharge({
sessionToken : '09f29859-caf0-4cf7-abba-69e1bc81c6e4', // sessionToken generated by your server
      env: 'int', // the environment you’re running on, if omitted prod is default
      merchantSiteId : 152358 // your merchantsite id provided by Safecharge
});


4. Instantiate SafeCharge Fields.

COPIED
1
2
3
4
5
var ScFields = sfc.fields({
fonts: [
            { cssUrl: 'https://fonts.googleapis.com/css?family=Roboto' }, // include your custom fonts
      ] 
})


5. Create custom styles and classes for SafeCharge Fields.

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
var ScFieldStyles = {
            base: {
                color: '#32325D',
                fontWeight: 500,
                fontFamily: 'Roboto, Consolas, Menlo, monospace',
                fontSize: '16px',
                fontSmoothing: 'antialiased',

                '::placeholder': {
                    color: '#CFD7DF',
                },
                ':-webkit-autofill': {
                    color: '#e39f48',
                },
            },
            invalid: {
                color: '#E25950',

                '::placeholder': {
                    color: '#FFCCA5',
                },
            },
        };

 var ScFieldClasses = {
     focus: 'focused',
     empty: 'empty',
     invalid: 'invalid',
     complete: 'complete',  
 };


6. Create and attach fields to the DOM.

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var cardNumber = ScFields.create('ccNumber', {
    style: ScFieldStyles,
    classes: ScFieldClasses,
});
cardNumber.attach('#card-number');

var cardExpiry = ScFields.create('ccExpiration', {
    style: ScFieldStyles,
    classes: ScFieldClasses,
});
cardExpiry.attach('#card-expiry');

var cardCvc = ScFields.create('ccCvc', {
    style: ScFieldStyles,
    classes: ScFieldClasses,
});
cardCvc.attach('#card-cvc');


7. Send the card to be tokenized by SafeCharge using the getToken method.
In return you get a result containing the paymentOption structure that contains the ccTempToken required for the server-side call to the dynamic3D API method.

COPIED
1
2
3
4
5
6
7
8
9
sfc.getToken(cardNumber).then(function(result) {
    // Stop progress animation!
    if (result.status === 'SUCCESS') {
        // use result.paymentOption.ccTempToken to pass on to the dynamic3D REST
    } else {
        // Otherwise, re-enable input. Handle error

    }
});

Additional Features

Additional Methods

The following additional methods are available to instruct SafeCharge Fields to perform the corresponding functionalities:
- destroy – Removes SafeCharge Fields from your page
- clear – Erases your customers input from SafeCharge Fields
- focus – Selects the element and your customer can start typing

Example for selecting an element and invoking method:

COPIED
1
2
3
4
document.getElementById("SfcFields").addEventListener('click', function (ev) {
            ev.preventDefault();
            SfcFields.destroy();
        });

SafeCharge Fields Custom Styling – States and Attributes

Supported States
We support custom styling for 4 states of SafeCharge Fields.

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
var customStyles = {
            base: {

            },
            empty: {

            },
            valid: {

            },
            invalid: {
            },
   };

Supported Attributes
We support the following attributes for custom styling: color, fontFamily, fontSize, fontSmoothing, -webkit-font-smoothing, -moz-osx-font-smoothing, fontStyle, fontVariant, fontWeight, lineHeight, letterSpacing, textAlign, textDecoration, textShadow, textTransform, ::placeholder, ::selection, ::-ms-clear, :-webkit-autofill, :disabled, :focus, :hover, opacity, and display.

Supported Events
We support the following events to which you can subscribe:
- blur
- change
- focus
- ready

COPIED
1
2
3
sfcCard.on('ready', function (evt) {
console.log('on sfcCard ready', evt);
});

Validation Errors Handling

For each change to the SafeCharge Fields, the Web SDK sends “change” events, which provide information the following information about the Fields status:

For errors, the following events are thrown:

Error samples:

/cardTokenization

Card tokenization enables the retrieval of a temporary card token based on card data.

High-level PCI certified merchants can work with this API fully server to server, as well as perform credit card payments be sending the card data itself in the API call request, either dynamic3D, payment3D methods (recommended) or using paymentCC method.
Card tokenization is intended for low-level PCI certified merchants implementing card tokenization.
For security and PCI reasons, please note that low-level PCI certified merchants that cannot enter card data on their side and use a native mobile application are not required to use the credit card tokenization client SDK. However, they are able to call the cardTokenization method directly.

Low-level PCI certified merchants that cannot enter card data on their side and use an online website are required to use the credit card tokenization client SDK, according to the instructions below, which performs credit card tokenization for them.


/initPayment

This method initiates the payment process for transactions. It is recommended use the SafeCharge Web SDK instead of calling this method directly.

The method determines the 3D Secure version for the end user and the method URL information.



Request Parameters

Example Request

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
                "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
                "merchantId": "2502136204546424962",
                "merchantSiteId": "126006",
                "userTokenId": "230811147",
                "orderId": "33704071",
                "clientRequestId": "TH2FFCD9T",
                "clientUniqueId": "695701003",
                "currency": "USD",
                "amount": "500",
                "paymentOption": {
                                "card": {
                                                "cardNumber": "5111426646345761",
                                                "cardHolderName": "CL-BRW1",
                                                "expirationMonth": "12",
                                                "expirationYear": "25",
                                                "CVV": "217",
                                                "threeD": {
                                                                "methodNotificationUrl": "www.ThisIsAMethodNotificationURL.com"
                                                }
                                }
                },
                "billingAddress": {
                                "addressMatch": "Y",
                                "city": "Billing City",
                                "country": "DE",
                                "address": "340689 Billing Str.", 
                                "addressLine2": "Billing Addres Line 2", 
                                "addressLine3": "Billing Addres Line 3",
                                "zip": "48957",
                                "state": "",
                                "email": "mhsbg.xxnbx@udapl.rg",
                                "phone": "359888526527",
                                "cell": "359881526527",
                                "firstName": "Zilsijihrw",
                                "lastName": "Jgethizxrr",
                                "county": "TTT"
                },
                "deviceDetails": {
                                "deviceType": "TABLET",
                                "deviceName": "iPad",
                                "deviceOS": "iOS U",
                                "browser": "safari U",
                                "ipAddress": "FE80::0202:B3FF:FE1E:8329"
                },
                "urlDetails": {
                                "notificationUrl": "http://srv-bsf-devppptrunk.gw-4u.com/ppptest/NotifyMerchantTest"
                },
                "customData": "Custom Data Inserted By Darin!",
                "webMasterId": "M9UOWGECHKD2"
}

And the response is:

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    "reason": "",
    "orderId": "33704071",
    "transactionStatus": "APPROVED",
    "clientRequestId": "TH2FFCD9T",
    "customData": "Custom Data Inserted By Darin!",
    "internalRequestId": 10036001,
    "version": "1.0",
    "transactionId": "2110000000000587378",
    "merchantSiteId": "126006",
    "transactionType": "InitAuth3D",
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode": 0,
    "paymentOption": {
        "card": {
            "ccCardNumber": "5****5761",
            "bin": "511142",
            "threeD": {
                "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
                "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
                "v2supported": "true",
                "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
                "version": "2.1.0"
            },
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "last4Digits": "5761"
        }
    },
    "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
    "userTokenId": "230811147",
    "status": "SUCCESS"
}
Parameter Type Mandatory Description
sessionToken
String (36)
Yes
The session identifier returned by getSessionToken.
orderId
String (45)
No
The ID to be used as an input parameter in the update method and payment methods. The parameter is sent to define which merchant order to update.
merchantId
String(20)
Yes
The merchant ID provided by SafeCharge.
merchantSiteId
String(20)
Yes
The merchant Site ID provided by SafeCharge.
userTokenId
String(255)
No
The ID of the user in merchant system.
clientUniqueId
String(45)
Yes
The ID of the transaction in merchant system.
clientRequestId
String(255)
Yes
The ID of the API request in merchant system.
currency
String(3)
Yes
The ISO currency code.
If the merchant did not call openOrder prior, then a value must be sent by the merchant in this parameter.
amount
String(12)
Yes
The transaction amount.
If the merchant did not call openOrder prior, then a value must be sent by the merchant in this parameter.
deviceDetails
Class
Conditional (per configuration)
The device’s details.
deviceType (string, 10)
deviceName (string, 255)
deviceOS (string, 255)
browser (string, 255)
ipAddres (string, 15)*Support device types: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (If device type cannot be recognized).
paymentOption
Class
Yes
Containing card payment information inside the card sub-class
paymentOption.card
Class
Yes
Card data that must be passed as a parameter in the payment methods, and not prior in the payment flow (openOrder, updateOrder) as it may not be saved in the cashier/checkout DB.
cardNumber (string, 20)
cardHolderName (string, 70) expirationMonth (string, 2)
expirationYear (string, 4)
cvv (string, 4)
OR**
ccTempToken*(string, 45)
cvv(string, 4)
cardHolderName* (string, 70)
urlDetails
Class
No
Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
successUrl (string, 1000)
failureUrl (string, 1000)
pendingUrl (string, 1000)
notificationUrl (string, 1000)
customData
String(255)
No
General data about the customer is provided by the merchant.This parameter can be used to pass any type of information to the gateway, which is returned in a response for the merchant records. This field is visible in Control Panel reports with transaction information.
webMasterId
String(255)
No
This is an affiliate parameter that the merchant can send and is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SC REST API SDK’s in order to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SC REST API.
timeStamp
String(14)
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss.
checksum
Hexi-decimal String (256)
Yes
Hash (used hash algorithm, MD5 or SHA256, depends on merchantSite setting) of the values of the request parameters UTF-8 encoded, and concatenated in this order:
merchantId
merchantSiteId
clientRequestId
amount
currency
timestamp
merchantSecretKey

Response Parameters

Parameter Type Description
sessionToken
String(36)
The session identifier returned by the getSessionToken parameter.
orderId
String(20)
The ID returned from the MerchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
merchantId
String(20)
The Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
The Merchant Site ID provided by SafeCharge.
userTokenId
String(255)
The ID of the user in merchant system.
clientUniqueId
String(255)
The ID of the transaction in merchant system.
clientRequestId
String(20)
The ID of the API request in merchant system.
internalRequestId
Long(20)
SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
transactionId
String(20)
The gateway transaction ID.
transactionType
String(45)
The type of transaction;
InitAuth3D
Note: This requires the merchant to be configured to gateway version 4.1.2 and up.
status
String(20)
The cashier status of merchant request.
Possible statuses: SUCCESS or ERROR
transactionStatus
String(20)
The gateway transaction status.
errCode
Integer(11)
The error code if an error occurred at the cashier side.
reason
String(400)
The error reason, if an error occurred on the cashier side.
For example: failure in checksum validation, timeout from processing engine, etc.
gwErrorCode
Integer(11)
The error reason code, if an error occurred on the gateway side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the specific error.
gwErrorReason
String(400)
The error reason, if an error an occurred on the gateway side.
gwExtendedErrorCode
Integer(11)
The error reason code, if an error occurred on the bank side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
String(10)
The version of the API.
The current version of the API method. The current version is 1.
paymentOption
Class
This class contains the card information inside the card sub-class and the userPaymentOptionId , as detailed in the following lines.
paymentOption.userpaymentOptionId
String(45)
This is the ID of the newly generated*userPaymentOption *, in the event that a new** userPaymentOption is generated, or a userPaymentOptionId** that has been used for transaction processing and has been sent into the request.
paymentOption.card
Class
bin String (6) - The bin number of the credit card.
last4Digits String (4) - The last four digits of the credit card number.
ccCardNumber String (20) - The masked credit card number, for example: 4****1111.
ccExpMonth String (2) - The two-digit value representing the expiration month.
ccExpYear String (4) - The four-digit value representing the expiration year.
threeD Class – A class containing the 3D Secure information as detailed in the following line.
paymentOption.card.threeD
Class
methodUrl String (256) - The 3D Secure 2.0 URL.
version String (8) - The 3D Secure version.
Possible values: 1 or 2.
ver2supported Boolean (1) - The 3D Secure 2 support indication.
serverTransID String - 3DS Server Transaction ID to be used in thethreeDSMethod in Merchant Website.
methodPayload String – To be to be used in thethreeDSMethod in merchant website.
Possible values: 0 (not supported) - or 1 (supported).
ver1supported Boolean (1) - The 3D Secure 1 support indication.Possible values: 0 (not supported) - or 1 (supported).

/payment

Overview

The payment method is your endpoint for performing payment of any kind:
- Regular card transactions – credit or debit cards.
-3D secure card transactions, supporting 3D 2.0
-Alternative payment method transactions

Mandatory Fields

-Authentication credentials – sessionToken, merchantId, merchantSiteId, checksum, timeStamp, country under billing Address
-Amount and currency
-A Payment option – the payment method details by which the payment is executed. This is passed using the paymentOption JSON block, which is either created by the Web SDK and passed from the client-side or can be constructed by you directly on the server side.

Selecting a Payment Method (paymentOption class)

This class represents the details of the payment method of the transaction that can be one of three options, which are represented by the sub class to the paymentOption:



Input Field Table

Input Parameters

Example Request

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
{
  "merchantSiteId": "51001",
  "merchantId": "5288945245833474115",
  "sessionToken": "{{sessionToken}}",
  "clientRequestId": "20190605094208",
  "           ": "20190228160209",
  "checksum": "eb50508f5cd2e99797a658f686ceb5ea",
  "clientUniqueId": "uniqueIdCC",
  "currency": "EUR",
  "amount": "10",
  "userTokenId": "someone@website.com",
  "isRebilling": "0",
  "paymentOption" : {
                             "card": {
                                           "cardNumber": "5115806139808464",
                                           "cardHolderName": "test name",
                                           "expirationMonth": "01",
                                           "expirationYear": "2020",
                                           "CVV": "122",
                                           "threeD":{
                                                "browserDetails":{
                                                     "acceptHeader":"text/html,application/xhtml+xml",
                                                     "ip":"192.168.1.11",
                                                     "javaEnabled":"TRUE",
                                                     "javaScriptEnabled":"TRUE",
                                                     "language":"EN",
                                                     "colorDepth":"48",
                                                     "screenHeight":"400",
                                                     "screenWidth":"600",
                                                     "timeZone":"0",
                                                     "userAgent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47"
                                                },
                                                "version":"2",
                                                "challengePreference":"1",
                                                "notificationUrl":"https://www.merchant.com/notificationURL/",
                                                "merchantUrl":"https://www.merchant-website.com",
                                                "platformType":"02",
                                                "deliveryEmail":"deliveryEmail@somedomain.com",
                                                "deliveryTimeFrame":"1",
                                                "giftCardAmount":"456",
                                                "giftCardCount":"10",
                                                "giftCardCurrency":"826",
                                                "preOrderDate":"20190219",
                                                "preOrderPurchaseInd":"2",
                                                "reorderItemsInd":"2",
                                                "shipIndicator":"1",
                                                "rebillExpiry":"",
                                                "rebillFrequency":"",
                                                "ChallengeWindowSize":"2"
                                           }
                             }
              },

  "deviceDetails": {
    "deviceType": "DESKTOP",
    "deviceName": "deviceName",
    "deviceOS": "deviceOS",
    "browser": "browser",
    "ipAddress": "127.0.0.1"
  },
  "userDetails": {
    "firstName": "first_name",
    "lastName": "last_name",
    "email": "email@email.com",
    "phone1": "phone1",
    "phone2": "phone2",
    "phone3": "phone3"
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "city",
    "country": "DE",
    "state": "",
    "zip": "1340"
  },
  "billingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "city",
    "country": "DE",
    "state": "",
    "zip": "1335"
  },
  "dynamicDescriptor": {
    "merchantName": "merchantName",
    "merchantPhone": "merchantPhone"
  },
  "merchantDetails": {
    "customField1": "customField1",
    "customField2": "customField2",
    "customField3": "customField3",
    "customField4": "customField4",
    "customField5": "customField5"
  }
}

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
    "orderId": "246670583",
    "userTokenId": "someone@website.com",
    "paymentOption": {
        "userPaymentOptionId": "8348263",
        "card": {
            "ccCardNumber": "5****8464",
            "bin": "511580",
           "last4Digits": "8464",
            "ccExpMonth": "01",
            "ccExpYear": "20",
            "acquirerId": "19",
            "cvv2Reply": "",
            "avsCode": "",
            "threeD": {
                "sdk": {}
            }
        }
    },
    "transactionStatus": "DECLINED",
    "merchantDetails": {
                             "customField1": "customField1",
                             "customField2": "customField2",
                             "customField3": "customField3",
                             "customField4": "customField4",
                             "customField5": "customField5"

    },
    "gwErrorCode": -1,
    "gwErrorReason": "Decline",
    "gwExtendedErrorCode": 0,
    "transactionType": "Auth3D",
    "transactionId": "1110000000000696512",
    "externalTransactionId": "",
    "authCode": "",
    "customData": "",
    "sessionToken": "76f24921-a279-4ad7-9893-142d6e6c2ab6",
    "clientUniqueId": "uniqueIdCC",
    "internalRequestId": 143323743,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "5288945245833474115",
    "merchantSiteId": "51001",
    "version": "1.0",
    "clientRequestId": "20190605094208"
}

The following table describes the full list of input fields to be sent for any call using the payment method.
The paymentOption class field of the request is described in the follow-up table.

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
The merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
The merchant Site ID provided by SafeCharge.
sessionToken
String
(36)
Yes
Session identifier returned by the getSessionToken.
timeStamp
String
(14)
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
The UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order:
merchantId,
merchantSiteId,
clientRequestId,
amount,
currency,
timeStamp,
merchantSecretKey
currency
String
(3)
Yes
The three-character ISO currency code.
amount
Double
(12)
Yes
The transaction amount.
This amount must be identical to the amount listed in the dynamic3D.
paymentOption
Class
Yes
This class represent the details about the payment method.
Can be one of 3 options.
See above for details.
card – representing credit/debit card.
-or-
alternativePaymentMethod – representing an alternative payment method.
-or-
userPaymentOptionId – this is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. SafeCharge keeps payment option details from a previous uses.
relatedTransactionId
String
(19)
Conditional
(See description.)
Mandatory in the following cases:
For 3D 2.0 (refer to 3D 2.0 guide for details).
The transaction ID of the initPayment on the first call.
The transaction ID of the first Payment call of the second call.
This is for rebilling/recurring transactions marked by the sg_Rebill field, which CVV cannot be provided.
orderId
String
(45)
No
The order ID provided by SafeCharge.
This parameter is passed to define which merchant order to update.
userTokenId
String
(255)
No
The ID of the user in the merchant’s system. Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details.
clientUniqueId
String
(45)
No
The ID of the transaction in the merchant’s system. This value must be unique, and though not mandatory it is recommended that it is sent.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
This parameter appears in the DMN as merchant_unique_id.
clientRequestId
String
(255)
No
The ID of the API request in the merchant’s system. This value must be unique, and though not mandatory it is recommended that it is sent.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
isPartialApproval
String
(1)
No
This describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds within the desired payment method.
Partial approval is only supported by SafeCharge acquiring. In order for partial approval to be available for the merchant it should be configured by SafeCharge’s integration team.
Possible values:
1 - allow partial approval
0 - not allow partial approval
amountDetails
Class
No
totalShipping (String, not mandatory),
totalHandling (String, not mandatory),
totalDiscount (String, not mandatory),
totalTax (String, not mandatory)

The items and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
items
Class
No
name (String, 255, mandatory),
price (String, 10, mandatory),
quantity (String, 10, mandatory)

An array describing the items in the purchase. The items price should be summed up to the amount parameter sent separately. All items must be in the same currency.
deviceDetails
Class
Only ipAddress
deviceType (String, 10),
deviceName (String, 255),
deviceOS (String, 255),
browser (String, 255), ipAddress (String, 15)

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by SafeCharge’s integration team.
userDetails
Class
No
firstName (String, 30, not mandatory),
lastName (String, 40, not mandatory),
address (String, 60, not mandatory),
phone (String, 18, not mandatory),
zip (String, 10, not mandatory),
city (String, 30, not mandatory),
country (two-letter ISO country code)(String, 2, not mandatory),
state (two-letter ISO state code)(String, 2, not mandatory),
email (String, 100, not mandatory),
county (String, 255, not mandatory)
shippingAddress
Class
No
firstName (String, 30),
lastName (String, 40),
address (String, 60),
phone (String, 18),
zip (String, 10),
city (String, 30),
country (two-letter ISO country code)(String, 2),
state (two-letter ISO state code)(String, 2),
email (String, 100),
shippingCounty (String, 255)
billingAddress
Class
Only country
The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters.
firstName (String, 30),
lastName (String, 40),
address (String, 60),
phone (String, 18),
zip (String, 10),
city (String, 30),
country (two-letter ISO country code)(String, 2), must be entered in Uppercase
state (two-letter ISO state code)(String, 2),
email (String, 100),
county (String, 255)

These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s integration team.
dynamicDescriptor
Class
No
descriptorMerchantName (String, 25, not mandatory),
descriptorMerchantPhone (String, 13, not mandatory)
merchantDetails
Class
No
customField1 (String, 255, not mandatory),
customField2 (String, 255, not mandatory),
customField3 (String, 255, not mandatory),
customField4 (String, 255, not mandatory),
customField5 (String, 255, not mandatory),
customField6 (String, 255, not mandatory),
customField7 (String, 255, not mandatory),
customField8 (String, 255, not mandatory),
customField9 (String, 255, not mandatory),
customField10 (String, 255, not mandatory),
customField11 (String, 255, not mandatory),
customField12 (String, 255, not mandatory),
customField13 (String, 255, not mandatory),
customField14 (String, 255, not mandatory),
customField15 (String, 255, not mandatory)
urlDetails
Class
No
notificationUrl (String, 1000)

This parameter determines where to return the DMN to.
Each parameter is limited to up to 1000 characters.
customSiteName
String
(50)
No
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
Risk rules and traffic management rules are usually built based on this field value.
productId
String
(50)
No
A free text field used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this field value.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
This is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SafeCharge API SDKs in order to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SafeCharge API.

paymentOption Input

As explained, the paymentObject block in the payment request specifies the payment method details. It can contain either one of the following sub-classes:

Card Class

PARAMETER TYPE MANDATORY DESCRIPTION
cardNumber
-or-
ccTempToken
String
(20),
String, (45)
Yes
The clear text cardNumber can be collected and provided by merchants that are PCI certified to do so.
Alternatively, you can use our web SDK tokenization and provide card token using ccTempToken.
cardHolderName
String
(70)
Yes
The card holder name, as it appears on the card.
expirationMonth
String
(2)
Yes
The card expiration month as it appears on the card.
expirationYear
String
(4)
Yes
The card expiration year as it appears on the card.
CVV
String
(4)
Yes
The CVV/CVC security code as appear on the back of the card.
threeD
Class
Yes, (for 3D-S)
A class structure that contains all of the 3D secure information. If you are using the SafeCharge web SDK, paymentOption includes all the relevant 3D information inside this block.
In case you would like to construct this class on your own, please refer to the threeD class of the paymentOption input section under the 3D Secure guide.

Two optional advance fields help you control the 3D secure behavior:
- dynamic3DMode (String), possible values: “ON” / “OFF”
If you would like to override the 3D secure default behavior and force non-3D secure transaction, you need set the following threeD field to “OFF”. The default value is “ON”.
- convertNonEnrolled (String), possible values: “false”/“true”

If you set this flag to “true”, it submits a transaction for processing, even if the a 3D Secure was attempted and failed because the user is not enrolled for 3D secure. The default value is “false”.

threeD Class

This class contains the 3D Secure information required to perform the 3D authorization as defined in the 3D Guide.

threeD fields Type Mandatory Description
version
String
3D 2.0
The 3DS version used.
1 or empty = 3DS 1.0
2 = 3DS 2.0
notificationURL
String
3D 2.0
The notification URL for redirecting the browser after the challenge completion, which receives the CRes message.
merchantURL
String
3D 2.0
The merchant website fully qualified URL.
methodCompletionInd
String
3D 2.0
Indicates whether the 3DS Method was successfully completed.
Y = Successfully completed
N = Did not successfully complete
U = Unavailable – 3DS Method URL was not present
challengePreference
String
No
The 3DS challenge requestor indication.
01 = No preference
02 = No challenge requested
03 = Challenge requested: 3DS Requestor Preference
04 = Challenge requested: Mandate
platformType
String
3D 2.0
The device channel.
01 = App-based (only for SDK implementation, not in the scope of this document)
02 = Browser
deliveryEmail
String
No
For electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeFrame
String
No
Indicates the merchandise delivery timeframe.
01 = Electronic Delivery
02 = Same day shipping
03 = Overnight shipping
04 = Two-day or more shipping
giftCardAmount
String
No
For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
giftCardCount
String
No
For prepaid or gift card purchase, the total count of individual prepaid or gift cards/codes purchased.
giftCardCurrency
String
No
For prepaid or gift card purchase, the ISO 4217 three-digit currency code of the gift card.
preOrderDate
String
No
For a pre-ordered purchase, the expected date that the merchandise is available (YYYYMMDD).
preOrderPurchaseInd
String
No
Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 = Merchandise available
02 = Future availability
reorderItemsInd
String
No
Indicates whether the cardholder is reordering previously purchased merchandise.
01 = First time ordered
02 = Reordered
shipIndicator
String
No
Indicates the selected shipping method for the transaction.
01 = Ship to cardholder’s billing address
02 = Ship to another verified address on file with merchant
03 = Ship to address that is different than the cardholder’s billing address
04 = “Ship to Store”/Pick-up at local store (Store address shall be populated in shipping address fields)
05 = Digital goods (includes online services, electronic gift cards and redemption codes)
06 = Travel and Event tickets, not shipped
07 = Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)
rebillExpiry
String
No
Recurring Expiry - required if sg_rebill = 1 (format: YYYYMMDD)
rebillFrequency
String
No
Recurring Expiry - required if sg_rebill = 1In number of days.
challengeWindowSize
String
No
The dimensions of the challenge window.
01 = 250 x 4000
2 = 390 x 4000
3 = 500 x 6000
4 = 600 x 4000
5 = Full screen
browserDetails
Class
3D 2.0
acceptHeader (string, not mandatory)
browserIP (string, not mandatory)
browserJavaEnabled (string, not mandatory)
browserJavaScriptEnabled (string, not mandatory)
browserLanguage (string, not mandatory)
browserColorDepth (string, not mandatory)
browserScreenHeight (string, not mandatory)
browserScreenWidth (string, not mandatory)
browserTimeZone (string, not mandatory)
browserUserAgent (string, not mandatory)

alternativePaymentMethod Class

PARAMETER TYPE MANDATORY DESCRIPTION
paymentMethod
String
(50)
Yes
Specifies the payment method name of the payment option to be charged.
Payment method specific field set
Please refer to:
APM Account-Identifiers

Output Field Table

The table below contains the full list of output fields retrieved with the payment method response, for any call. The paymentOption class field of the request is described in the follow-up table.

Input Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"orderId": "241494183",
"userTokenId": "petka",
"paymentOption": {
"userPaymentOptionId": "8348263",
"card": {
"ccCardNumber": "5****8464",
"bin": "511580",
"last4Digits": "8464",
"ccExpMonth": "01",
"ccExpYear": "20",
"cvv2Reply": "",
"avsCode": "",
"threeD": {}
}
},
"transactionStatus": "DECLINED",
"merchantDetails": {
"customField1": "merchantName",
"customField2": "merchantName",
"customField3": "merchantName",
"customField4": "merchantName",
"customField5": "merchantName",
"customField6": "merchantName",
"customField7": "merchantName",
"customField8": "merchantName",
"customField9": "merchantName",
"customField10": "merchantName",
"customField11": "merchantName",
"customField12": "merchantName",
"customField13": "merchantName",
"customField14": "merchantName",
"customField15": "merchantName"
         },
"gwErrorCode": -1,
"gwErrorReason": "Decline",
"gwExtendedErrorCode": 0,
"transactionType": "Auth3D",
"transactionId": "1110000000000347161",
"externalTransactionId": "",
"authCode": "",
"customData": "",
"sessionToken": "5bd76168-844c-4fb1-9cfb-f7812ca31950",
"clientUniqueId": "uniqueIdCC",
"internalRequestId": 134148663,
"status": "SUCCESS",
"errCode": 0,
"reason": "",
"merchantId": "5288945245833474115",
"merchantSiteId": "51001",
"version": "1.0",
"clientRequestId": "20190411173319"
}

PARAMETER TYPE DESCRIPTION
sessionToken
String
(36)
The session identifier returned by the getSessionToken parameter.
orderId
String
(20)
The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
merchantId
String
(20)
The Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
The Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
The ID of the user in merchant system.
clientUniqueId
String
(255)
The ID of the transaction in merchant system.
clientRequestId
String
(20)
The ID of the API request in merchant system.
internalRequestId
Long
(20)
SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
status
String
(20)
The cashier status of merchant request.
Possible statuses: SUCCESS or ERROR
transactionStatus
String
(20)
The gateway transaction status.
paymentOption
Class
This class represent the details about the payment method. This can be one of two options: See above for details.

card – representing credit/debit card.
-or-
alternativePaymentMethod – representing an alternative payment method.

In addition, if a user option ID was either created or exiting one was uses in the transaction – it returns the ID to this payment option:
userPaymentOptionId – this is a field identifying a payment option that
merchantDetails
Class
customField1 (String, 255, not mandatory),
customField2 (String, 255, not mandatory),
customField3 (String, 255, not mandatory),
customField4 (String, 255, not mandatory),
customField5 (String, 255, not mandatory),
customField6 (String, 255, not mandatory),
customField7 (String, 255, not mandatory),
customField8 (String, 255, not mandatory),
customField9 (String, 255, not mandatory),
customField10 (String, 255, not mandatory),
customField11 (String, 255, not mandatory),
customField12 (String, 255, not mandatory),
customField13 (String, 255, not mandatory),
customField14 (String, 255, not mandatory),
customField15 (String, 255, not mandatory)

This allows the merchant to send information with the request to be saved in the API level and returned in response. It is not passed to the payment gateway and is not used for processing.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
gwExtendedErrorCode
Integer
(11)
The error code if an error occurred on the bank’s side.
When a transaction is successful, this field is 0.
When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
(10)
The version of the request.
The current version is 1.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
transactionId
String
(20)
The gateway transaction ID.
authCode
String
(128)
The authorization code of the transaction.
partialApprovalDetails
Class
This determines whether or not the transaction is a partial approval and other information regarding the amount.
These following parameters are returned only if the partial approval feature was in use, as per the relevant input parameter sent value.

isPartialApproval (String-True or False)
amountInfo:
requestedAmount (String),
requestedCurrency (String),
processedAmount (String),
processedCurrency (String)
transactionType
String
(45)
The type of transaction; Sale or Auth.
Note: This requires the merchant to be configured to gateway version 4.1.2 or higher. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com
customData
String
(255)
This parameter can be used to pass any type of information.
If sent in the request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
fraudDetails
Class
finalDecision (String),
recommendations (String),
system {systemId(String),
systemName (String),
decision (String),
rules [ruleId(String),
ruleDescription (String)]}

The ‘system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
The ‘rule’ refers to the risk management system rules triggered by the transaction.
The ‘decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction.
There are five possible values for the decision parameter:
1. Accept - The risk management system accepts the transactions.
2. Reject - The risk management system rejects the transaction. The transaction not passed to bank for authorization. The reasons are returned in ruleDescription parameter.
3. Review - The risk management system flags a transaction for review, but still accepts the transaction.
4. Error - An error occurred during the risk management system operation. The gateway continues to process the transaction through the bank.
5. None - No risk analysis was performed. The gateway continues to process the transaction through the bank.

The finalDecision refers to when deciding whether to accept or reject a transaction. The risk Management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a ‘Reject’ decision, the finalDecision accepts the transaction. If at least one of the rules leads to a ‘Reject’ decision, the finalDecision rejects the transaction.
In order to receive this information in response special configurations are required. For more information, please contact SafeCharge’s integration team at integration@safecharge.com

paymentOption Output

The following two tables describe the paymentOption object, as retrieved from calling the payment method. It includes either the card OR the alternativePaymentMethod class, according to the method processed. In addition it includes the userPaymentOptionId, if one was created during the payment request or if one was used for the payment.

PARAMETER TYPE DESCRIPTION
userPaymentOptionId
String
(45)
Upon the first consumer use of a particular payment method, SafeCharge assigns a unique ID and returns it.
This ID is returned as the value of this parameter for subsequent uses.
card
Class
bin (String) - The bin number of the credit card.
last4Digits (String) - The last four digits of the credit card number.
ccCardNumber (String) - The credit card number in a mask, for example: 4***1111
ccExpMonth* (String) - The two-digit value that is the expiration month.
ccExpYear (String) - The four-digit value that is the expiration year.
cvv2Reply (String) - The CVV2 (card verification value).
avsCode (String) - The AVS (address verification) response.
acquirerId (String) – The acquirer ID of the acquirer which processed the transaction.
threeD (Class) – This class contains the 3D Secure information part of the response. Detailed in the following up table
-OR-
redirectURL
String
The URL used by the merchant to redirect consumers to the payment method for authentication and authorization of the payment. This is returned only if the APM payment is conducted using redirect APM flow.

threeD Class Output

The 3D Secure result returned from the call to payment as described in the 3D Guide.

Parameter Type Description
cavv
String(28)
A cryptogram created by the issuer that serves as a proof that the merchant is entitled to this authentication.
whiteListStatus
String(1)
This determines whether this consumer defined this merchant as whitelist or not. If the consumer defined the merchant, then this is the reason why the challenge did not occur.
Possible values:
Y = 3DS Requestor is whitelisted by cardholder
N = 3DS Requestor is not whitelisted by cardholder
E = Not eligible as determined by issuer
P = Pending confirmation by cardholder
R = Cardholder rejected
U = Whitelist status unknown, unavailable, or does not apply
threeDFlow
String
If the gateway response parameter for threeDFlow = 1 the transaction is converted from Sale3D to Auth3D after passing the gateway rule engine. ( paRequest and acsUrl are returned and the merchant needs to redirect to issuer and call payment3D method afterwards).If the gateway response parameter for threeDFlow = 0, the transaction converted from Sale3D to Sale or Auth depending on the configured merchant mode of operation after passing the gateway rule engine. ( paRequest and acsUrl are NOT be returned and the merchant does NOT need to redirect to issuer and call payment3D method later on).
externalTransactionId
String(20)
The transaction ID of the transaction in the event that an external service is used.
transactionId
String(20)
The gateway transaction ID.
authCode
String(128)
The authorization code of the transaction.
paRequest
String
The 3D secure request data for the card issuer/bank.
acsUrl
String
URL/endpoint used to redirect the consumer to the card issuer/bank’s 3D secure verification page.
eci
String
This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed.
The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant.
Possible ECI data values are:
ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated
ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program
ECI = 7: payment authentication was not performed
Note: In this method eci is returned in response only in case its value is 1 or 6 or 7.
threeDReason
String
If the attempt failed, this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
acsChallengeMandate
String(1)
The 3D Secure 2.0 challenge required indication. Possible values:N (not required)Y (required)
cReq
String
The Base64 encoded cReq relevant for the 3D Secure 2.0. acsUrl is sent as well as a separate field.
authenticationType
String(2)
The type of authentication performed during the 3D Secure 2.0 challenge.
If the merchant wants to react differently for each authentication type, it is possible per the value returned.
Possible values:
01 (Static)
02 (Dynamic)
03 (OOB)
04 (Decoupled)
05–79 (reserved for EMVCo future use, values invalid until defined by EMVCo)
80–99 (Reserved for DS use)
cardHolderInfoText
String(128)
The text provided by the ACS/Issuer to the cardholder during a frictionless transaction that was not authenticated by the ACS.The issuer can opt to provide information to cardholder.For example: “Additional authentication is needed for this transaction, please contact [Issuer Name] at xxx-xxx-xxxx.”

/settleTransaction

The settleTransaction method is used for settling an authorization transaction that was previously performed, with a two-phase auth-settle process, for either a full or partial settles. When partial settles are issued – multiple settles requests can be performed for up to the entire amount of the original authorised transaction.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/settleTransaction.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "100",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "8495798459",
    "authCode": "8378749",
    "descriptorMerchantName": "Name",
    "descriptorMerchantPhone": "+4412378",
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": ""
    },
    "addendums": {
        "airline": {
        "addendumSent":"",
        "pnrCode":"",
        "bookingSystemUniqueId":"",
        "computerizedReservationSystem":"",
        "ticketNumber":"",
        "documentType":"",
        "flightDateUTC":"",
        "issueDate":"",
        "travelAgencyCode":"",
        "travelAgencyName":"",
        "travelAgencyInvoiceNumber":"",
        "travelAgencyPlanName":"",
        "restrictedTicketIndicator":"",
        "issuingCarrierCode":"",
        "isCardholderTraveling":"",
        "passengersCount":"",
        "infantsCount":"",
        "payerPassportId":"",
        "totalFare":"",
        "totalTaxes":"",
        "totalFee":"",
        "boardingFee":"",
        "ticketIssueAddres ":"",
        "passengerDetails": {
            "passengerId":"",
            "passportNumber":"",
            "customerCode":"",
            "frequentFlyerCode":"",
            "title":"",
            "firstName":"",
            "lastName":"",
            "middleName":"",
            "dateOfBirth":"",
            "phoneNumber":""
        },
        "flightLegDetails": {
            "flightLegId":"",
            "airlineCode":"",
            "flightNumber":"",
            "departureDate":"",
            "arrivalDate":"",
            "departureCountry":"",
            "departureCity":"",
            "departureAirport":"",
            "destinationCountry":"",
            "destinationCity":"",
            "destinationAirport":"",
            "legType":"",
            "flightType":"",
            "ticketDeliveryMethod":"",
            "ticketDeliveryRecipient":"",
            "fareBasisCode":"",
            "serviceClass":"",
            "seatClass":"",
            "stopOverCode":"",
            "departureTaxAmount":"",
            "departureTaxCurrency":"",
            "fareAmount":"",
            "feeAmount":"",
            "taxAmount":"",
            "layoutIntegererval":""
            }
        }
    },
    "customSiteName":"",
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
(128)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientUniqueId
String
(255)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
amount
Decimal
(12)
Yes
The transaction amount.
currency
String
(3)
Yes
The three character ISO currency code.
It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId
String
(19)
Yes
The ID of the original auth transaction.

The value sent must contain digit characters only, meaning this string value can not contain any character that is not a digit.
authCode
String
(128)
Yes
The authorization code of the related auth transaction, to be compared to the original one.
descriptorMerchantName
String
(25)
No
Allows the merchant to define a dynamic descriptor, which appears in the payment statement. The name field should contain the merchant name.

If you work in an auth-Settle mode then you must provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
descriptorMerchantPhone
String
(13)
No
Allows the merchant to define a dynamic descriptor, which appears in the payment statement. The phone field should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.

If you work in an auth-Settle mode then you must to provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
comment
String
(255)
No
Enables the addition of a free text comment to the request.
urlDetails
Class
No
notificationUrl(String, 1000)

This parameter determines where to return the DMN.
Each parameter is limited for up to 1000 characters.
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

For example, airline addendum includes:
addendumSent(String),
pnrCode(String),
bookingSystemUniqueId(String),
computerizedReservationSystem(String),
ticketNumber(String),
documentType(String),
flightDateUTC(String),
issueDate(String),
travelAgencyCode(String),
travelAgencyName(String),
travelAgencyInvoiceNumber(String),
travelAgencyPlanName(String),
restrictedTicketIndicator(String),
issuingCarrierCode(String),
isCardholderTraveling(String),
passengersCount(String),
infantsCount(String),
payerPassportId(String),
totalFare(String),
totalTaxes(String),
totalFee(String),
boardingFee(String),
ticketIssueAddres(String),
passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)},
flightLegDetails {flightLegId(String), airlineCode(S, flightNumber(String), departureDate(String), arrivalDate(String), departureCountry(String), departureCity(String), departureAirport(String), destinationCountry(String), destinationCity(String), destinationAirport(String), legType(String), flightType(String), ticketDeliveryMethod(String), ticketDeliveryRecipient(String), fareBasisCode(String), serviceClass(String), seatClass(String), stopOverCode(String), departureTaxAmount(String), departureTaxCurrency(String), fareAmount(String), feeAmount(String), taxAmount(String), layoutIntegererval(String)}

For card airline transactions, it is not required to send airline information during settle as it is sent previously during Auth. For APM airline transactions, it is required to send airline information during settle and not during Auth (currently only PayPal APM is supported for airline transactions).

For more information and for required SafeCharge configurations settings, please contact SafeCharge’s Integration Team at integration@safecharge.com.
customSiteName
String
(50)
No
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId
String
(50)
No
A free text field used to identify the product/service sold.
If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
timeStamp
String
(14)
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, descriptorMerchantName, descriptorMerchantPhone, comment, urlDetails, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "merchantId": "8263015379487437770",
   "merchantSiteId": "39",
   "internalRequestId": "45",
   "clientRequestId": "100",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "authCode": "8378749",
   "errCode": "0",
   "reason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "customData":"",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
internalRequestId
String
(20)
ID of the API request in merchant system.
clientRequestId
String
(255)
The client’s request ID as defined by the merchant for record-keeping.
transactionId
String
(20)
The transaction ID of the settle transaction for future actions.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
(20)
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
authCode
String
(128)
Authorization code of the transaction.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
paymentMethodErrorCode
Integer
(11)
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
(400)
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
customData
String
(255)
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
version
Integer
(10)
The current version of the request. The current version is 1.

/refundTransaction

The refundTransaction method is used for refunding a previously settled transaction for either a full or partial refunds. When partial refunds are issued, multiple refund requests can be performed for up to the entire amount of the original settled transaction.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/refundTransaction.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "100",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "8495798459",
    "authCode": "8378749",
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "customSiteName":"",
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
(128)
Yes,
See Description
ID of the API request in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientUniqueId
String
(255)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
amount
Decimal
Yes
(12)
The transaction amount.
currency
String
(3)
Yes
The three character ISO currency code.
It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId
String
(19)
Yes
The ID of the settle transaction.

The value sent must contain digit characters only, meaning this string value can not contain any character that is not a digit.
authCode
String
(128)
Yes,
See Description
The authorization code of the related settle transaction, to be compared to the original one.
This is mandatory for cards, non-mandatory for APM’s.
comment
String
(255)
No
Enables the addition of a free text comment to the request.
urlDetails
Class
No
notificationUrl(String, 1000)

This parameter determines where to return the DMN.
Each parameter is limited for up to 1000 characters.
customSiteName
String
(50)
No
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId
String
(50)
No
A free text field used to identify the product/service sold.
If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
timeStamp
String
(14)
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "merchantId": 8263015379487437770,
   "merchantSiteId": "39",
   "internalRequestId": 45,
   "clientRequestId": "100",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "authCode": "8378749",
   "errCode": "0",
   "errReason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "customData":"",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
internalRequestId
String
(20)
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
(255)
The client’s request ID as defined by the merchant for record-keeping.
transactionId
String
(20)
The transaction ID of the refund transaction for future actions.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
(20)
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
authCode
String
(128)
Authorization code of the transaction.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
paymentMethodErrorCode
Integer
(11)
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
(400)
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
customData
String
(255)
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
version
Integer
(10)
The current version of the request. The current version is 1.

/voidTransaction

The voidTransaction method is used for voiding a previously performed authorization, within a two-phase auth-settle process. Please note that a void action is not always supported by the payment method or the card issuer.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/voidTransaction.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "100",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "8495798459",
    "authCode": "8378749",
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "customSiteName":"",
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
(128)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientUniqueId
String
(255)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
amount
Decimal
(12)
Yes
The transaction amount.
It is required to send an amount that is equal to the amount sent in the related transaction that this void aim to cancel.
currency
String
(3)
Yes
The three character ISO currency code.
It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId
String
(19)
Yes
The ID of the original auth transaction.

The value sent must contain digit characters only, meaning this string value can not contain any character that is not a digit.
authCode
String
(128)
Yes
The authorization code of the related settle transaction, to be compared to the original one.
comment
String
(255)
No
Enables the addition of a free text comment to the request.
urlDetails
Class
No
notificationUrl(String, 1000)

This parameter determines where to return the DMN.
Each parameter is limited for up to 1000 characters.
customSiteName
String
(50)
No
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId
String
(50)
No
A free text field used to identify the product/service sold.
If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
timeStamp
String
(14)
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "merchantId": 8263015379487437770,
   "merchantSiteId": "39",
   "internalRequestId": 45,
   "clientRequestId": "100",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "authCode": "8378749",
   "errCode": "0",
   "errReason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "customData":"",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
internalRequestId
String
(20)
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
(20)
ID of the API request in merchant system.
transactionId
String
(255)
The transaction ID of the void transaction for future actions.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
(20)
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
authCode
String
(128)
Authorization code of the transaction.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
paymentMethodErrorCode
Integer
(11)
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
(400)
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
customData
String
(255)
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
version
Integer
(10)
The current version of the request. The current version is 1.

/payout

The payout method allows to perform payout (transfer funds from merchant to consumer, with no relation to previous transaction).





Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/payout.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientRequestId": "100",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503"
    },
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": ""
    },
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
Yes
ID of the user in the merchant’s system.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientUniqueId
String
(45)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
amount
Double
(12)
Yes
The transaction amount.
currency
String
(3)
Yes
The three character ISO currency code.
dynamicDescriptor
Class
No
merchantName(String, 25),
merchantPhone(String, 13)

This allows the merchant to define a dynamic descriptor, which will appear in the payment statement. The name field should contain the merchant name. The phone field should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.
merchantDetails
Class
No
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not be used for processing.
cardData
Class
No
This may be one of two options:
cardNumber(String, 20),
cardHolderName(String, 70),
expirationMonth(String, 2),
expirationYear(String, 4),
CVV(String, 4)

An alternative to sending the paymentOptionId for card payouts. Merchant has to be PCI ceritifed in order to use this, as it uses clear text card numbers.
When sending carData you must also send userTokenId
CVV can be mandatory or non-mandatory per configuration.
If CVV not required need to send it with NULL value or not provide CVV parameter at all in the request.
userPaymentOption
Class
Yes
userPaymentOptionId(String, 45),

The first time a consumer uses a payment method, SafeCharge assigns a unique ID to it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
comment
String
(255)
No
Enables the addition of a free text comment to the request.
urlDetails
Class
No
notificationUrl(String, 1000)

This parameter determines where to return the DMN.
Each parameter is limited for up to 1000 characters.
timeStamp
String
(14)
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
   "merchantId": "8263015379487437770",
   "merchantSiteId": "39",
   "userTokenId": "487106",
   "clientUniqueId": "12345",
   "clientRequestId": "1484759782197",
   "internalRequestId": "866",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "merchantDetails": {
    "customField1": "",
    "customField2": "",
    "customField3": "",
    "customField4": "",
    "customField5": "",
    "customField6": "",
    "customField7": "",
    "customField8": "",
    "customField9": "",
    "customField10": "",
    "customField11": "",
    "customField12": "",
    "customField13": "",
    "customField14": "",
    "customField15": ""
   },
   "userPaymentOptionId": "12442",
   "errCode": "0",
   "reason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
ID of the user in the merchant’s system.
clientUniqueId
String
(45)
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(255)
ID of the API request in the merchant’s system.
internalRequestId
String
(20)
ID of the API request in merchant system.
transactionId
String
(20)
The gateway transaction ID.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
merchantDetails
Class
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
userPaymentOptionId
String
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
paymentMethodErrorCode
Integer
(11)
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
(400)
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
(10)
The current version of the request. The current version is 1.

/getPaymentPageUrl

Although this is a server to server API, if a merchant wants to use SafeCharge hosted payment page instead of building its own payment page UI, then this method allows retrieval of a redirect URL to a SafeCharge hosted payment page UI.
For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getPaymentPageUrl.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
{
  "merchantId": "427583496191624621",
  "merchantSiteId": "142033",
  "userTokenId": "487106",
  "clientUniqueId": "12345",
  "clientRequestId": "1484759782197",
  "currency": "EUR",
  "amount": "22",
  "amountDetails": {
    "totalShipping": 2,
    "totalHandling": 1,
    "totalDiscount": 6,
    "totalTax": 3,
    "itemOpenAmount1": "false",
    "itemMinAmount1": "",
    "itemMaxAmount1": "",
    "numberOfItems":"1"
  },
  "productId": "",
  "promoCode": "",
  "items": [
    {
      "name": "name",
      "price": "10",
      "quantity": "1"
    }
  ],
  "shippingAddress": {
    "firstName": "some first name",
    "lastName": "some last name",
    "address": "some street",
    "cell": "",
    "phone": "972502457558",
    "zip": "",
    "city": "some city",
    "country": "GB",
    "state": "",
    "email": "someemail@somedomain.com",
    "shippingCounty": ""
  },
  "billingAddress": {
    "firstName": "some first name",
    "lastName": "some last name",
    "address": "some street",
    "cell":"",
    "phone": "972502457558",
    "zip": "",
    "city": "some city",
    "country": "GB",
    "state": "",
    "email": "someemail@somedomain.com",
    "county": ""
  },

  "dynamicDescriptor": {
    "descriptorMerchantName": "merchantName",
    "descriptorMerchantPhone": "merchantPhone"
  },

  "merchantDetails": {
    "customField1": "",
    "customField2": "",
    "customField3": "",
    "customField4": "",
    "customField5": "",
    "customField6": "",
    "customField7": "",
    "customField9": "",
    "customField10": "",
    "customField11": "",
    "customField12": "",
    "customField13": "",
    "customField14": "",
    "customField15": ""
  },
  "customData": "customData",
  "addendums": {
    "localPayment": {
      "nationalId": "012345678",
      "allowInstallments": "true",
      "allowSpecialDebit": "true",
      "maxNumInstallments": "2"
    }
  },
  "urlDetails": {
    "successUrl": "",
    "failureUrl": "",
    "pendingUrl": "",
    "notificationUrl": "",
    "backUrl": ""
  },
  "skipReviewTab": "true",
  "customSiteName": "",
  "merchantLocale": "en_US",
  "encoding": "UTF-8",
  "paymentMethod": "cc_card",
  "paymentMethodMode": "",
  "userToken": "auto",
  "userPaymentOptionId": "",
  "themeId": "",
  "invoiceId": "",
  "webMasterId": "",
  "isNative": "",
  "kyc":"",
  "dateOfBirth":"",
  "building":"",
  "quick_deposit": "",
  "timeStamp": "",
  "checksum": ""
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
Yes
ID of the user in the merchant’s system.
clientUniqueId
String
(45)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
currency
String
(3)
Yes
The three character ISO currency code.
amount
Double
(12)
Yes
The transaction amount.
amountDetails
Class
Yes,
See Description
totalShipping,
totalHandling,
totalDiscount,
totalTax
itemOpenAmount1,
itemMinAmount1,
itemMaxAmount1,
numberOfItems

The items’ and total shipping/handling/discount/tax prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.

If itemOpenAmount1 sent with the value true then need to populate itemMinAmount1, itemMaxAmount1 with the open amount min and max values and also send numberOfItems with suitable value as well as totalShipping, totalHandling, totalDiscount, totalTax with 0 value.
productId
String
(50)
No
Merchant’s product ID.
If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
promoCode
String
(512)
No
This value is a promotional code the merchant can define in order to apply discounts to the products or services.
SafeCharge does not apply any discounts and only passes this field for your records.
To activate this field, need to contact SafeCharge’s integration team at integration@safecharge.com.
items
Class
Yes,
See Description
name(String, 255),
price(String, 10),
quantity(String, 10)

The items’ and total shipping/handling/discount/tax prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.

If the number of items appears in the payment page, it’s value represents the number of items sent in this items block.
shippingAddress
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
cell(String, 18),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
shippingCounty(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
billingAddress
Class
Yes,
See Description
firstName(String, 30),
lastName(String, 40),
address(String, 60),
cell(String, 18),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

These parameters can be defined as mandatory or non mandatory per need by SafeCharge integration team.

Note that, country parameter is always mandatory.
dynamicDescriptor
Class
No
merchantName(String, 25),
merchantPhone(String, 13)

This allows the merchant to define a dynamic descriptor, which will appear in the payment statement. The name field should contain the merchant name. The phone field should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.
merchantDetails
Class
No
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level which is not passed to the payments gateway and is not used for processing.
customData
String
(25)
No
General data about the customer provided by the merchant.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

For example, localPayment addendum includes:
nationalId,
allowInstallments,
allowSpecialDebit,
maxNumInstallments

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s integration team at integration@safecharge.com.
urlDetails
Class
No
successUrl,
failureUrl(String, 1000),
pendingUrl(String, 1000),
notificationUrl(String, 1000),
backUrl(String, 1000)

Each parameter is limited for up to 1000 characters.
skipReviewTab
String
(5)
No
Indicating whether or not to skip the payment page review page. Possible values: true, false.
customeSiteName
String
(50)
No
The merchant’s site name that should replace the default MerchantSite name.
This parameter is useful for merchants operating many websites that are distinguished only by name.
merchantLocale
String
(5)
No
The default language. The current default value is English (for example: for English (US) the value is en_US).
encoding
String
(20)
No
The type of character encoding. Default value is ISO-8859-1.
paymentMethod
String
(256)
No
The type of payment method selected by the customer (pre selected): credit card: cc_card / debit card: dc_card / APM’s: SafeCharge’s unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see APM Unique SafeCharge Names.
paymentMethodMode
String
No
This parameter filters out any payment method that is not the payment method sent in paymentMethod parameter. Possible values: filter or no value at all.
userToken
String
(8)
No
This parameter determines if the payment page requires existing customers to register for each transaction.
When user_token=register, the payment page requires the customer to register even if they have already registered in the system. The previously registered payment methods are deleted.
When user_token=auto, the payment page checks the SafeCharge database to determine if the customer has registered before.
When user_token=readonly, the customer can only select payment methods they have previously used.
When user_token=registeronly, the payment page requires the customer to register (by entering a new payment option) even if they are already registered in the system. No other previously saved payment options are deleted. The payment page does not show any previously saved payment options.
When user_token=readonlyupo, the customer is presented with a single payment option previously saved and specified on the payment page userPaymentOptionId parameter. If payment option parameters need to be completed, they are editable on the payment page (CVV, expired expiration date, etc.).
userPaymentOptionId
String
No
If input parameter userToken=readonlyupo and userPaymentOptionId parameter sent then the consumer is presented only with this userPaymentOption sent that he previously registered with.
themeId
String
No
This parameter is configured per merchant site but if sent as input it overrides the configuration and themeId chosen is presented.
invoiceId
String
(100)
No
A unique invoice identifier provided by the merchant or randomly generated.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
isNative
String
(1)
No
This value determines whether or not the payment method is redirected to appear in a new window (0) or whether it is redirected within the existing window (1).
kyc
String(TBD)
No
This parameter determines the point in time in the customer lifecycle when the KYC checks should be triggered in the hosted payment page.
Possible values:
PreDeposit
postDeposit
preWithdrawal
ekycFlow
String
(TBD)
No
This parameter determines whether eKYC/Pep and sanctions and document verification should be always performed, or if document verification should be performed as a fallback to a technical business failure of eKYC/Pep and sanctions.
Optional values:
CASCADING or empty value
FULL
EKYC_ONLY
DOC_VER_ONLY
ekycType
String
(TBD)
No
This parameter determines the required sub-type of the KYC check.
Optional values:
All
Bureau
PEP_Sanctions
dateOfBirth
String
No
If value sent in kyc parameter, then it is mandatory to send the consumer date of birth as it is required for KYC processing.
building
String
No
If value sent in kyc parameter, then it is mandatory to send the consumer building as it is required for KYC processing.
building should be populated with house number or building name.
quick_deposit
String
(1)
No
This parameter is only relevant for merchants that have been configured by SafeCharge to preform quick deposits.
For more information, please contact SafeCharge’s integration team at integration@safecharge.com
timeStamp
String
(14)
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "paymentPageUrl": "",
  "merchantId": "427583496191624621",
  "merchantSiteId": "142033",
  "userTokenId": "487106",
  "clientUniqueId": "12345",
  "clientRequestId": "1484759782197",
  "internalRequestId": "866",
  "status": "SUCCESS",
  "errCode": "0",
  "reason": "",
  "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
paymentPageUrl
String
The payment page url including parameters.
For example: https://secure.SafeCharge.com/ppp/purchase.do?merchant_id=427583496191624621&merchant_site_id=142033&…
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
ID of the user in merchant system.
clientUniqueId
String
(255)
ID of the transaction in the merchant’s system.
clientRequestId
String
(20)
ID of the API request in the merchant’s system.
internalRequestId
String
(20)
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode
Integer
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
version
String
(10)
The current version of the request. The current version is 1.



/getMerchantPaymentMethods

This method allows the merchant to view the names, IDs and other information regarding the enabled payment methods and APMs, which may be filtered based on country, currency and language. It is used by the merchant mostly to display the available payment methods in its payment page.




Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getMerchantPaymentMethods.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId":"427583496191624621",
    "merchantSiteId":"142033",
    "clientRequestId": "1484759782197",
    "currencyCode":"GBP",
    "countryCode":"GB",
    "type":"DEPOSIT",
    "languageCode":"eng",
    "timeStamp":"20151105021120",
    "checksum":"6133d0fd12e90ff8de5d8ab5e52a8c23"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
(36)
Yes
Session identifier returned by getSessionToken.
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
Integer
(20)
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
currencyCode
String
(20)
No
The three letter ISO currency code that the transaction is to be completed in.
countryCode
String
(2)
No
The two-letter ISO country code the transaction is to be completed in.
languageCode
String
(5)
No
The language the transaction is to be completed in.
type
String
No
The type of the payment methods to be returned. Possible values: DEPOSIT, WITHDRAWAL. If no value sent, then default value is DEPOSIT.
timeStamp
String
(14)
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
{
    "sessionToken": "",
    "merchantId": "",
    "merchantSiteId": "",
    "clientRequestId": "",
    "internalRequestId": "",
    "paymentMethods": [
      {
        "paymentMethod": "cc_card",
        "paymentMethodDisplayName": [
          {
            "language": "en",
            "message": "Credit Card"
          }
        ],
        "isDirect": "true",
        "countries": [
          "US",
          "DE"
        ],
        "currencies": [
          "USD"
        ],
        "logoURL": "",
        "fields": [
          {
            "name": "ccCardNumber",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Card Number"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Number"
              }
            ]
          },
          {
            "name": "ccExpMonth",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Expiration Month"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Expiration Month"
              }
            ]
          },
          {
            "name": "ccExpYear",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Expiration Year"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Expiration Year"
              }
            ]
          },
          {
            "name": "ccNameOnCard",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Name on Card"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Cardholder name as it appears on your credit card"
              }
            ]
          }
        ]
      }
    ],
    "type":"DEPOSIT",
    "status": "",
    "errCode": "",
    "reason": "",
    "version": ""
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
(36)
Session identifier returned by getSessionToken.
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
clientRequestId
String
(20)
ID of the API request in merchant system.
internalRequestID
String
(20)
SafeCharge Internal unique request id (used for reconciliation purposes, etc.).
paymentMethods
Class
paymentMethod(String, 50),
paymentMethodDisplayName {language(String, 2), message(String, 400)},
isDirect(String, 5),
countries(String, 2),
currencies(String, 3),
logoURL(String, 255)

fields:
name(String, 45),
regex(String, 128),
type(String, 45),
validationMessage {language(String, 2), message(String, 400)},
caption {language(String, 2), message(String, 400)}
type
String
The type of the payment methods to be returned. Possible values: DEPOSIT, WITHDRAWAL. If no value sent, then default value is DEPOSIT.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS, ERROR.
errCode
String
(11)
If an error occurred on the request side then an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
version
Integer
(10)
The current version of your request. Current version is 1.

Deprecated Methods

3D Secure is a credit card authentication program offered by Visa and MasterCard meant to reduce fraudulent purchases by verifying the purchaser’s identity during online transactions.

The goal of the 3D Secure program is to authenticate the cardholders’ identity and verify that they are authorised to complete a transaction.

To authenticate online transactions, the cardholder is required to fill in a username and password known only to them.

When 3D Secure is implemented into the payment process, disputed transactions and chargebacks are reduced by shifting the liability of the charge from the merchant to the cardholder.

The 3D secure flow is implemented in the following four stages:
1. dynamic3D method - Provides the merchant with the 3D secure payment data (paRequest), as well as the 3D secure verification page URL (acsUrl) for the card issuer/bank.
2. Merchant required actions - Redirect the user’s browser to the issuing bank’s 3D Secure authentication page (according to the value of the acsUrl parameter). Redirect should be done using POST and sending the parameters paRequest, termUrl to the acsUrl as shown in the HTML example below:

COPIED
1
2
3
4
5
6
7
8
9
<body OnLoad="OnLoadEvent();" >
<form name="mainform" action="ACS_URL" method="POST">
<h1>3D Secure Transactions</h1>
<h3>Click Submit to process your 3D Secure transaction.</h3>
<input type="submit" value="Submit">
<input type="hidden" name="PaReq" value="PAREQ">
<input type="hidden" name="TermUrl" value="TERM_URL">
</form>
</body>



3. Card issuer/bank required actions – Following the successful 3D secure verification, the card issuer/bank redirects the consumer back to the merchant website (using termUrl), performs the needed actions and provides the 3D secure payment data (paResponse).
4. payment3D method - Performs the actual payment transaction.

These four stages are described in detail in the following sections.

/dynamic3D

This is the initial stage of the 3D secure payment process, providing the merchant with the necessary data, and provides the card issuer/bank with the verification page URL.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/dynamic3D.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "isDynamic3D": "1",
    "dynamic3DMode":"",
    "isRebilling":"0",
    "isPartialApproval":"0",
    "currency": "EUR",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "ipAddress"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "shippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "cardData": {
        "cardNumber": "4111111111111111",
        "cardHolderName": "test name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV":"",
        "ccTempToken": ""
    },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503",
        "CVV":"234"
    },
    "relatedTransactionId": "8495798459",
    "addendums": {
        "localPayment":{
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        },
        "airline": {
            "addendumSent":"",
            "pnrCode":"",
            "bookingSystemUniqueId":"",
            "computerizedReservationSystem":"",
            "ticketNumber":"",
            "documentType":"",
            "flightDateUTC":"",
            "issueDate":"",
            "travelAgencyCode":"",
            "travelAgencyName":"",
            "travelAgencyInvoiceNumber":"",
            "travelAgencyPlanName":"",
            "restrictedTicketIndicator":"",
            "issuingCarrierCode":"",
            "isCardholderTraveling":"",
            "passengersCount":"",
            "infantsCount":"",
            "payerPassportId":"",
            "totalFare":"",
            "totalTaxes":"",
            "totalFee":"",
            "boardingFee":"",
            "ticketIssueAddres ":"",
            "passengerDetails": {
                "passengerId":"",
                "passportNumber":"",
                "customerCode":"",
                "frequentFlyerCode":"",
                "title":"",
                "firstName":"",
                "lastName":"",
                "middleName":"",
                "dateOfBirth":"",
                "phoneNumber":""
            },
            "flightLegDetails": {
                "flightLegId":"",
                "airlineCode":"",
                "flightNumber":"",
                "departureDate":"",
                "arrivalDate":"",
                "departureCountry":"",
                "departureCity":"",
                "departureAirport":"",
                "destinationCountry":"",
                "destinationCity":"",
                "destinationAirport":"",
                "legType":"",
                "flightType":"",
                "ticketDeliveryMethod":"",
                "ticketDeliveryRecipient":"",
                "fareBasisCode":"",
                "serviceClass":"",
                "seatClass":"",
                "stopOverCode":"",
                "departureTaxAmount":"",
                "departureTaxCurrency":"",
                "fareAmount":"",
                "feeAmount":"",
                "taxAmount":"",
                "layoutIntegererval":""
            }
        }
    },
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "externalMpi": {
        "isExternalMpi":"0",
        "eci":"",
        "cavv":"",
        "xid":""
    },
    "storedCredentials": {
        "storedCredentialsMode":""
    },
    "customSiteName":"",
    "productId":"",
    "customData":"",
    "externalTokenProvider": {
        "externalTokenProvider":"",
        "mobileToken":""
    },
    "webMasterId":"",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
(36)
Yes
Session identifier returned by the getSessionToken.
orderId
String
(45)
No
The order ID provided by SafeCharge.
This parameter is provided only in cases where this method is called after an Orders Management method.
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
No
ID of the user in the merchant’s system.

If userPaymentOption sent in the request, then it is mandatory to send userTokenId in the request as well.
clientUniqueId
String
(45)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
isDynamic3D
String
(1)
Yes
Always send isDynamic3D = 1.
dynamic3DMode
String
No
In case the merchant wants to force the transaction to go to 3D, send dynamic3DMode = ON.
isRebilling
Integer
(2)
No
This indicates whether this is a regular transaction or a recurring/re-billing transaction.
Possible values:
0 - this is a regular transaction.
1 - this is a recurring/re-billing transaction.
Re-billing can be performed using a userPaymentOptionId or cardData. If done using cardData then it is highly recommended to send it’s relatedTransactionId as well.

Note that: in case isRebilling=1 sent then must also send isDynamic3D=1 and dynamic3DMode=OFF.
isPartialApproval
String
(1)
No
This describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds from the desired payment method.
Partial approval is supported only by SafeCharge acquiring.
In order for partial approval to be available for the merchant it should be configured by SafeCharge’s integration team.
Possible values:
1 - allow partial approval
0 - not allow partial approval
currency
String
(3)
Yes
The three character ISO currency code.
amount
Double
(12)
Yes
The transaction amount.
amountDetails
Class
Yes,
See Description
totalShipping(String, 255),
totalHandling(String, 10),
totalDiscount,
totalTax(String, 10)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
items
Class
Yes,
See Description
name(String, 255),
price(String, 10),
quantity(String, 10)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
deviceDetails
Class
Yes,
See Description
deviceType(String, 10),
deviceName(String, 255),
deviceOS(String, 225),
browser(String, 225),
ipAddress(String, 15)

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized).

ipAddress parameter can be defined as mandatory or non mandatory per need by SafeCharge’s integration team.
userDetails
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
shippingAddress
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
cell(String, 18),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
shippingCounty(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
billingAddress
Class
Yes,
See Description
firstName(String, 30),
lastName(String, 40),
address(String, 60),
cell(String, 18),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

These parameters can be defined as mandatory or non mandatory per need by SafeCharge’s integration team.

Note that, country parameter is always mandatory.

In case billingAddress provided when the user payment option (UPO) created/updated, then it is used for the transaction.
In case billingAddress sent in orders/payments methods request as separate parameter, then it is used for the transaction and after transaction performed overrides the one saved in the UPO.
In case billingAddress was not saved in the UPO, and was not sent in orders/payments methods request as separate parameter, then value from userDetails parameter is used, but billingAddress is not saved in the UPO.
dynamicDescriptor
Class
No
merchantName(String, 25),
merchantPhone(String, 13)

This allows the merchant to define a dynamic descriptor, which will appear in the payment statement. The name field should contain the merchant name. The phone field should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.
merchantDetails
Class
No
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
cardData
Class
No
This may be one of two options:
cardNumber(String, 20),
cardHolderName(String, 70),
expirationMonth(String, 2),
expirationYear(String, 4),
CVV(String, 4)
-OR-
ccTempToken(String, 45),
CVV(String, 4),
cardHolderName(String, 70)

This is mandatory if the userPaymentOption (below) is not sent.

CVV can be mandatory or non-mandatory per configuration.

If CVV not required need to send it with NULL value or not provide CVV parameter at all in the request.

Please avoid sending card which was expired as it will cause a risk in transaction being declined.
userPaymentOption
Class
No
userPaymentOptionId(String, 45),
CVV(String, 4)

On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.

This is mandatory if the cardData (above) is not sent.

CVV can be mandatory or non-mandatory per configuration.
relatedTransactionId
String
(19)
Yes,
See Description
The ID of the original transaction. It is required in case recurring/re-billing transaction was requested (isRebilling=1 sent) using cardData and not using userPaymentOptionId.

The value sent must contain digit characters only, meaning this string value can not contain any character that is not a digit.
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

For example, localPayment addendum includes:
nationalId(String, 255),
debitType(String, 255),
firstInstallment(String, 255),
periodicalInstallment(String, 255),
numberOfInstallments(String, 255)

Please note that the possible values for the debitType parameter are:
'1’ - Singular payment.
'2’ - Instalments.
'3’ - Special debit.

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.

For example, airline addendum includes:
addendumSent(String),
pnrCode(String),
bookingSystemUniqueId(String),
computerizedReservationSystem(String),
ticketNumber(String),
documentType(String),
flightDateUTC(String),
issueDate(String),
travelAgencyCode(String),
travelAgencyName(String),
travelAgencyInvoiceNumber(String),
travelAgencyPlanName(String),
restrictedTicketIndicator(String),
issuingCarrierCode(String),
isCardholderTraveling(String),
passengersCount(String),
infantsCount(String),
payerPassportId(String),
totalFare(String),
totalTaxes(String),
totalFee(String),
boardingFee(String),
ticketIssueAddres(String),
passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)},
flightLegDetails {flightLegId(String), airlineCode(S, flightNumber(String), departureDate(String), arrivalDate(String), departureCountry(String), departureCity(String), departureAirport(String), destinationCountry(String), destinationCity(String), destinationAirport(String), legType(String), flightType(String), ticketDeliveryMethod(String), ticketDeliveryRecipient(String), fareBasisCode(String), serviceClass(String), seatClass(String), stopOverCode(String), departureTaxAmount(String), departureTaxCurrency(String), fareAmount(String), feeAmount(String), taxAmount(String), layoutIntegererval(String)}

For cards, while working in Auth-Settle mode, the Auth is done using this API call and settle is done in a separate clearing batch process.

For more information and for required SafeCharge configurations settings, please contact SafeCharge’s Integration Team at integration@safecharge.com.
urlDetails
Class
No
notificationUrl(String, 1000)

This parameter determines where to return the DMN.
Each parameter is limited for up to 1000 characters.
externalMpi
Class
No
isExternaMpi(String, 1),
eci(String, 2),
cavv(String, 50),
xid(String, 50)

Allow the merchant to provide the 3D Secure authentication result as input.

isExternalMpi possible values:
1 - external MPI is used (in this case need to send eci, cavv, xid values obtained from the external MPI).
0 - external MPI is not used.

Note that: eci is the The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated; ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program; ECI = 7: payment authentication was not performed, cavv is the card holder authentication verification value, xid is the transaction identification value.

Note that: in case isExternalMpi=1 sent then must also send isDynamic3D=1 and dynamic3DMode=OFF.
storedCredentials
Class
No
storedCredentialsMode

This parameter shows whether or not stored tokenized card data is sent to execute the transaction.
Possible values:
0 - The card data was entered for the first time, and, upon completion of the transaction, is tokenized and stored for future transactions.
1 - Previously tokenized and stored card data was used to perform the transaction.
This parameter is only applicable to merchants that store tokenized card data and is mandatory when cardData->cardNumber parameter is populated and sent. Merchants that do not store card data, or that are using SafeCharge’s tokenization feature, should not send this parameter.
customSiteName
String
(50)
No
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId
String
(50)
No
A free text field used to identify the product/service sold.
If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
externalTokenProvider
Class
No
externalTokenProvider(String, 45),
mobileToken(String, 5000)

External token provider is a type of entity in the payment industry with its own flow. For example: ApplePay.
For ApplePay it is required to pass on the values:
externalTokenProvider - “ApplePay”,
mobileToken - the token received from Apple during the following: Dynamic Server to Server JS Button Solution.
In order to work with external token providers special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
timeStamp
String
(14)
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "threeDFlow": "0",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "",
    "gwErrorCode": "0",
    "gwErrorReason": "",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "eci": "",
    "threeDReason": "",
    "paRequest": "",
    "acsUrl": "www.issuer3Dsite.com",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    },
    "partialApprovalDetails":{
        "isPartialApproval": "",
        "amountInfo":{
            "requestedAmount": "",
            "requestedCurrency": "",
            "processedAmount": "",
            "processedCurrency": ""
        }
    },
    "cvv2Reply":"",
    "avsCode":"",
    "transactionType":"",
    "customData":"",
    "fraudDetails":{
        "finalDecision":"",
        "recommendations": "",
        "system":{
            "systemId":"1",
            "systemName":"SafeCharge",
            "decision":"",
            "rules":[{
               "ruleId": "",
               "ruleDescription":""
            }]
        }
    }
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
(36)
Session identifier returned by getSessionToken.
orderId
String
(20)
The order ID provided by SafeCharge.
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
ID of the user in the merchant’s system.
clientUniqueId
String
(255)
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(20)
ID of the API request in the merchant’s system.
internalRequestId
String
(20)
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
threeDFlow
String
If the value sent in isDynamic3D input parameter equals 1 (i.e. 3D Secure was configured to be managed by SafeCharge’s Rules Engine) then this parameter indicates whether the performed transaction was auth3D (1), or whether the performed transaction was auth/sale(0). For the merchant required actions once the response is received, see Possible Scenarios Table.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
(20)
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
merchantDetails
Class
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It isnot passed to the payments gateway and is not used for processing.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side. When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
(10)
The current version of the request. The current version is 1.
userPaymentOptionId
String
(45)
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
transactionId
String
(20)
The gateway transaction ID.
authCode
String
(128)
Authorization code of the transaction.
paRequest
String
The 3D secure request data for the card issuer/bank.
acsUrl
String
URL/endpoint used to redirect the consumer to the card issuer/bank’s 3D secure verification page.
externalToken
Class
externalToken_blockedCardSt(String),
externalToken_cardAcquirerId(String),
externalToken_cardAcquirerName(String),
externalToken_cardBin(String),
externalToken_cardBrandId(String),
externalToken_cardBrandName(String),
externalToken_cardExpiration(String),
externalToken_cardLength(String),
externalToken_cardMask(String),
externalToken_cardName(String),
externalToken_cardTypeId(String),
externalToken_cardTypeName(String),
externalToken_clubName(String),
externalToken_creditCompanyId(String),
externalToken_creditCompanyName(String),
externalToken_extendedCardType(String),
externalToken_Indication(String),
externalToken_tokenValue(String),
externalToken_tokenProvider(String)

Parameters arriving from a third-party payment provider that also generate card tokens (currently relevant only to CreditGuard as third party payment provider which generate card tokens).
partialApprovalDetails
Class
isPartialApproval(String, True or False),
amountInfo: requestedAmount(String), requestedCurrency(String), processedAmount(String), processedCurrency(String)

These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.
eci
String
This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed.

The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated; ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program; ECI = 7: payment authentication was not performed.

Note that, in this method eci will be returned in response only in case its value is 1 or 6 or 7.
threeDReason
String
If the attempt failed this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
cvv2Reply
String
The CVV2 response. Possible values:
M = CVV2 Match.
N = CVV2 No Match.
P = Not Processed.
U = Issuer is not certified and/or has not.
provided Visa the encryption keys.
S = CVV2 processor is unavailable.
avsCode
String
The AVS response. Possible values:
A = The street address matches, the zip code does not.
W = Whole 9-digits zip code match, the street address does not.
Y = Both the 5-digits zip code and the street address match.
X = An exact match of both the 9-digits zip code and the street address.
Z = Only the 5-digits zip code match, the street code does not.
U = Issuer is unavailable.
S = Not Supported.
R = Retry.
B = Not authorized (declined).
N = Both street address and zip code do not match.
transactionType
String
(45)
The type of transaction; Auth3D or Sale or Auth. (See Glossary for more details about Auth3D, Sale, Auth transactions.)
Note that, this require the merchant to be configured to gateway version 4.1.2 and up, For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
customData
String
(255)
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
fraudDetails
Class
finalDecision(String),
recommendations(String),
system{systemId(String), systemName(String), decision(String), rules[ruleId(String), ruleDescription(String)]}

system - Which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
rules - The risk management system rules triggered by the transaction.
decision - The risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter:
1. “Accept” The risk management system accepts the transactions.
2. “Reject” The risk management system rejects the transaction. The transaction not passed to bank for authorization. The reasons returned in ruleDescription parameter.
3. “Review” The risk management system flags a transaction for review but still accept the transaction.
4. “Error” An error occurred during risk management system operation. The gateway continues to process the transaction through the bank.
5. “None” No risk analysis was performed. The gateway continues to process the transaction through the bank.
finalDecision - when deciding whether to accept or reject a transaction, the risk Management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision is to accept the transaction. If at least one of the rules leads to a Reject decision, the finalDecision is to reject the transaction.

In order to receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.



Possible Scenarios Table

The below describes possible scenarios for this method and the merchant’s required actions after receiving the method’s response:

Possible Scenarios for Dynamic 3D (isDynamic3D = 1)

Possible Scenario Parameter Values Meaning Merchant Required Action
1
Input:
isDynamic3D = 1 and
Output:
acsUrl is returned and threeDFlow = 1
auth3D transaction was performed successfully (3D Secure managed by SafeCharge’s rule engine) and the card is enrolled to 3D OR card is not enrolled for 3D, but the issuer allows registration.
1. Merchant should redirect to acsUrl.
2. Merchant should call payment3D method afterwards.
2
Input:
isDynamic3D = 1 and
Output:
acsUrl is NOT returned and threeDFlow = 1
auth3D transaction was performed successfully (3D Secure managed by SafeCharge’s rule engine) and the card is NOT enrolled for 3D.
1. Merchant should NOT redirect to acsUrl.
2. Merchant should call payment3D method (The performed transaction is 'sale’ in order to complete the 'auth3D’ transaction previously performed in dynamic3D method).
3
Input:
isDynamic3D = 1 and
Output:
acsUrl is NOT returned and threeDFlow = 0
The performed transaction in dynamic3D is 'sale’ or 'auth’, depending on the merchant’s configured mode of operation.
If the merchant’s configured mode of operation is sale, then no further action is required.
If the merchant’s configured mode of operation is auth-settle, then the merchant should call settleTransaction method afterwards.



/payment3D

This final stage performs the actual payment transaction.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/payment3D.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "transactionType": "Auth",
    "isPartialApproval": "0",
    "currency": "EUR",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "ipAddress"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "shippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "addendums":{
        "localPayment":{
            "nationalId":"012345678",
            "debitType":"1",
            "firstInstallment":"",
            "periodicalInstallment":"",
            "numberOfInstallments":""
        },
        "airline": {
            "addendumSent":"",
            "pnrCode":"",
            "bookingSystemUniqueId":"",
            "computerizedReservationSystem":"",
            "ticketNumber":"",
            "documentType":"",
            "flightDateUTC":"",
            "issueDate":"",
            "travelAgencyCode":"",
            "travelAgencyName":"",
            "travelAgencyInvoiceNumber":"",
            "travelAgencyPlanName":"",
            "restrictedTicketIndicator":"",
            "issuingCarrierCode":"",
            "isCardholderTraveling":"",
            "passengersCount":"",
            "infantsCount":"",
            "payerPassportId":"",
            "totalFare":"",
            "totalTaxes":"",
            "totalFee":"",
            "boardingFee":"",
            "ticketIssueAddres ":"",
            "passengerDetails": {
                "passengerId":"",
                "passportNumber":"",
                "customerCode":"",
                "frequentFlyerCode":"",
                "title":"",
                "firstName":"",
                "lastName":"",
                "middleName":"",
                "dateOfBirth":"",
                "phoneNumber":""
            },
            "flightLegDetails": {
                "flightLegId":"",
                "airlineCode":"",
                "flightNumber":"",
                "departureDate":"",
                "arrivalDate":"",
                "departureCountry":"",
                "departureCity":"",
                "departureAirport":"",
                "destinationCountry":"",
                "destinationCity":"",
                "destinationAirport":"",
                "legType":"",
                "flightType":"",
                "ticketDeliveryMethod":"",
                "ticketDeliveryRecipient":"",
                "fareBasisCode":"",
                "serviceClass":"",
                "seatClass":"",
                "stopOverCode":"",
                "departureTaxAmount":"",
                "departureTaxCurrency":"",
                "fareAmount":"",
                "feeAmount":"",
                "taxAmount":"",
                "layoutIntegererval":""
            }
        }
    },
    "cardData": {
        "cardNumber": "4111111111111111",
        "cardHolderName": "some name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV": "122",
        "ccTempToken": ""
    },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503",
        "CVV":"234"
    },
    "paResponse": "",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "storedCredentials": {
        "storedCredentialsMode":""
    },
    "customSiteName":"",
    "productId":"",
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
(36)
Yes
Session identifier returned by the getSessionToken.
It is required to provide the same sessionToken value sent to dynamic3D method that was celled before.
orderId
String
(45)
Yes
The order ID provided by SafeCharge.
It is required to provide the orderId value returned by dynamic3D method that was called before.
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
No
ID of the user in the merchant’s system.

If userPaymentOption sent in the request, then it is mandatory to send userTokenId in the request as well.
clientUniqueId
String
(45)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
transactionType
String
(45)
Yes
The type of transaction; Sale or Auth. (See Glossary for more details about Auth and Sale transactions.)
isPartialApproval
String
(1)
No
This describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds from the desired payment method.
Partial approval is supported only by SafeCharge acquiring.
In order for partial approval to be available for the merchant it should be configured by SafeCharge’s integration team.
Possible values:
1 - allow partial approval
0 - not allow partial approval
currency
String
(3)
Yes
The three character ISO currency code.
amount
Double
(12)
Yes
The transaction amount. This amount must be identical to the amount listed in the dynamic3D.
amountDetails
Class
Yes,
See Description
totalShipping(String),
totalHandling(String),
totalDiscount(String),
totalTax(String)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
items
Class
Yes,
See Description
name(String, 255),
price(String, 10),
quantity(String, 10)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
deviceDetails
Class
Yes,
See Description
deviceType(String, 10),
deviceName(String, 255),
deviceOS(String, 255),
browser(String, 255),
ipAddress(String, 15)

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized).

ipAddress parameter can be defined as mandatory or non mandatory per need by SafeCharge integration team.
userDetails
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
shippingAddress
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
shippingCounty(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
billingAddress
Class
Yes,
See Description
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

These parameters can be defined as mandatory or non mandatory per need by SafeCharge integration team.

Note that, country parameter is always mandatory.

In case billingAddress provided when the user payment option (UPO) created/updated, then it is used for the transaction.
In case billingAddress sent in orders/payments methods request as separate parameter, then it is used for the transaction and after transaction performed overrides the one saved in the UPO.
In case billingAddress was not saved in the UPO, and was not sent in orders/payments methods request as separate parameter, then value from userDetails parameter is used, but billingAddress is not saved in the UPO.
dynamicDescriptor
Class
No
merchantName(String, 25),
merchantPhone(String, 13)

This allows the merchant to define a dynamic descriptor, which will appear in the payment statement. The name field should contain the merchant name. The phone field should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.

If you work in a Sale mode then you must provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
merchantDetails
Class
No
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

For example, localPayment addendum includes:
nationalId(String, 255),
debitType(String, 255),
firstInstallment(String, 255),
periodicalInstallment(String, 255),
numberOfInstallments(String, 255)

Please note that the possible values for the debitType parameter are:
'1’ - Singular payment.
'2’ - Instalments.
'3’ - Special debit.

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.

For example, airline addendum includes:
addendumSent(String),
pnrCode(String),
bookingSystemUniqueId(String),
computerizedReservationSystem(String),
ticketNumber(String),
documentType(String),
flightDateUTC(String),
issueDate(String),
travelAgencyCode(String),
travelAgencyName(String),
travelAgencyInvoiceNumber(String),
travelAgencyPlanName(String),
restrictedTicketIndicator(String),
issuingCarrierCode(String),
isCardholderTraveling(String),
passengersCount(String),
infantsCount(String),
payerPassportId(String),
totalFare(String),
totalTaxes(String),
totalFee(String),
boardingFee(String),
ticketIssueAddres(String),
passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)},
flightLegDetails {flightLegId(String), airlineCode(S, flightNumber(String), departureDate(String), arrivalDate(String), departureCountry(String), departureCity(String), departureAirport(String), destinationCountry(String), destinationCity(String), destinationAirport(String), legType(String), flightType(String), ticketDeliveryMethod(String), ticketDeliveryRecipient(String), fareBasisCode(String), serviceClass(String), seatClass(String), stopOverCode(String), departureTaxAmount(String), departureTaxCurrency(String), fareAmount(String), feeAmount(String), taxAmount(String), layoutIntegererval(String)}

For cards, while working in Auth-Settle mode, the Auth is done using this API call and settle is done in a separate clearing batch process.

For more information and for required SafeCharge configurations settings, please contact SafeCharge’s Integration Team at integration@safecharge.com.
cardData
Class
No
This may be one of two options:
cardNumber(String, 20),
cardHolderName(String, 70),
expirationMonth(String, 2),
expirationYear(String, 4),
CVV(String, 4)
-OR-
ccTempToken(String, 45),
CVV(String, 4),
cardHolderName(String, 70)

This is mandatory if the userPaymentOption (below) is not sent.

CVV can be mandatory or non-mandatory per configuration.

If CVV not required need to send it with NULL value or not provide CVV parameter at all in the request.

Please avoid sending card which was expired as it will cause a risk in transaction being declined.
userPaymentOption
Class
No
userPaymentOptionId(String, 45),
CVV(String, 4)

On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.

This is mandatory if the cardData (above) is not sent.

CVV can be mandatory or non-mandatory per configuration.
paResponse
String
Yes
The payment authorization response returned by the card issuer/bank.
urlDetails
Class
No
notificationUrl(String, 1000)

This parameter determines where to return the DMN.
Each parameter is limited for up to 1000 characters.
storedCredentials
Class
No
storedCredentialsMode

This parameter shows whether or not stored tokenized card data is sent to execute the transaction.
Possible values:
0 - The card data was entered for the first time, and, upon completion of the transaction, is tokenized and stored for future transactions.
1 - Previously tokenized and stored card data was used to perform the transaction.
This parameter is only applicable to merchants that store tokenized card data and is mandatory when cardData->cardNumber parameter is populated and sent. Merchants that do not store card data, or that are using SafeCharge’s tokenization feature, should not send this parameter.
customSiteName
String
(50)
No
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId
String
(50)
No
A free text field used to identify the product/service sold.
If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
timeStamp
String
(14)
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "",
    "gwErrorCode": "0",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "eci": "",
    "threeDReason": "",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    },
    "partialApprovalDetails":{
        "isPartialApproval": "",
        "amountInfo":{
            "requestedAmount": "",
            "requestedCurrency": "",
            "processedAmount": "",
            "processedCurrency": ""
        }
    },
    "cvv2Reply":"",
    "avsCode":"",
    "transactionType":"",
    "customData":"",
    "fraudDetails":{
        "finalDecision":"",
        "recommendations": "",
        "system":{
            "systemId":"1",
            "systemName":"SafeCharge",
            "decision":"",
            "rules":[{
               "ruleId": "",
               "ruleDescription":""
            }]
        }
    }
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
(36)
Session identifier returned by getSessionToken.
orderId
String
(20)
The order ID provided by SafeCharge.
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
ID of the user in the merchant’s system.
clientUniqueId
String
(255)
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(20)
ID of the API request in the merchant’s system.
internalRequestId
String
(20)
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
(20)
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
merchantDetails
Class
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side. When a transaction is successful, this field is 0.
When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
(10)
The current version of the request. The current version is 1.
userPaymentOptionId
String
(45)
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
transactionId
String
(20)
The gateway transaction ID.
authCode
String
(128)
Authorization code of the transaction.
eci
String
This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed.

The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated; ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program; ECI = 7: payment authentication was not performed.
threeDReason
String
If the attempt failed this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
externalToken
Class
externalToken_blockedCard(String),
externalToken_cardAcquirerId(String),
externalToken_cardAcquirerName(String),
externalToken_cardBin(String),
externalToken_cardBrandId(String),
externalToken_cardBrandName(String),
externalToken_cardExpiration(String),
externalToken_cardLength(String),
externalToken_cardMask(String),
externalToken_cardName(String),
externalToken_cardTypeId(String),
externalToken_cardTypeName(String),
externalToken_clubName(String),
externalToken_creditCompanyId(String),
externalToken_creditCompanyName(String),
externalToken_extendedCardType(String),
externalToken_Indication(String),
externalToken_tokenValue(String),
externalToken_tokenProvider(String)

Parameters arriving from a third-party payment provider that also generate card tokens (currently relevant only to CreditGuard as third party payment provider which generate card tokens).
partialApprovalDetails
Class
isPartialApproval(String, True or False),
amountInfo: requestedAmount(String), requestedCurrency(String), processedAmount(String), processedCurrency(String)

These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.
cvv2Reply
String
CVV2 (card verification value) response. Possible values:
M = CVV2 Match
N = CVV2 No Match
P = Not Processed
U = Issuer is not certified and/or has not provided Visa the encryption keys.
S = CVV2 processor is unavailable.
avsCode
String
The AVS (address verification) response. The following values may be returned:
A = The street address matches, the ZIP code does not.
W = Whole 9-digits ZIP code match, the street address does not.
Y = Both the 5-digits ZIP code and the street address match.
X = An exact match of both the 9-digits ZIP code and the street address.
Z = Only the 5-digits ZIP code match, the street code does not.
U = Issuer Unavailable
S = Not Supported
R = Retry
B = Not Authorized (declined)
N = Both street address and ZIP code do not match.
transactionType
String
(45)
The type of transaction; Sale or Auth. (See Glossary for more details about Auth and Sale transactions.)
Note that, this require the merchant to be configured to gateway version 4.1.2 and up, For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
customData
String
(255)
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
fraudDetails
Class
finalDecision(String),
recommendations(String),
system{systemId(String), systemName(String), decision(String), rules[ruleId(String), ruleDescription(String)]}

system - Which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
rules - The risk management system rules triggered by the transaction.
decision - The risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter:
1. “Accept” The risk management system accepts the transactions.
2. “Reject” The risk management system rejects the transaction. The transaction not passed to bank for authorization. The reasons returned in ruleDescription parameter.
3. “Review” The risk management system flags a transaction for review but still accept the transaction.
4. “Error” An error occurred during risk management system operation. The gateway continues to process the transaction through the bank.
5. “None” No risk analysis was performed. The gateway continues to process the transaction through the bank.
finalDecision - when deciding whether to accept or reject a transaction, the risk Management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision is to accept the transaction. If at least one of the rules leads to a Reject decision, the finalDecision is to reject the transaction.

In order to receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.

/paymentCC

This method is used for performing credit card payments, using a card number, credit card, temporary token or user payment option.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/paymentCC.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "transactionType": "Auth",
    "isRebilling": "0",
    "isPartialApproval": "0",
    "currency": "EUR", 
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
    "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "192.168.0.1"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "shippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "addendums": {
        "localPayment":{
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        },
        "cardPresentPointOfSale":{
            "terminalId": "",
            "trackData": "",
            "trackType": "",
            "icc": "",
            "pinData": "",
            "entryMode": "",
            "terminalCapability": "",
            "terminalAttendance": "",
            "cardSequenceNum": "",
            "offlineResCode": "",
            "localTime": "",
            "localDate": "",
            "cvMethod": "",
            "cvEntity": "",
            "outputCapability": "",
            "autoReversal": "",
            "autoReversalAmount": "",
            "autoReversalCurrency": "",
            "channel": "3",
            "suppressAuth": "",
            "terminalCity": "",
            "terminalAddress": "",
            "terminalCountry": "",
            "terminalZip": "",
            "terminalState": "",
            "terminalModel": "",
            "terminalManufacturer": "",
            "terminalMacAddress": "",
            "terminalKernel": "",
            "terminalImei": "",
            "mobileTerminal": ""
        },
        "airline": {
            "addendumSent":"",
            "pnrCode":"",
            "bookingSystemUniqueId":"",
            "computerizedReservationSystem":"",
            "ticketNumber":"",
            "documentType":"",
            "flightDateUTC":"",
            "issueDate":"",
            "travelAgencyCode":"",
            "travelAgencyName":"",
            "travelAgencyInvoiceNumber":"",
            "travelAgencyPlanName":"",
            "restrictedTicketIndicator":"",
            "issuingCarrierCode":"",
            "isCardholderTraveling":"",
            "passengersCount":"",
            "infantsCount":"",
            "payerPassportId":"",
            "totalFare":"",
            "totalTaxes":"",
            "totalFee":"",
            "boardingFee":"",
            "ticketIssueAddres ":"",
            "passengerDetails": {
                "passengerId":"",
                "passportNumber":"", 
                "customerCode":"", 
                "frequentFlyerCode":"", 
                "title":"", 
                "firstName":"", 
                "lastName":"", 
                "middleName":"", 
                "dateOfBirth":"", 
                "phoneNumber":""
            },
            "flightLegDetails": {
                "flightLegId":"", 
                "airlineCode":"", 
                "flightNumber":"", 
                "departureDate":"", 
                "arrivalDate":"", 
                "departureCountry":"", 
                "departureCity":"", 
                "departureAirport":"", 
                "destinationCountry":"", 
                "destinationCity":"", 
                "destinationAirport":"", 
                "legType":"", 
                "flightType":"", 
                "ticketDeliveryMethod":"", 
                "ticketDeliveryRecipient":"", 
                "fareBasisCode":"", 
                "serviceClass":"",
                "seatClass":"", 
                "stopOverCode":"", 
                "departureTaxAmount":"", 
                "departureTaxCurrency":"", 
                "fareAmount":"",
                "feeAmount":"",
                "taxAmount":"",
                "layoutIntegererval":""
            }
        }
    },
        "cardData": {
                "cardNumber": "5101080963349948",
                "cardHolderName": "test name",
                "expirationMonth": "01",
                "expirationYear": "2020",
                "CVV": "122"
        },
    "userPaymentOption":{
        "userPaymentOptionId":"",
        "CVV":""
    },
    "relatedTransactionId": "8495798459",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "externalMpi": {
        "isExtenalMpi":"0",
        "eci":"",
        "cavv":"",
        "xid":""
    },
    "storedCredentials": {
        "storedCredentialsMode":""
    },
    "customSiteName":"",
    "productId":"",
    "customData":"",
    "externalTokenProvider": {
        "externalTokenProvider":"",
        "mobileToken":""
    },
    "webMasterId":"",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
(36)
Yes
Session identifier returned by the getSessionToken.
orderId
String
(45)
No
The order ID provided by SafeCharge.
This parameter is provided only in cases where this method is called after an Orders Management method.
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
No
ID of the user in the merchant’s system.

If userPaymentOption sent in the request, then it is mandatory to send userTokenId in the request as well.
clientUniqueId
String
(45)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
transactionType
String
(45)
Yes
The type of transaction; Sale or Auth. (See Glossary for more details about Auth and Sale transactions.)
isRebilling
Integer
(2)
No
This indicates whether this is a regular transaction or a recurring/re-billing transaction.
Possible values:
0 - this is a regular transaction.
1 - this is a recurring/re-billing transaction.
Re-billing can be performed using a userPaymentOptionId or cardData. If done using cardData then it is highly recommended to send it’s relatedTransactionId as well.
isPartialApproval
String
(1)
No
This describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds from the desired payment method.
Partial approval is supported only by SafeCharge acquiring.
In order for partial approval to be available for the merchant it should be configured by SafeCharge’s integration team.
Possible values:
1 - allow partial approval.
0 - not allow partial approval.
currency
String
(3)
Yes
The three character ISO currency code.
amount
Double
(12)
Yes
The transaction amount.
amountDetails
Class
Yes,
See Description
totalShipping(String),
totalHandling(String),
totalDiscount(String),
totalTax(String)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
items
Class
Yes,
See Description
name(String, 255),
price(String, 10),
quantity(String, 10)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
deviceDetails
Class
Yes, See Description
deviceType(String, 10),
deviceName(String, 255),
deviceOS(String, 255),
browser(String, 255),
ipAddress(String, 15)

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognized).

ipAddress parameter can be defined as mandatory or non mandatory per need by SafeCharge integration team.
userDetails
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
shippingAddress
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
shippingCounty(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
billingAddress
Class
Yes,
See Description
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

These parameters can be defined as mandatory or non mandatory per need by SafeCharge integration team.

Note that, country parameter is always mandatory.

In case billingAddress provided when the user payment option (UPO) created/updated, then it is used for the transaction.
In case billingAddress sent in orders/payments methods request as separate parameter, then it is used for the transaction and after transaction performed overrides the one saved in the UPO.
In case billingAddress was not saved in the UPO, and was not sent in orders/payments methods request as separate parameter, then value from userDetails parameter is used, but billingAddress is not saved in the UPO.
dynamicDescriptor
Class
No
merchantName(String, 25),
merchantPhone(String, 13)

This allows the merchant to define a dynamic descriptor, which will appear in the payment statement. The name field should contain the merchant name. The phone field should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.

If you work in a Sale mode then you must provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
merchantDetails
Class
No
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
cardData
Class
No
This may be one of two options:
cardNumber(String, 20),
cardHolderName(String, 70),
expirationMonth(String, 2),
expirationYear(String, 4),
CVV(String, 4)
-OR-
ccTempToken(String, 45),
CVV(String, 4),
cardHolderName(String, 70)

This is mandatory if the userPaymentOption (below) is not sent.

CVV can be mandatory or non-mandatory per configuration.

If CVV not required need to send it with NULL value or not provide CVV parameter at all in the request.

Please avoid sending card which was expired as it will cause a risk in transaction being declined.
userPaymentOption
Class
No
userPaymentOptionId(String, 45),
CVV(String, 4)

On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.

This is mandatory if the cardData (above) is not sent.

CVV can be mandatory or non-mandatory per configuration.
relatedTransactionId
String
(19)
Yes,
See Description
The ID of the original transaction. It is required in case recurring/re-billing transaction was requested (isRebilling=1 sent) using cardData and not using userPaymentOptionId.

The value sent must contain digit characters only, meaning this string value can not contain any character that is not a digit.
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

For example, localPayment addendum includes:
nationalId(String, 255),
debitType(String, 255),
firstInstallment(String, 255),
periodicalInstallment(String, 255),
numberOfInstallments(String, 255)

Please note that the possible values for the debitType parameter are:
'1’ - Singular payment.
'2’ - Instalments.
'3’ - Special debit.

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.

For example, cardPresentPointOfSale addendum includes:
terminalId(String),
trackData(String),
trackType(String),
icc(String),
pinData(String),
entryMode(String),
terminalCapability(String),
terminalAttendance(String),
cardSequenceNum(String),
offlineResCode(String),
localTime(String),
localDate(String),
cvMethod(String),
cvEntity(String),
outputCapability(String),
autoReversal(String),
autoReversalAmount(String),
autoReversalCurrency(String),
channel(String),
suppressAuth(String),
terminalCity(String),
terminalAddress(String),
terminalCountry(String),
terminalZip(String),
terminalState(String),
terminalModel(String),
terminalManufacturer(String),
terminalMacAddress(String),
terminalKernel(String),
terminalImei(String),
mobileTerminal(String)

Card Present/Point Of Sale transactions are when an employee and the customer are present in the same physical location. The card data can be collected by a card reader through various means such as a magnetic strip or chip (manual entry is also possible). The card reader device reads the magnetic stripe on the back of the card or chip and the reader or your application connected to the reader submits the encoded information to your terminal management server that passes the information to the API. Following SafeCharge’s response, when approved, the merchant can print a receipt for the customer.

The following are the possible types of Card Present/Point Of Sale physical ways for initiation:
Available for immediate merchant integration:
1.Manual (key-entered): Card data was not obtained via the chip or magnetic stripe on the Card, for example, when the transaction is a Mail/Phone Order Transaction, Electronic Commerce Transaction, Recurring Transaction, voice authorised, or when the Chip or magnet stripe on the Card cannot be read. Represented by posEntryMode=1.
2.Magnetic Stripe (swiped): Card data was obtained via the magnetic stripe on the card via swipe. Represented by posEntryMode=2.
Will require merchant implementing this API which supports card present in its hardware terminals:
3.ICC Read (chip): Card data was obtained via chip on the card, but does not include PIN entry data by the customer. Represented by posEntryMode=3.
4.Contactless ICC: Card data was obtained via chip on the card that was obtained through a contactless device-read. Represented by posEntryMode=5.
5.Contactless magstripe: Card data was obtained via equivalent track 2 data in ICC block on the Card, originated in contactless device-read. Represented by posEntryMode=6.
Currently not supported by SafeCharge:
6.ICC Read (chip) + PIN: Card data was obtained via chip on the card, and includes PIN entry data by the customer.

Note that, for Card Present/Point Of Sale processing, it is mandatory to send channel parameter with value 3.

Note that, an EMV chip can is a contactless card where the chip embedded into the card or smart phone and is placed on or near the terminal. The data collected from the chip must be encoded in TLV (tag-length-value) format. After a merchant has encoded the data, need to pass it to SafeCharge as the value of the parameter posIcc which is a variable length parameter (LLLVAR).
While full list of EMV tags you can include in the request appear here, below is a list of the mandatory tags:
9F26 (mandatory): Application cryptogram. This field contains the cryptogram used while authenticating the transaction. This data field contains an Authorization Request Cryptogram (ARQC), transaction certificate (TC), or an application authentication Cryptogram (AAC). In general, an ARQC means that the card determined that the transaction should be sent online, a TC indicates that the transaction was approved offline, and an AAC indicates that the transaction was declined offline. Example: E57BA2A13A84AA19
9F27 (mandatory for MasterCard transactions (authorization + settlement)): Cryptogram Information. This field indicates the type of cryptogram and the actions to be performed by the terminal. Example: 80
9F10 (mandatory): Issuer Application Data. This field contains application data transmitted from the chip to the issuer and is updated by the issuer in the response message. Card Verification Result (CVR) Example: 06010A03A06002
9F37 (mandatory): Unpredictable Number. This field contains an unpredictable number value generated by the POS terminal that is to be used as input to the application cryptogram algorithm. Example: DA00A010
9F36 (mandatory for Visa Mandatory for MC authorization): Application Transaction Counter. This field contains a counter maintained by the application in the ICC (incrementing the ATC is managed by the ICC) Example: 0B0E
95 (mandatory): Terminal Verification Relts (TVR). The TVR is a series of bits set by the terminal reading an EMV card, based on logical tests (for example has the card expired). This data object is used in the terminal’s decision whether to accept, decline or go on-line for a payment transaction. Example: 0000008000
9A (mandatory): Transaction Date. This field contains the local date that the transaction was performed. Example: 151102
9C (mandatory): Transaction Type. This field Indicates the type of transaction, represented by the values of the first two digits of Processing Code as defined by the payment system. Example: 00
9F02 (mandatory): Amount Authorized. This field contains the authorised amount of the transaction (excluding adjustments). Example: 000000001500
5F2A (mandatory): Transaction Currency Code. This field contains the currency code of the transaction according to ISO 4217. Example: 0978
82 (mandatory): Application Interchange Profile. This field indicates the capabilities of the card to support specific functions in the application. Example: 3C00
9F1A (mandatory): Terminal Country Code. This field indicates the country of the terminal, represented according to ISO 3166. Example: 0376
9F34 (mandatory for MC authorization only): Cardholder Verification Method (CVM) Results. This field indicates the results of the last CVM performed. Example: 1F0002
9F33 (mandatory for Visa): Terminal Capabilities. This field indicates the card data input, CVM, and security capabilities of the Terminal. Example: 6008C8
84 (mandatory for MasterCard): Dedicated File.

For more information and for required SafeCharge configurations settings, please contact SafeCharge’s Integration Team at integration@safecharge.com.

For example, airline addendum includes:
addendumSent(String),
pnrCode(String),
bookingSystemUniqueId(String),
computerizedReservationSystem(String),
ticketNumber(String),
documentType(String),
flightDateUTC(String),
issueDate(String),
travelAgencyCode(String),
travelAgencyName(String),
travelAgencyInvoiceNumber(String),
travelAgencyPlanName(String),
restrictedTicketIndicator(String),
issuingCarrierCode(String),
isCardholderTraveling(String),
passengersCount(String),
infantsCount(String),
payerPassportId(String),
totalFare(String),
totalTaxes(String),
totalFee(String),
boardingFee(String),
ticketIssueAddres(String),
passengerDetails {passengerId(String), passportNumber(String), customerCode(String), frequentFlyerCode(String), title(String), firstName(String), lastName(String), middleName(String), dateOfBirth(String), phoneNumber(String)},
flightLegDetails {flightLegId(String), airlineCode(S, flightNumber(String), departureDate(String), arrivalDate(String), departureCountry(String), departureCity(String), departureAirport(String), destinationCountry(String), destinationCity(String), destinationAirport(String), legType(String), flightType(String), ticketDeliveryMethod(String), ticketDeliveryRecipient(String), fareBasisCode(String), serviceClass(String), seatClass(String), stopOverCode(String), departureTaxAmount(String), departureTaxCurrency(String), fareAmount(String), feeAmount(String), taxAmount(String), layoutIntegererval(String)}

For cards, while working in Auth-Settle mode, the Auth is done using this API call and settle is done in a separate clearing batch process.

For more information and for required SafeCharge configurations settings, please contact SafeCharge’s Integration Team at integration@safecharge.com.
urlDetails
Class
No
notificationUrl(String, 1000)

This parameter determines where to return the DMN.
Each parameter is limited for up to 1000 characters.
externalMpi
Class
No
isExternaMpi(String, 1),
eci(String, 2),
cavv(String, 50),
xid(String, 50)

Allow the merchant to provide the 3D Secure authentication result as input.

isExternalMpi possible values:
1 - external MPI is used (in this case need to send eci, cavv, xid values obtained from the external MPI).
0 - external MPI is not used.

Note that: eci is the The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated; ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program; ECI = 7: payment authentication was not performed, cavv is the card holder authentication verification value, xid is the transaction identification value.
storedCredentials
Class
No
storedCredentialsMode

This parameter shows whether or not stored tokenized card data is sent to execute the transaction.
Possible values:
0 - The card data was entered for the first time, and, upon completion of the transaction, is tokenized and stored for future transactions.
1 - Previously tokenized and stored card data was used to perform the transaction.
This parameter is only applicable to merchants that store tokenized card data and is mandatory when cardData->cardNumber parameter is populated and sent. Merchants that do not store card data, or that are using SafeCharge’s tokenization feature, should not send this parameter.
customSiteName
String
(50)
No
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
productId
String
(50)
No
A free text field used to identify the product/service sold.
If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
externalTokenProvider
Class
No
externalTokenProvider(String, 45),
mobileToken(String, 5000)

External token provider is a type of entity in the payment industry with its own flow. For example: ApplePay.
For ApplePay it is required to pass on the values:
externalTokenProvider - “ApplePay”,
mobileToken - the token received from Apple during the following: Dynamic Server to Server JS Button Solution.
In order to work with external token providers special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
timeStamp
String
(14)
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "", 
    "gwErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    }, 
    "partialApprovalDetails":{
        "isPartialApproval": "",
        "amountInfo":{
            "requestedAmount": "",
            "requestedCurrency": "",
            "processedAmount": "",
            "processedCurrency": ""
        }
    },
    "cvv2Reply":"",
    "avsCode":"",
    "transactionType":"",
    "customData":"",
    "fraudDetails":{
        "finalDecision":"",
        "recommendations": "",
        "system":{
            "systemId":"1",
            "systemName":"SafeCharge",
            "decision":"",
            "rules":[{
               "ruleId": "",
               "ruleDescription":""
            }]
        }
    },
    "acquirerId": "19",
    "bin": "400002",
    "last4Digits": "2535",
    "ccCardNumber": "4****2535",
    "ccExpMonth": "10",
    "ccExpYear": "22"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
(36)
Session identifier returned by getSessionToken.
orderId
String
(20)
The order ID provided by SafeCharge.
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
ID of the user in the merchant’s system.
clientUniqueId
String
(255)
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(20)
ID of the API request in the merchant’s system.
internalRequestId
String
(20)
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
(20)
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
merchantDetails
Class
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0.
When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
(10)
The current version of the request. The current version is 1.
userPaymentOptionId
String
(45)
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
(20)
The transaction ID of the transaction in the event that an external service is used.
transactionId
String
(20)
The gateway transaction ID.
authCode
String
(128)
Authorization code of the transaction.
externalToken
Class
externalToken_blockedCard(String),
externalToken_cardAcquirerId(String),
externalToken_cardAcquirerName(String),
externalToken_cardBin(String),
externalToken_cardBrandId(String),
externalToken_cardBrandName(String),
externalToken_cardExpiration(String),
externalToken_cardLength(String),
externalToken_cardMask(String),
externalToken_cardName(String),
externalToken_cardTypeId(String),
externalToken_cardTypeName(String),
externalToken_clubName(String),
externalToken_creditCompanyId(String),
externalToken_creditCompanyName(String),
externalToken_extendedCardType(String),
externalToken_Indication(String),
externalToken_tokenValue(String),
externalToken_tokenProvider(String)

Parameters arriving from a third-party payment provider that also generate card tokens (currently relevant only to CreditGuard as third party payment provider which generate card tokens).
partialApprovalDetails
Class
isPartialApproval(String-True or False),
amountInfo: requestedAmount(String), requestedCurrency(String), processedAmount(String), processedCurrency(String)

These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.
cvv2Reply
String
CVV2 (card verification value) response. Possible values:
M = CVV2 Match
N = CVV2 No Match
P = Not Processed
U = Issuer is not certified and/or has not provided Visa the encryption keys.
S = CVV2 processor is unavailable.
avsCode
String
The AVS (address verification) response. The following values may be returned:
A = The street address matches, the ZIP code does not.
W = Whole 9-digits ZIP code match, the street address does not.
Y = Both the 5-digits ZIP code and the street address match.
X = An exact match of both the 9-digits ZIP code and the street address.
Z = Only the 5-digits ZIP code match, the street code does not.
U = Issuer Unavailable
S = Not Supported
R = Retry
B = Not Authorized (declined)
N = Both street address and ZIP code do not match.
transactionType
String
(45)
The type of transaction; Sale or Auth. (See Glossary for more details about Auth and Sale transactions.)
Note that, this require the merchant to be configured to gateway version 4.1.2 and up, For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
customData
String
(255)
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
fraudDetails
Class
finalDecision(String),
recommendations(String),
system{systemId(String), systemName(String), decision(String), rules[ruleId(String), ruleDescription(String)]}

system - Which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
rules - The risk management system rules triggered by the transaction.
decision - The risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter:
1. “Accept” The risk management system accepts the transactions.
2. “Reject” The risk management system rejects the transaction. The transaction not passed to bank for authorization. The reasons returned in ruleDescription parameter.
3. “Review” The risk management system flags a transaction for review but still accept the transaction.
4. “Error” An error occurred during risk management system operation. The gateway continues to process the transaction through the bank.
5. “None” No risk analysis was performed. The gateway continues to process the transaction through the bank.
finalDecision - when deciding whether to accept or reject a transaction, the risk Management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a Reject decision, the finalDecision is to accept the transaction. If at least one of the rules leads to a Reject decision, the finalDecision is to reject the transaction.

In order to receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
bin
String
(6)
This parameter returns the BIN number of the card process.
Note: BINs are the first 6 numbers of the card, which represent the card issuer.
last4Digits
String
(4)
This parameter returns the last four digits of the card.
ccCardNumber
String
(20)
This parameter returns a masked version of the card, e.g. 4****2535.
ccExpMonth
String
(2)
This parameter returns the card expiration month (MM).
ccExpYear
String
(2)
This parameter returns the card expiration year (YY).
acquirerId
String
(2)
This is an ID representing the acquirer that processed the transaction.

/paymentAPM

Performs payments using an alternative payment method, in direct or redirect flow. PaymentAPM transaction is implemented in 4 main stages:
1. Ensuring that SafeCharge is integrated to the desired APM.
2. The paymentAPM method call.
3. The required merchant actions (for APM’s who work redirect). Following a positive response from the paymentAPM method, per output parameter transactionStatus returned value, the merchant is redirected to the APM’s payment page (using redirectURL) to login and confirm the billing information.
4. The APM required actions (for APM’s who work redirect). Once the credentials are typed and the payment is confirmed, the APM redirects (with some additional information) back to SafeCharge’s gateway using a returnUrl from previous APM-SafeCharge communications at 1st stage. Afterwards, the SafeCharge gateway redirects to a successURL or to a failureURL.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/paymentAPM.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "currency": "EUR",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
     "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "ipAddress"
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "shippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "addendums": {
        "localPayment": {
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        }
    },
    "paymentMethod": "apmgw_expresscheckout",
    "userAccountDetails": {
        "email": "user@mail.com"
    },
    "userPaymentOption":{
        "userPaymentOptionId":""
    },
    "urlDetails": {
        "successUrl": "",
        "failureUrl": "",
        "pendingUrl": "",
        "notificationUrl": ""
    },
    "subMethodDetails": {
        "subMethod":"",
        "subMethodField1":"",
        "subMethodField2":""
    },
    "customData":"",
    "webMasterId":"",
    "timeStamp": "20170118191845",
    "checksum": "31010a1101b653fa187bbef2cdd7d6441d6f681bf198efa2e8749cae6d77ca80"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
(36)
Yes
Session identifier returned by the getSessionToken.
orderId
String
(45)
No
The order ID provided by SafeCharge.
This parameter is provided only in cases where this method is called after an Orders Management method.
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
No
ID of the user in the merchant’s system.

If userPaymentOption sent in the request, then it is mandatory to send userTokenId in the request as well.
clientUniqueId
String
(45)
Yes,
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
currency
String
(3)
Yes
The three character ISO currency code.
amount
Double
(12)
Yes
The transaction amount.
amountDetails
Class
Yes,
See Description
totalShipping(String),
totalHandling(String),
totalDiscount(String),
totalTax(String)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
items
Class
Yes,
See Description
name(String, 255),
price(String, 10),
quantity(String, 10)

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
deviceDetails
Class
No
deviceType(String, 10),
deviceName(String, 255),
deviceOS(String, 255),
browser(String, 255),
ipAddress(String, 15)

Supported device types: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (If device type cannot be recognized).
userDetails
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
county(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
shippingAddress
Class
No
firstName(String, 30),
lastName(String, 40),
address(String, 60),
cell(String, 18),
phone(String, 18),
zip(String, 10),
city(String, 30),
country(two-letter ISO country code)(String, 2),
state(two-letter ISO state code)(String, 2),
email(String, 100),
shippingCounty(String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
billingAddress
Class
Yes,
See Description
firstName(String, 30) (optional),
lastName(String, 40) (optional),
address(String, 60) (optional),
cell(String, 18) (optional),
phone(String, 18) (optional),
zip(String, 10) (optional),
city(String, 30) (optional),
country(String, 2) (mandatory, two-letter ISO country code),
state(String, 2) (optional, two-letter ISO state code),
email(String, 100) (mandatory),
county(String, 255) (optional)

The country parameter is mandatory and must contain the ISO code of a country that is supported by the APM according to the configuration by SafeCharge.
It is recommended that you use the getMerchantPaymentMethods to see what SafeCharge configuration is to be received.

Note that the email parameter is mandatory for most APMs.

In case billingAddress provided when the user payment option (UPO) created/updated, then it is used for the transaction.
In case billingAddress sent in orders/payments methods request as separate parameter, then it is used for the transaction and after transaction performed overrides the one saved in the UPO.
In case billingAddress was not saved in the UPO, and was not sent in orders/payments methods request as separate parameter, then value from userDetails parameter is used, but billingAddress is not saved in the UPO.
dynamicDescriptor
Class
No
merchantName(String, 25),
merchantPhone(String, 13)

This allows the merchant to define a dynamic descriptor, which will appear in the payment statement. The name field should contain the merchant name. The phone field should contain either customer support phone number or support email address or merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.
merchantDetails
Class
No
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

For example, localPayment addendum includes:
nationalId,
debitType,
firstInstallment,
periodicalInstallment,
numberOfInstallments

Please note that the possible values for the debitType parameter are:
'1’ - Singular payment.
'2’ - Instalments.
'3’ - Special debit.

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
paymentMethod
String
(50)
Yes
SafeCharge’s unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see APM Unique SafeCharge Names.

This is mandatory if the userPaymentOption (below) is not sent. One of these two parameters, paymentMethod or userPaymentOption, MUST be sent, but NEVER both.
userAccountDetails
Map
No
SafeCharge’s account identifiers of the payment methods. For more information, see APM Account Identifiers.

This is mandatory if paymentMethod (above) sent and the userPaymentOption (below) is not sent.
userPaymentOption
Class
No
userPaymentOptionId(String, 45)

On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.

This is mandatory if the user desires to pay with an existing UPO and paymentMethod, userAccountDetails (above) were not sent.

This is mandatory if the paymentMethod (above) is not sent. One of these two parameters, paymentMethod or userPaymentOption, MUST be sent, but NEVER both.
urlDetails
Class
No
successUrl(String, 1000),
failureUrl(String, 1000),
pendingUrl(String, 1000),
notificationUrl(String, 1000)

Each parameter is limited for up to 1000 characters.
subMethodDetails
Class
No
subMethod(String),
subMethodField1(String),
subMethodField2(String)

The sub method parameter enables working with a specific payment method in a few different flows.

Supported Flow
PayPal quick registration mode.
- subMethod should be set to QuickRegistration. No other fields are required.
PayPal Membership Agreement
- subMethod should be set to referenceTransaction. No other sub method fields are required.
customData
String
(255)
No
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway and is visible in SafeCharge’s back-office tool transaction reporting.
webMasterId
String
(255)
No
This is an affiliate parameter that the merchant can send.
timeStamp
String
(14)
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "", 
    "paymentMethodErrorCode": "0",
    "paymentMethodErrorReason": "",
    "gwErrorCode": "0",
    "gwErrorReason": "",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "redirectURL": "www.apmurl.com"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
(36)
Session identifier returned by getSessionToken.
orderId
String
(20)
The order ID provided by SafeCharge.
merchantId
String
(20)
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Merchant Site ID provided by SafeCharge.
userTokenId
String
(20)
ID of the user in the merchant’s system.
clientUniqueId
String
(20)
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
(255)
ID of the API request in the merchant’s system.
internalRequestId
String
(20)
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status
String
(20)
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
(20)
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR, PENDING.
merchantDetails
Class
customField1(String, 255),
customField2(String, 255),
customField3(String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8(String, 255),
customField9(String, 255),
customField10(String, 255),
customField11(String, 255),
customField12(String, 255),
customField13(String, 255),
customField14(String, 255),
customField15(String, 255)

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not used for processing.
errCode
String
(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
(400)
If an error occurred on the request side, an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
paymentMethodErrorCode
Integer
(11)
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
(400)
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
(400)
If an error occurred in the gateway, then an error reason is returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
gwExtendedErrorCode
Integer
(11)
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.
userPaymentOptionId
Long
(45)
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
(20)
A unique ID generated by SafeCharge that represents the APM transaction.
transactionId
String
(20)
The gateway transaction ID.
authCode
String
(128)
Authorization code of the transaction.
redirectURL
String
The URL used by the merchant to redirect consumers to the payment method for authentication and authorization of the payment. This is returned only if the APM payment is conducted using redirect APM flow.

Payment Options

Payment Option Methods

/createUser

This method creates a new user. The user is stored according to the userTokenId as defined by the merchant for the user. Future calls relevant to this user require the userTokenId sent in this request.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/createUser.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "testUserToken",
    "clientRequestId": "100",
    "firstName": "John",
    "lastName": "Smith",
    "address": "some street",
    "state": "",
    "city":"",
    "zip":"",
    "countryCode": "GB",
    "phone":"",
    "locale": "en_UK",
    "email": "john.smith@test.com",
    "dateOfBirth": "",
    "county":"",
    "timeStamp": "20150915143321",
    "checksum": "21bc2501b7857059862124a5d04c9ade"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
(20)
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
(20)
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
(255)
Yes
ID of the user in the merchant’s system.
clientRequestId
String
(255)
Yes,
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
firstName
String
(30)
No
The first name of the user being registered.
lastName
String
(40)
No
The last name of the user being registered.
address
String
(60)
No
The street address of the user being registered.
state
String
(2)
No
The two-letter ISO state code of the user being registered.
city
String
(30)
No
The city of the user being registered.
zip
String
(10)
No
The ZIP code of the user being registered.
countryCode
String
(2)
Yes
The two-letter ISO country code of the user being registered.
phone
String
(18)
No
The phone number of the user being registered.
locale
String
(5)
No
The user’s locale and default language, for example en_UK.
email
String
(100)
No
The email address of the user being registered.
dateOfBirth
String
(10)
No
The date of birth of the user being registered.
county
String
(255)
No
The county (district) of the user being registered.
timeStamp
String
(14)
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
(256)
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, firstName, lastName, address, state, city, zip, countryCode, phone, locale, email, county, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "45",
    "clientRequestId": "100",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version"