Navbar
JSON Node.JS java php C#

Home

Introduction

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

SafeCharge’s API is simple, easy-to-use, secure and stateless, 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 the merchant side. A merchant is only required to submit a 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, backoffice tool, pay-out services, etc. can be obtained by contacting SafeCharge at integration@safecharge.com.

Getting Started

SafeCharge offers two quick ways to build your payment page.

Our Checkout Page solution provides a pre-designed template, which can be branded to your business needs.

Alternatively, you can use our Web SDK solution, which allows for customisation of your payment page.

API and SDK

You can use our Web SDK to accept payment directly on your own custom payment flow and payment page.

The Web SDK is a JavaScript library that allows you to achieve the following:

For the full Web SDK reference, please click here.

Please follow this step-by-step Web SDK guide for quick payment integration.

STEP 1: SET UP AN ORDER BY API CALL

Before you can submit a payment with our client-side Web SDK, you need to send the /openOrder API call that both:

Sample Request

Sample Response


STEP 2: REFERENCE THE WEB SDK LIBRARY

Import the safecharge.js JavaScript library.

STEP 3: GENERATE THE PAYMENT FORM

Create your payment form with the placeholder for SafeCharge Fields.

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>

STEP 4: ACTIVATE SAFECHARGE FIELDS

Use our API to inject SafeCharge Card Fields:

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'));

By the end of this step, the form is completely rendered and ready for the user to enter the cardholder details and other payment information. By clicking the 'Form’ button, the user activates the payment process and submits the response to your server.

STEP 5: SUBMIT PAYMENT WITH THE TOKEN

When the user clicks the 'Submit’ button, you need to invoke the createPayment method, providing the SafeCharge Field that holds the cardholder data that was collected.

When the transaction is returned, you receive the complete transaction response. You can receive the response in two separate ways (either or both):

The following are the most important output fields you should examine:

(For the complete response specification, please refer to the /payment output table chapter.)

You should verify the response you received on your server-side, after having generated a checksum from the same field values (they should be concatenated in the above order), and compare that you received the same checksum value.

Sample Response

Checkout Page

The quickest way to integrate to SafeCharge and benefit from all our features is via our 'Checkout Page’ 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 customisation of your payment page via the Page Builder menu located in the Control Panel. Speak to your account manager for more complex customisation.

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


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): 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.
Can be used to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc
clientUniqueId
If transaction is sent through the SafeCharge API, this parameter is populated by the ID of the transaction in the merchant’s system.
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. Please refer to the APM ACCOUNT IDENTIFIERS (Pay In) under Supported Payment Methods.
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",
    "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:
APPROVED
DECLINED
ERROR
Read more
Read less
redirectURL
The APM’s URL to redirect to. For Redirect APM only.
reason
The error reason, in the event of an error.
AuthCode
The authorisation 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. Refer to Returning Users for further details.
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",
    "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 provide 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 3166-1 country code list and ISO 4217 currency code list.

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.
These 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:

Please contact SafeCharge’s Integration Team at integration@safecharge.com for further information.

Post Finance Alias Recurring

Post Finance support directs recurring payments using this sub method. The first Alias Registration request returns a URL that enables the end user to perform the first payment. For any follow up, Alias Registration directs calls and returns the transaction response.
In order to invoke:

Please contact SafeCharge’s Integration Team at integration@safecharge.com for further information.

Skrill 1 Tap

Skrill 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 follow-up transaction can be done server-to-server.

Trustly PayNPlay

This Trustly feature allows you to register your user based on their registration to their Trustly registration. In order to invoke:

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 (Pay In)

You can download full description of APM Unique SafeCharge Names (Payin) by clicking 'Export as CSV’.



APM UNIQUE SAFECHARGE NAMES (Pay Out)

You can download full description of APM Unique SafeCharge Names (Payout) by clicking 'Export as CSV’.



APM ACCOUNT IDENTIFIERS (Pay In)

You can download full description of APM Account Identifiers (Payin) by clicking 'Export as CSV’.



APM ACCOUNT IDENTIFIERS (Pay Out)

You can download full description of APM Account Identifiers (Payout) by clicking 'Export as CSV’.



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 (UPO) 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.

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 a 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 maximising 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 for 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 authorisation 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 authorisation. 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 authorisation.

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:

SPECIAL 3D SECURE HANDLING

Avoid 3D Secure

Though not recommended, in some case you will want to avoid 3D Secure altogether. To do this, you need to specify it by setting the paymentOption.card.threeD.dynamic3DMode field to “OFF”.

Handle non-enrolled user

If a user is not enrolled with any 3D Secure program, the default behaviour is that the payment method returns a Declined response. You can instruct SafeCharge to automatically charge the user with a non-3D Secure transaction by setting the paymentOption.card.threeD. convertNonEnrolled field to true. Refer to details in the Payment method section.

Recurring Transaction Parameters

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:

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

Any call to the payment transaction must include the field:

Partial Approval

This chapter describes how to process partial approval transactions through the SafeCharge Gateway integration. It explains:

OVERVIEW

A situation may arise where a customer wishes to make a purchase or deposit while lacking sufficient funds to complete the transaction. This may be caused by an insufficient balance on a prepaid card or a lack of approval on the part of the issuing bank. In such a case for a deposit, the customer is charged for the remainder of the existing funds and the transaction is completed. If the transaction is a purchase, the remaining part of the sum total of the transaction is required to complete the transaction; however, the total amount of the remaining sum is charged immediately.

This option is enabled by contacting customer support.

If this option is enabled, you should take the necessary steps to notify your customers of the partial approval due to their lack of funds to ensure “user-friendliness” and adherence to the applicable laws and standards governing your business.

As mentioned above, once a transaction is approved, even with less funds than needed to complete the requested deposit/purchase, the transaction for the available funds is executed and submitted for approval. If you wish to supply your customers with an option to cancel on the submitted transaction, a new reversal transaction must be implemented on your part to reimburse the funds previously charged to the customer.

HOSTED PAYMENT PAGE SUPPORT

To activate Partial approval on the payment page, please contact your account manager. Once activated and a deposit transaction is partially approved, a dialog window opens allowing to confirm or cancel the transaction. Clicking 'Cancel’ triggers execution of a void transaction and a DMN is sent to the merchant. Clicking 'Confirm’ triggers a confirmation DMN to the merchant.

Following the partial approval operation in SafeCharge’s hosted payment solution, the DMN notification is triggered and the following parameters are sent with the following values:

REVERSING A PARTIAL APPROVAL

A situation may arise where the customer is not interested in continuing with a transaction if it can only be carried out partially. Since the partial approval is authenticated automatically, it is incumbent on the merchant to be prepared for this scenario and to offer the merchant an option for the customer to back out of the transaction. The partial approval transaction cannot be reversed and instead must be voided by the merchant; therefore, merchants must be sure to provide their customers an easy option to reimburse their funds if needed.

The hosted payment page allows the customer to void the partially approved transaction by presenting a dialog with a “Confirm” button and a “Cancel transaction” button. Clicking 'Cancel transaction’ issues a void transaction with the partially approved amount and currency.

DIRECT API SOLUTION

The SafeCharge API also offers support to the partial approval feature. For more information about the input and output parameters, please refer to /payment and Notifications (using DMN).

Apple Pay

CERTIFICATES

Below are the required actions to be completed to obtain the Apple Pay certificates from Apple.

Apple Pay Certification

  1. Log in to https://developer.apple.com/
  2. Click the 'Certificates, IDs & Profiles’ option.
  3. From the newly opened screen, select Merchant IDs and click 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 verifies the entered data.
  6. Click the 'Register’ button. If the registration is successful a screen showing ‘Registration complete’ appears.
  7. Click the row with the newly created ID and click 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, click 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’. 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 dropdown menu in Keychain Access, click '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’ checkbox 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, select the file by clicking 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 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 Keychain Access. The login keychain is the default if no other keychain was chosen.
  10. Right-click the imported certificate and then select 'Export “PAIR_NAME’ to export the signed pair. Select ’.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. Click 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 '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. Click 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. More information can be found here: https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server. The above link also contains a complete guide on how to verify the domain.
  2. From the Register Merchant Domain window, enter the desired domain to be verified and click '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 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:

Mac device:
- Safari running on macOS Sierra or later.
- 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.

To use 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, 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.

The merchant must define the callback function that receives the authorised payment token (mobileToken), optional address 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.

The merchant sends the data gathered by the button handler to the 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 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 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:

Mac device:

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 the '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 that is integrated with a 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 its 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 website.
2. The merchant must include SafeCharge IFrame directly on the merchant’s website (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 you need to switch the merchant configuration between HTTPS GET and HTTPS POST, then you 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.

To integrate DMNs, 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

If the IP address of a DMN listener needs to 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 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:
Approved: The transaction was processed and approved by the APM processor.
Declined: The transaction was processed by the APM processor and declined.
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 Declined) 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 RESPONSE 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 same 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 DESCRIPTION
ppp_status
Required
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
Required
A unique 64-bit number that identifies the SafeCharge payment page transaction.
totalAmount
Required
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
Required
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
Optional
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
Optional
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
Required
Deprecated checksum parameter.
advanceResponseChecksum
Required
Advanced response checksum that ensures that the DMN callback is authentic.
transactionID
Optional
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
Optional
The type of transaction: Sale, Auth, Settle, Credit or Void. This service is only available upon request.
Status
Optional
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
Optional
The first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and returns 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
Optional
The transaction ID of the transaction when an external service is used.
userid
Optional
The value that was initially passed as the userid parameter when making the HTTPS POST request to the payment page.
customData
Optional
The ID that was initially passed as the customData parameter during the first request.
productId
Optional
The ID that was initially passed as the productId parameter during the first request.
first_name
Optional
First name of the user processing the transaction, if provided.
last_name
Optional
Last name of the user processing the transaction, if provided.
email
Optional
Email of the user processing the transaction, if provided.
externalEmail
Optional
For PayPal only. The registered email address that is returned from the PayPal account.
cardCompany
Optional
The name of the credit card company.
Possible values: Visa, Amex, MasterCard, 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
Optional
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
Optional
The invoice_id that that was initially passed as the invoice_id parameter during the first request.
address1
Optional
Street address of the user processing the transaction, if supplied.
address2
Optional
Street address of the user processing the transaction, if supplied.
country
Optional
The country of the user processing the transaction, if supplied.
state
Optional
State of the user processing the transaction, if supplied.
city
Optional
City of the user processing the transaction, if supplied.
zip
Optional
Zip code of the user processing the transaction, if supplied.
phone1
Optional
Phone number of the user processing the transaction, if supplied.
Phone2
Optional
Alternate phone number of the user processing the transaction, if supplied.
Phone3
Optional
Alternate phone number of the user processing the transaction, if supplied.
nameOnCard
Optional
Name on card used to process the transaction, if supplied.
cardNumber
Optional
The masked card number 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.
expMonth
Optional
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
Optional
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
Optional
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
Optional
Deprecated ID of the token. Used in combination with the token.
orderTransactionId
Optional
This value helps to identify individual transactions that are related to the same orderID.
3dflow
Optional
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
Optional
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
Optional
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
Optional
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
Optional
The error code returned from an APM.
errApmDescription
Optional
The error description returned from an APM.
errScCode
Optional
The error code returned by SafeCharge for an APM transaction.
errScDescription
Optional
The error description returned by SafeCharge for an APM transaction.
AuthCode
Optional
Authorisation code, up to 35 characters, returned for each approved and pending transaction.
acquirerId
Optional
The acquiring bank’s unique ID. The value 0 represents an invalid bank code.
bin
Optional
The first six digits from the credit card number used for identifying the processing bank.
shippingCountry
Optional
Shipping country of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingState
Optional
Shipping state of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingCity
Optional
Shipping city of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingAddress
Optional
Shipping address of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingZip
Optional
Shipping zip code of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingFirstName
Optional
Shipping first name of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingLastName
Optional
Shipping last name of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingPhone
Optional
Shipping phone of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingCell
Optional
Shipping mobile phone of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
shippingMail
Optional
Shipping email of the consumer processing the transaction, if supplied. An empty string is returned when the shipping feature is not enabled.
Total_discount
Optional
The sum of the values in the item_discount_X parameter.
total_handling
Optional
The handling parameter that the merchant passed to SafeCharge in the HTTPS POST request.
total_shipping
Optional
The shipping parameter that the merchant initially passed as the shipping parameter during the first request.
total_tax
Optional
The total tax parameter that that the merchant initially passed during the first request.
buyButtonProductBundleId
Optional
Contains the ID of the product bundle when the buy button payment is processed.
merchant_site_id
Required
The ID, provided by SafeCharge that uniquely defines a particular merchant customisation.
requestVersion
Required
The version of the request.
message
Required
A message from SafeCharge about the transaction that has been completed.
merchantLocale
Optional
The language of the payment page. The possible values of this parameter are 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
Read more
Read less
unknownParameters
Optional
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
Required
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 tables in APM Account Identifiers.
ID
Optional
Hebrew ID.
merchant_id
Required
The unique merchant ID supplied by SafeCharge.
responseTimeStamp
Required
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
Optional
Contains the ID of the product when the ‘buy button payment’ was processed.
dynamicDescriptor
Required
Dynamic descriptor passed to the SafeCharge gateway for the current transaction.
Reason
Optional
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
Optional
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
Required
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
Optional
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
Required
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
Optional
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
Optional
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
Optional
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
Optional
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
Optional
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
Required
The IP address from which the client made the purchase.
uniqueCC
Optional
A unique value assigned to the credit card number.
user_token_id
Optional
This is a unique identifier for each consumer generated by the merchant.
ExternalAccountID
Optional
This is the consumer’s username or unique identifier provided by the APM. This value is not returned for all APMs.
APMReferenceID
Optional
This is SafeCharge’s reference identifier for each APM.
webMasterId
Optional
The webMasterID passed in the request.
finalFraudDecision
Optional
This parameter indicates the final fraud analysis decision made by SafeCharge Risk Management.
Possible values:
Accept – The transaction is redirected for processing
Reject – The transaction is rejected due to a Fraud Filter.
Read more
Read less
SystemID
Optional
The value of this parameter is a numeric identifier generated by SafeCharge for the fraud analysis service/tool.
SystemName
Optional
The value of this parameter is an internal SafeCharge name for the fraud analysis service/tool.
SystemDecision
Optional
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.
Read more
Read less
Rules
Optional
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 ’=’.
Read more
Read less
CVV2Reply
Optional
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.
Read more
Read less
AVSCode
Optional
The AVS (address verification) response. The following values may be returned:
A – The street address matches, the zip code does not.
W – Whole 9-digit zip code match, the street address does not.
Y – Both the 5-digit zip code and the street address match.
X – An exact match of both the 9-digit zip code and the street address.
Z – Only the 5-digit zip code matches, 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.
Read more
Read less
cardType
Optional
The type of card used in the transaction.
Possible values: credit or debit.
upoRegistrationDate
Optional
The date that the UPO was registered in the following format: YYYMMDDHHmmss
isPartialApproval
Optional
Indicate if the transaction was requested for partial approval (1) or not (0).
requestedAmount
Optional
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
Optional
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
Optional
Indicates whether this is a regular transaction or a recurring/rebilling transaction.
Possible values:
0 – This is a regular transaction.
1 – This is a recurring/rebilling transaction.
Read more
Read less
autoSettleMode
Optional
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.
Read more
Read less
isExternalMpi
Optional
Allows 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.
Read more
Read less
cavv
Optional
The card holder authentication verification value. Relevant for external MPI.
xid
Optional
The transaction identification value. Relevant for external MPI.
eci
Optional
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.
Read more
Read less
type
Optional
The type of the notification.
Possible values:
DEPOSIT
WITHDRAWAL
KYC
DOCUP
KYC and DOCUP are only relevant for merchants implementing SafeCharge’s KYC solutions.
Read more
Read less
clientRequestId
Optional
ID of the API request in merchant’s system. This value must be unique. Can be used to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
relatedTransactionId
Optional
The ID of the related transaction used in case it was required for processing.
merchant_unique_id
Optional
If transaction sent through SafeCharge payment page, this parameter is populated by the ID of the transaction in the merchant’s system.
clientUniqueId
Optional
If transaction sent through SafeCharge API, this parameter is populated by the ID of the transaction in the merchant’s system.
externalTokenProvider
Optional
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
Optional
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 cannot 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 Technical 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 authorisation and settle.
1109
Unable to process this credit card company.
1110
Unrecognised 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.
Read more
Read less
-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, pickup
This decline code is returned when the card is listed as lost on the issuer’s side.
-1
0
Stolen card, pickup
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.
Read more
Read less
-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 authorising 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 authorisation 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.
Read more
Read less
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.
Read more
Read less
Extends Withdrawal Frequency
4000196948974975 (India)
4008440870955798 (UK)
5333498929343773 (South Korea)
5101825328239980 (UK)
375529856696120 (Ireland)
Issuer declined your payment. Please contact issuer.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
Transaction Not Permitted on Terminal
4000269084739575 (US)
4018415418260230 (UK)
5333562868563707 (US)
5116819173651897 (UK)
375536629108788 (Greece)
Issuer declined your payment. Please contact issuer.
Read more
Read less
Restricted Card
4000273652260030 (US)
4018445028360724 (UK)
5333578626428553 (US)
5116828963987577 (UK)
375537795464104 (Greece)
Issuer declined your payment. Please contact issuer.
Read more
Read less

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.

Web SDK

Web SDK Overview

The Web SDK is SafeCharge’s newest integration method. This is a JavaScript library that you can use on your own payment page to perform end-to-end payments.

The main strength of the Web SDK is that it is very simple to integrate, yet does not require any PCI whatsoever, giving you complete control over the UI and UX.

The simplicity of the integration is especially important with the new 3D Secure v2.0 mandate by the card schemes. The 3DS v2.0 mandate introduces a new compulsory flow that turns any API based solution (including SafeCharge’s) from a simple API call to a complete workflow to be implemented, which requires a thorough understanding of 3D v2.0.

This is also relevant when you wish to migrate from your current 3D Secure v1.0 integration to 3DS v2.0. The Web SDK offers a quick migration option, with which you can use your existing integration – either with SafeCharge or any other provider – and migrate to 3D 2.0 with just a minimal code change.

Comparison to Other Solutions

This simplicity is what makes, it in most cases, the preferred solution for most merchants. However, there are cases when you would prefer our other two integration solutions:

Product Quick Integration Control Over UI/UX PCI Multi-PSP Comment / Relevant Customers
Cashier/Hosted PP
v
v
v
v
  • No control over UI/UX
  • Only basic customization support
  • Pure API (REST)
    x
    v
    x*
    v
  • 3D secure flow has to be fully implemented by the merchant
  • Full control over the process
  • Web SDK
    v
    v
    v
    v
    Win-Win for the merchant for having full control, PCI and a simple integration

    * A merchant can combine API with SDK just for PCI descoping. It still is not trivial with multiple PSP providers.

    Q&A

    The Web SDK is in the frontend – why doesn’t it impact UI/UX?

    The Web SDK is a set of methods; it doesn’t intervene with your UI, except in two cases:

    How do I get control over what the Web SDK is doing “inside”?

    The Web SDK reflects each step of the progress of the payment by submitting JavaScript events. At any time, you can abort the process, or let the user abort the process and you get the indication for that as well.

    What control do l gain by using direct API rather than the Web SDK?

    Not much. The process that the Web SDK performs is not flexible and cannot be customised. Implementing by API must result with exactly the same workflow and user experience. Since we do not touch the UI, the UI is not influenced by you integrating with the API.

    Since you can use the Web SDK authenticate3d method and route the transaction to be processed by other acquirers/PSPs.

    Can I work with the Web SDK and process with other acquirers/PSPs? Will I need to use their SDK as well?

    Yes, the Web SDK can work with other acquirers/PSPs. The Web SDK contains the authenticate3d method, which performs the end-to-end 3D 2.0 flow, but instead of directly continuing to process the transaction, it returns the 3D result and authentication information (cavv and eci) that can then be used for processing either with the SafeCharge API (both the REST and the legacy Gateway) or with any other provider.

    What if I want to do it differently from the way the Web SDK is doing it?

    Theoretically, this is when you need to use the Direct API. However, we know of no other way the process can be performed other than the way that we do it. The process is very inflexible.

    What’s so complicated about the 3D v2.0 flow and how the web SDK simplifies it?

    For more information regarding the full implementation guide for 3D v2.0, please contact the Integration Team at integration@safecharge.com.

    In short, you have to implement the following (relevant to any provider, not just SafeCharge):

    1. Authenticate with the provider /getsessiontoken.
    2. Send a request to determine the cardholder 3D secure version /initpayment.
    3. Perform fingerprinting according to the 3D Secure definition (done by you).
    4. Perform a 3D secure authorisation request /initpayment.
    5. If version one (done by you):
      a. Analyse the response and if needed, perform 3DS v1 redirection
      b. Analyse the 3DS v1 response
      c. Handle non-enrolled users and walkaways
    6. If version two (done by you):
      a. Handle exemptions
      b. Handle the frictionless scenario
      c. Handle the challenge scenario
    7. Perform the payment request /payment
    8. Handle response

    Instead, what you need to do with the web SDK is: 1. Authenticate 2. Call the Web SDK createPayment or authenticate3d methods 3. Handle response

    What happens if the 3D Secure standard changes? Do other standards apply?

    This will be completely seamless to you as long as you are using the Web SDK. If you have implemented the API, you may need to make changes.

    What is the quickest way to migrate to 3D v2.0?

    The quickest way to migrate is by using the Web SDK authenticate3d method, not only for an existing SafeCharge integration, but for any integration that you have with any provider. This method performs the end-to-end 3D 2.0 flow, but instead of directly continuing to process the transaction, it returns the 3D result and authentication information (cavv and eci). You just need to add this field to your existing API integration -either with SafeCharge or with any other provider.

    I have PCI. I don’t need to or cannot use the Web SDK, right?

    No. There is still a big advantage in using the Web SDK, since besides performing PCI descoping it significantly simplifies any payment flow.

    The Web SDK can receive clear text cardholder information and in this way the cardholder information is not prevented or hidden (descoped) from you.

    I am PCI compliant. I am not allowed to use the Web SDK, right?

    Wrong. Since our code is hosted in our servers, the PCI is preserved even though the Web SDK is used by your page. You can choose to either use it by sending it clear text cardholder information or using our tokenization solution.

    Do I need the Web SDK for a tokenized transaction (using userPaymentOptionId)

    Yes. 3D Secure v2.0 is mandatory for all transactions. The Web SDK can receive userPaymentOptionId as an input.

    What You Can do with the SDK?

    Web SDK Initialisation

    Before any call to any of the Web SDK methods, you have to perform the following simple steps:

    Server-Side Authentication

    Before you can submit a payment with our client-side Web SDK, you need to send the openOrder API call that:

    Please refer to /openOrder for more details and code samples.

    Reference the Web SDK Library

    Import the safecharge.js JavaScript library.

    Initialise the Web SDK

    Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.

    COPIED
    1
    2
    3
    4
    5
    6
    
    // 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
    });
    

    Card Data

    An important input for any of the Web SDK methods is the details of the card holder. The card holder information can be received in either one of the following options:

    The card holder data is always placed under the paymentOption class, which is the input field to receive the card holder data. This applies to the following 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 initPayment() 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
    6
    
        var sfc = SafeCharge({
            sessionToken : '09f29859-caf0-4cf7-abba-69e1bc81c6e4', // sessionToken generated by your server
            env: 'prod', // the environment you’re running  on
            merchantId: '111', // your merchant id provided by Safecharge
            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 initPayment 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 flexibility 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

    An example of selecting an element and invoking the 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 SafeCharge Fields, the Web SDK sends “change” events, which provide the following information about the Fields status:

    For errors, the following events are thrown:

    Error samples:

    SDK Methods

    createPayment()

    Use this method to perform end-to-end card payment processing. The method receives any form of cardholder information, either tokenized or not, and performs the process through to the end, including seamlessly performing any 3D Secure or PCI requirement.

    Before calling createPayment(), you must first open an order on the server side using the openOrder API call and initialise the Web SDK as described in the previous Web SDK Initialisation section.

    INPUT

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String
    Required
    The sessionToken retrieved from a call to /openOrder that references the created order in SafeCharge system
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Required
    ID of the user in the merchant’s system.
    clientUniqueId
    String(45)
    Optional
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    This field is mandatory when using the Web SDK createPayment method.
    amount
    Double(12)
    Required
    The transaction amount.
    This field is mandatory when using the Web SDK createPayment method.
    paymentOption
    class
    This field collects the card. It can receive either a reference to a card instance, as received from SafeCharge Fields, or it can be explicitly set by either of the two following options:
    By a card class, with the following fields:
    - cardNumber, string(20) – The card number
    - cardHolderName, string(70) – The card holder name
    - expirationMonth, string(2) – The card expiration month
    - expirationYear, string(4) – The card expiration year
    - CVV, string(4) – The CVV/CVC security code
    Or by a userPaymentOptionId field, received from a previous transaction with SafeCharge that represents and tokenizes the cardholder card information.
    Read more
    Read less

    OUTPUT

    You can get the response in two separate ways (either or both):

    Output 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
    
    {
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "errCode": 0,
    "orderId": "241494183",
    "authCode": "1234567",
    "userTokenId": "someone@site.com",
    "paymentOption": {
        "userPaymentOptionId": "8348263",
        "card": {
            "ccCardNumber": "5****8464",
            "bin": "511580",
            "last4Digits": "8464",
            "ccExpMonth": "01",
            "ccExpYear": "20",
            "cvv2Reply": "",
            "avsCode": ""
        }
    },
    "gwErrorCode": 0,
    "gwErrorReason": "",
    "gwExtendedErrorCode": 0,
    "transactionType": "Auth3D",
    "transactionId": "1110000000000347161",
    "externalTransactionId": "",
    "customData": "",
    "sessionToken": "5bd76168-844c-4fb1-9cfb-f7812ca31950",
    "clientUniqueId": "695701003",
    "internalRequestId": 134148663,
    "merchantId": "5288945245833474115",
    "merchantSiteId": "51001",
    "clientRequestId": "20190411173319",
    "version": "1.0",
        "timeStamp": "20170118191845",
        "checksum": "649c79075b9147de12d2b0ff62484a09"
    
    }
    
    PARAMETER DESCRIPTION
    result
    String(20)
    The cashier status of merchant request. Possible statuses:
    APPROVED
    DECLINED
    ERROR
    errorCode
    String(11)
    If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0.
    Values as detailed in Errors and Declines. In addition, it can have the value of “-5”, which means the 3D Secure process was aborted.
    errorDescription
    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.
    Values as detailed in Errors and Declines. In addition, it can have the value of “General 3D error”, which means the 3D Secure process was aborted.
    Read more
    Read less
    Canceled
    Boolean
    If the process was canceled by the end user
    transactionId
    String(20)
    The gateway transaction ID.
    ccCardNumber
    String(20)
    The credit card number in a mask, for example: 4****1111.
    bin
    String(2)
    The bin number representing the issuer.
    last4Digits
    String(4)
    The last four digits of the card number.
    ccExpMonth
    String(2)
    The expiration month
    ccExpYear
    String(4)
    The expiration year.
    userPaymentOptionId
    String
    This field represents the ID for the newly created payment option, which can be referenced in future requests.
    Refer to Returning Users for further details.

    authenticate3d()

    Use this method to perform a 3D-only authorisation request. The output of this request (mainly the CAVV and ECI values) can be used to process a card payment with any PSP or acquirer and thus benefit from the 3D Secure liability shift.

    This is also the quickest way for a merchant to migrate to 3D Secure 2.0, just by calling this method on the client side and using the CAVV and ECI method with your existing integration – either with SafeCharge or any other PSP.

    Before calling authenticate3d(), you must first call the openOrder API call on the server side and initialise the Web SDK as described in the earlier Web SDK Initialisation section.

    INPUT

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String
    Required
    The sessionToken retrieved from a call to /openOrder that references the created order in the SafeCharge system.
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Required
    ID of the user in the merchant’s system.
    clientUniqueId
    String(45)
    Optional
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    This field is mandatory when using the Web SDK createPayment method.
    amount
    Double(12)
    Required
    The transaction amount.
    This field is mandatory when using the Web SDK createPayment method.
    paymentOption
    class
    This field collects the card. It can receive either a reference to a card instance, as received from SafeCharge Fields. or it can be explicitly set by either of the two following options:
    By a card class, with the following fields:
    - cardNumber, string(20) – the card number
    - cardHolderName, string(70) The card holder name
    - expirationMonth, string(2) – card expiration month
    - expirationYear, string4() – card expiration year
    - CVV, string(4) – The CVV/CVC security code
    Or by a userPaymentOptionId field, received from a previous transaction with SafeCharge that represents and tokenizes the cardholder card information.
    Read more
    Read less

    OUTPUT

    You can get the response in two separate ways (either or both):

    The following are the most important output fields you should examine:

    (For the complete response specification, please refer to the /payment output table chapter.)

    Output Parameters

    PARAMETER DESCRIPTION
    eci
    String(2)
    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.
    Read more
    Read less
    cavv
    String(50)
    The card authentication verification value as received from the MPI.
    xid
    String(50)
    The transaction ID received from the MPI for 3D v1.
    dsTransId
    String(30)
    The transaction ID received from the MPI for 3D v2.
    result
    String(20)
    The cashier status of merchant request. Possible statuses:
    APPROVED
    DECLINED
    ERROR
    errorCode
    String(11)
    If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0.
    Values as detailed in Errors and Declines. In addition, it can have the value of “-5”, which means the 3D Secure process was aborted.
    errorDescription
    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.
    Values as detailed in Errors and Declines. In addition, it can have the value of “General 3D error”, which means the 3D Secure process was aborted.
    Read more
    Read less
    Canceled
    Boolean
    If the process was canceled by the end user
    transactionId
    String(20)
    The gateway transaction ID.
    ccCardNumber
    String(20)
    The credit card number in a mask, for example: 4****1111.
    bin
    String(2)
    The bin number representing the issuer.
    last4Digits
    String(4)
    The last four digits of the card number.
    ccExpMonth
    String(2)
    The expiration month
    ccExpYear
    String(4)
    The expiration year.
    userPaymentOptionId
    String
    This field represents the ID for the newly created payment option, which can be referenced in future requests.
    Refer to Returning Users for further details.

    initPayment()

    This method performs the payment initialisation and 3D Secure initialisation of a transaction, as well as performs 3D Secure data collection and fingerprinting.

    paymentFrame()

    This method performs the 3D Secure challenge in a 3D Secure flow.

    It receives a paymentOption input that was received from a call to the payment API call and performs the 3D Secure challenge.

    At the end, it returns the challenge output – either Success or Failure.

    getToken()

    This method performs a tokenization only for a card input. The token is returned as the ccTempToken field under the card block, which is under the paymentOption block.

    Payment API

    /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 DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    clientRequestId
    String(255)
    Required
    ID of the API request in merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the following format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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 DESCRIPTION
    sessionToken
    String(36)
    The returned session identifier returned. To be used as an input.
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    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.

    /openOrder

    This method opens a session, sets an Order in the system, and retrieves the sessionToken. The sessionToken is required for any request to the SafeCharge API as an authentication indicator.

    The primary purpose of the openOrder method is to authenticate the merchant of the request, therefore the only mandatory fields are the ones that are required for the authentication:





    Input Parameters

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/openOrder.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
    
    {
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "userTokenId": " 487106",
        "clientUniqueId": "12345",
        "clientRequestId": "1484759782197",
        "currency": "USD",
        "amount": "10",
        "amountDetails": {
            "totalShipping": "0",
            "totalHandling": "0",
            "totalDiscount": "0",
            "totalTax": "0"
        },
        "items": [{
            "name": "name",
            "price": "10",
            "quantity": "1"
        }],
        "deviceDetails": {
            "deviceType": "DESKTOP",
            "deviceName": "",
            "deviceOS": "",
            "browser": "",
            "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",
            "sippingCounty":""
        },
        "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": ""
            }
        },
        "timeStamp": "20170118191751",
        "checksum": "6b53666fc048a825be63cbb820da467b"
    }
    
    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Optional
    ID of the user in the merchant’s system.
    clientUniqueId
    String(45)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    clientRequestId
    String(255)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    currency
    String(3)
    Conditional
    The three character ISO currency code.
    This field is mandatory when using the Web SDK createPayment method.
    amount
    Double(12)
    Conditional
    The transaction amount.
    This field is mandatory when using the Web SDK createPayment method.
    amountDetails
    Class
    Optional
    totalShipping
    totalHandling
    totalDiscount
    totalTax

    The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
    Read more
    Read less
    items
    Class
    Optional
    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.
    Read more
    Read less
    deviceDetails
    Class
    Optional
    deviceType (String, 10)
    deviceName (String, 255)
    deviceOS (String, 255)
    browser (String, 255)
    ipAddress (String, 15)

    Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognised).
    Read more
    Read less
    userDetails
    Class
    Optional
    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)(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.
    Read more
    Read less
    shippingAddress
    Class
    Optional
    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(100)
    shippingCounty (String, 255)
    addressLine2 (string, 50)
    addressLine3 (string, 50)
    If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using the billingAddress parameter.
    Read more
    Read less
    billingAddress
    Class
    Optional
    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)
    addressMatch (String, 1) – Set to “Y” when address matches shipping address
    addressLine2(String, 50)
    addressLine3(String, 50)
    homePhone(String)
    workPhone (String)
    Read more
    Read less
    dynamicDescriptor
    Class
    Optional
    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 the customer support phone number or the support email address or the merchant URL for Card Not Present requests and the city in which the terminal is located for Card Present/Point Of Sale requests.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    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 will not be passed to the payments gateway and will not be used for processing.
    Read more
    Read less
    urlDetails
    Class
    Optional
    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)
    Read more
    Read less
    addendums
    Class
    Optional
    This block contains industry specific addendums. The addendum fields that appear are based on the specific addendum type.

    For example, the localPayment addendum will include:
    nationalId
    debitType
    firstInstallment
    periodicalInstallment
    numberOfInstallments

    Please note that the possible values for the debitType parameter are:
    1 – Singular payment
    2 – Instalments
    3 – Special debit

    The nationalId parameter must be sent during 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.
    Read more
    Read less
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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
    
    {
        "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
        "orderId": "39272",
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "userTokenId": "487106",
        "clientUniqueId": "12345",
        "clientRequestId": "1484759782197",
        "merchantDetails": {
            "customField1": "",
            "customField2": "",
            "customField3": "",
            "customField4": "",
            "customField5": "",
            "customField6": "",
            "customField7": "",
            "customField8": "",
            "customField9": "",
            "customField10": "",
            "customField11": "",
            "customField12": "",
            "customField13": "",
            "customField14": "",
            "customField15": ""
        },
        "internalRequestId": "866",
        "status": "SUCCESS",
        "errCode": "0",
        "reason": "",
        "version": "1.0"
    }
    
    PARAMETER DESCRIPTION
    sessionToken
    String
    Session identifier to be used by the request that processed the newly opened order.
    orderId
    String
    The order ID provided by SafeCharge.
    merchantId
    String
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String
    ID of the user in the merchant’s system.
    clientUniqueId
    String
    ID of the transaction in the merchant’s system.
    clientRequestId
    String
    ID of the API request in the merchant’s system.
    internalRequestId
    String
    SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
    merchantDetails
    Class
    customField1
    customField2
    customField3
    customField4
    customField5
    customField6
    customField7
    customField8
    customField9
    customField10
    customField11
    customField12
    customField13
    customField14
    customField15
    Read more
    Read less
    status
    String
    The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
    errCode
    String
    If an error occurred on the request side, an error code is returned in this parameter.
    reason
    String
    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
    Integer
    The current version of the request. The current version is 1.

    /payment

    The payment method is your endpoint for performing payment of any kind:

    MANDATORY FIELDS

    SELECTING A PAYMENT METHOD (paymentOption CLASS)

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



    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
    
    {
      "merchantSiteId": "51001",
      "merchantId": "5288945245833474115",
      "sessionToken": "{{sessionToken}}",
      "clientRequestId": "20190605094208",
      "timeStamp": "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",
        "phone": "phone",
      },
      "shippingAddress": {
        "address": "address",
        "city": "city",
        "country": "DE",
        "state": "",
        "zip": "1340"
      },
      "billingAddress": {
        "address": "address",
        "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 DESCRIPTION
    merchantId
    String(20)
    Required
    The merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    The merchant Site ID provided by SafeCharge.
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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
    Read more
    Read less
    currency
    String(3)
    Required
    The three-character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption
    Class
    Required
    This class represents the details on the payment method.
    Can be one of 3 options:
    card – Represents a credit/debit card. Fields:
    - cardNumber, string(20) – The card number
    - cardHolderName, string(70) – The card holder name
    - expirationMonth, string(2) – The card expiration month
    - expirationYear, string(4) – The card expiration year
    - CVV, string(4) – The CVV/CVC security code
    - threeD, (class) – Stores the 3D information. Please refer to threeD class.
    -or-
    alternativePaymentMethod – Represents an alternative payment method. For details, please refer to alternativePaymentMethod Class
    -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 previous uses.
    Read more
    Read less
    transactionType
    String(45)
    The type of transaction: Sale or Auth.
    The default setting is Sales. If you wish to change the default setting, please contact SafeCharge’s Integration Team at integration@safecharge.com.
    subMethodDetails
    Class
    Optional
    subMethod(String) – details below
    email(String) – details below

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

    Supported Flows:
  • PayPal quick registration mode
         subMethod should be set to QuickRegistration. No other fields are required.
  • PayPal Membership Agreement
         subMethod should be set to referenceTransaction.
  • Skrill1tap
         subMethod should be set to skrill1Tap. No other sub method fields are required.
         email field should be provided.
  • Trustly PayNPlay
         subMethod should be set to PayNPlay.
  • Post Finance Alias Recurring
         subMethod should be set to AliasRegistration.
  • Read more
    Read less
    relatedTransactionId
    String(19)
    Conditional
    Mandatory in the following cases:
    For 3D Secure 2.0 (refer to 3D Secure 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.
    Read more
    Read less
    orderId
    String(45)
    Optional
    The order ID provided by SafeCharge.
    This parameter is passed to define which merchant order to update.
    userTokenId
    String(255)
    Optional
    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)
    Optional
    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 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.
    Read more
    Read less
    clientRequestId
    String(255)
    Optional
    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 to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
    isPartialApproval
    String(1)
    Optional
    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. 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
    Read more
    Read less
    amountDetails
    Class
    Optional
    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.
    Read more
    Read less
    items
    Class
    Optional
    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.
    Read more
    Read less
    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 recognised). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.
    Read more
    Read less
    userDetails
    Class
    Optional
    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)
    Read more
    Read less
    shippingAddress
    Class
    Optional
    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)
    Read more
    Read less
    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)
    address2 (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.
    Read more
    Read less
    dynamicDescriptor
    Class
    Optional
    descriptorMerchantName (String, 25, not mandatory)
    descriptorMerchantPhone (String, 13, not mandatory)
    merchantDetails
    Class
    Optional
    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)
    Read more
    Read less
    urlDetails
    Class
    Optional
    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)
    Read more
    Read less
    customSiteName
    String(50)
    Optional
    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)
    Optional
    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)
    Optional
    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)
    Optional
    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 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.
    Read more
    Read less

    Output Parameters

    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.

    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 DESCRIPTION
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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 represents the data retrieved from the processed payment method. Can be either card, or in case of alternative payment method, it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below:

    redirectUrl – String() – The redirect URL to follow for an alternative payment method, which needs to be redirected to in order to process.
    -or-
    Card – Information about the card that was processed:
    bin (String) – The bin number representing the issuer.
    last4Digits (String) – The last four digits of the card number.
    ccCardNumber (String) – The credit card number in a mask, for example:***1111
    ccExpMonth (String) – The expiration month.
    • ccExpYear (String) – 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) – Contains the required 3D Secure information. Refer to the threeD (out) chapter for details.

    userPaymentOptionId – In addition to the above, this field represents the ID for the newly created payment option, which can be referenced in future requests.
    For full details, refer to Returning Users.
    Read more
    Read less
    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.
    Read more
    Read less
    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 authorisation code of the transaction.
    partialApprovalDetails
    Class
    This determines whether or not the transaction is a partial approval, plus 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)
    Read more
    Read less
    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)
    score (decimal)
    recommendations (String)
    system {systemId(String),systemName (String),decision (String)
    rules [ruleId(String),ruleDescription (String)]}

    The 'score’ refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model.
    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:
  • Accept – The risk management system accepts the transactions.
  • Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorisation. The reasons are returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review, but still accepts the transaction.
  • Error – An error occurred during the risk management system operation. The gateway continues to process the transaction through the bank.
  • 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.
    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less

    /settleTransaction

    The settleTransaction method is used for settling an authorisation transaction that was previously performed, with a two-phase Auth-Settle process, for either a full or partial settlements. When partial settlements are issued – multiple settlement 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":"",
            "ticketIssueAddress":"",
            "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 DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    clientRequestId
    String(128)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    clientUniqueId
    String(255)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent 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.
    Read more
    Read less
    amount
    Decimal
    (12)
    Required
    The transaction amount.
    currency
    String(3)
    Required
    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)
    Required
    The ID of the original transaction to be refunded.

    The value sent must contain digits only, meaning this string value cannot contain any character that is not a digit.
    authCode
    String(128)
    Required
    The authorisation code of the original transaction to be refunded.
    descriptorMerchantName
    String(25)
    Optional
    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 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.
    Read more
    Read less
    descriptorMerchantPhone
    String(13)
    Optional
    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 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.
    Read more
    Read less
    comment
    String(255)
    Optional
    Enables the addition of a free text comment to the request.
    urlDetails
    Class
    Optional
    notificationUrl(String, 1000)

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    addendums
    Class
    Optional
    This block contains industry specific addendums. 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.
    Read more
    Read less
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    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)
    Optional
    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)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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.
    Read more
    Read less

    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 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)
    Authorisation 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 either in full or partially. 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 DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    clientRequestId
    String(128)
    Required
    ID of the API request in merchant system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    clientUniqueId
    String(255)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent 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)
    Required
    The transaction amount.
    currency
    String(3)
    Required
    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)
    Required
    The ID of the settle transaction.

    The value sent must contain digits only, meaning this string value cannot contain any character that is not a digit.
    authCode
    String(128)
    Required
    The authorisation code of the related settle transaction, to be compared to the original one.
    This is mandatory for cards, non-mandatory for APMs.
    comment
    String(255)
    Optional
    Enables the addition of a free text comment to the request.
    urlDetails
    Class
    Optional
    notificationUrl(String, 1000)

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    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)
    Optional
    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)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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 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)
    Authorisation 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 authorisation, 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 DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    clientRequestId
    String(128)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    clientUniqueId
    String(255)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent 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)
    Required
    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)
    Required
    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)
    Required
    The ID of the original auth transaction.

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

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    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 parameter maximum length.
    customData
    String(255)
    Optional
    This parameter can be used to pass any type of information.
    If it is sent in the request, then it is passed on to the payments gateway and is visible in SafeCharge’s back-office tool for transaction reporting and is returned in response.
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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 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)
    Authorisation 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 it is sent in the request, then it is passed on to the payments gateway and is visible in SafeCharge’s back-office tool for 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 performing a payout (transfer funds from merchant to consumer, with no connection 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 DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Required
    ID of the user in the merchant’s system.
    clientRequestId
    String(255)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    clientUniqueId
    String(45)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent 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)
    Required
    The transaction amount.
    currency
    String(3)
    Required
    The three character ISO currency code.
    dynamicDescriptor
    Class
    Optional
    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.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    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 payments gateway and is not be used for processing.
    Read more
    Read less
    cardData
    Class
    Optional
    cardNumber(String, 20)
    cardHolderName(String, 70)
    expirationMonth(String, 2)
    expirationYear(String, 4)

    An alternative to sending the paymentOptionId for card payouts. Merchant has to be PCI ceritifed to use this, as it uses clear text card numbers.
    When sending cardData you must also send userTokenId
    Read more
    Read less
    userPaymentOption
    Class
    Required
    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.
    Read more
    Read less
    comment
    String(255)
    Optional
    Enables the addition of a free text comment to the request.
    urlDetails
    Class
    Optional
    notificationUrl(String, 1000)

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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 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, 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 payments gateway and is not used for processing.
    Read more
    Read less
    userPaymentOptionId
    String
    The first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and returns 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 a SafeCharge hosted payment page instead of building its own payment page UI, then this method allows retrieving 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 DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Required
    ID of the user in the merchant’s system.
    clientUniqueId
    String(45)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    clientRequestId
    String(255)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    currency
    String(3)
    Required
    The three character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount.
    amountDetails
    Class
    Required
    totalShipping
    totalHandling
    totalDiscount
    totalTax
    itemOpenAmount1
    itemMinAmount1
    itemMaxAmount1
    numberOfItems

    The items’ 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.
    Read more
    Read less
    productId
    String(50)
    Optional
    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)
    Optional
    This value is a promotional code the merchant can define 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.
    Read more
    Read less
    items
    Class
    Optional
    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, its value represents the number of items sent in this items block.
    Read more
    Read less
    shippingAddress
    Class
    Optional
    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 must be sent using the billingAddress parameter.
    Read more
    Read less
    billingAddress
    Class
    Required
    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 the country parameter is always mandatory.
    Read more
    Read less
    dynamicDescriptor
    Class
    Optional
    merchantName(String, 25)
    merchantPhone(String, 13)

    This allows the merchant to define a dynamic descriptor, which appears 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.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    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 which is not passed to the payments gateway and is not used for processing.
    Read more
    Read less
    customData
    String(25)
    Optional
    General data about the customer provided by the merchant.
    If it is sent in a request, then it is passed on to the payments gateway and is visible in SafeCharge’s back-office tool for transaction reporting and is returned in response.
    addendums
    Class
    Optional
    This block contains industry specific addendums. 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.
    Read more
    Read less
    urlDetails
    Class
    Optional
    successUrl
    failureUrl(String, 1000)
    pendingUrl(String, 1000)
    notificationUrl(String, 1000)
    backUrl(String, 1000)

    Each parameter is limited for up to 1000 characters.
    Read more
    Read less
    skipReviewTab
    String(5)
    Optional
    Indicating wheth*er or not to skip the payment page review page.
    Possible values: *
    true
    or false.
    customeSiteName
    String(50)
    Optional
    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)
    Optional
    The default language. The current default value is English (for example: for English (US) the value is en_US).
    encoding
    String(20)
    Optional
    The type of character encoding. Default value is ISO-8859-1.
    paymentMethod
    String(256)
    Optional
    The type of payment method selected by the customer (pre-selected):
    credit card: cc_card
    debit card: dc_card
    APMs: SafeCharge’s unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see APM Unique SafeCharge Names.
    Read more
    Read less
    paymentMethodMode
    String
    Optional
    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)
    Optional
    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.).
    Read more
    Read less
    userPaymentOptionId
    String
    Optional
    If input parameter userToken=readonlyupo and userPaymentOptionId parameter is sent, then the consumer is presented only with this sent userPaymentOption that was used previously to registered.
    themeId
    String
    Optional
    This parameter is configured per merchant site, but if sent as input it overrides the configuration, and the selected themeId is presented.
    invoiceId
    String(100)
    Optional
    A unique invoice identifier provided by the merchant or randomly generated.
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    isNative
    String(1)
    Optional
    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)
    Optional
    This parameter determines the point in time in the customer’s life cycle at which the merchant would like to initiate automated KYC checks.
    Possible values:
    PreDeposit – KYC is checked before a user places a deposit. After successful verification, the user is automatically re-directed to the SafeCharge cashier deposit page
    postDeposit – KYC is checked after a user places a successful deposit
    preWithdrawal – KYC is checked upon a user placing a Withdrawal request
    Note: When a merchant wishes to perform a check in the customer’s registration process without a redirection to the deposit page afterwards, the eKYC.do API method should be used.
    Read more
    Read less
    ekycFlow
    String(TBD)
    Optional
    This parameter describes the business logic layer of the KYC checks, allowing a merchant to perform one of the following:
    EKYC_ONLY – perform only this type
    DOC_VER_ONLY – perform only this type
    FULL – Always do both

    CASCADING or empty value – Do both only in a case of a fallback (cascading direction is always from eKYC to document verification)
    Read more
    Read less
    ekycType
    String(TBD)
    Optional
    This parameter controls the sub-checks category of the eKYC required in the API call.
    Bureau – Performs eKYC check that validates a name against an address and date of birth
    PEP_Sanctions – Performs Pep & sanctions checks (politically exposed persons and sanctions lists lookup)
    All – Performs both Bureau and Pep & sanctions checks
    Read more
    Read less
    dateOfBirth
    String
    Optional
    If value is sent in kyc parameter, then it is mandatory to send the consumer date of birth as it is required for KYC processing.
    building
    String
    Optional
    If value is 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)
    Optional
    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)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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 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.

    /initPayment(API)

    This method initiates the payment process for transactions. It is recommended to 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

    Definition

    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
    
    {
                    "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 Address Line 2", 
                                    "addressLine3": "Billing Address 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",
                    "timeStamp": "20190617110903",
                    "checksum": "eaca71a67d972fd47b796a02cf02b51844c8adeba734c54fea504c69bb16a171"
    }
    

    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
    
    {
        "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"
                    "directoryServerId":"A000000003",
                    "directoryServerPublicKey":"MIIFrjCCBJagAwIBAgIQB2rJm.."
                },
                "ccExpMonth": "12",
                "ccExpYear": "25",
                "last4Digits": "5761"
            }
        },
        "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
        "userTokenId": "230811147",
        "status": "SUCCESS"
    }
    
    Parameter Description
    sessionToken
    String(36)
    Required
    The session identifier returned by /getSessionToken.
    orderId
    String(45)
    Optional
    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)
    Required
    The merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    The merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Optional
    The ID of the user in merchant system.
    clientUniqueId
    String(45)
    Required
    The ID of the transaction in merchant system.
    clientRequestId
    String(255)
    Required
    The ID of the API request in merchant system.
    currency
    String(3)
    Required
    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)
    Required
    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
    The device’s details (conditional per configuration).
    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 recognised).
    Read more
    Read less
    paymentOption
    Class
    Required
    Card payment information inside the card sub-class
    paymentOption.card
    Class
    Required
    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)

    threeD class with the following field:
    threeD.methodNotificationUrl (string, 255) – The URL the ACS redirects to after performing the 3DS 2.0 fingerprinting. Refer to the 3D Secure 2.0 guide for details.
    Read more
    Read less
    customData
    String(255)
    Optional
    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)
    Optional
    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 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.
    Read more
    Read less
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss.
    checksum
    Hexi-decimal
    String(256)
    Required
    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
    Read more
    Read less

    RESPONSE PARAMETERS

    Parameter Description
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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.
    Read more
    Read less
    gwErrorReason
    String(400)
    The error reason, if an error 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.
    Read more
    Read less
    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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 the threeDSMethod in the 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).

    directoryServerId (String) – The 3DS directory server ID. Relevant only for the 3D Mobile SDK
    directoryServerPublicKey (String) – The 3DS directory public encryption key. Relevant only for the 3D Mobile SDK
    Read more
    Read less

    MPI Methods

    /authorize3d (API)

    Call this method if you need to use the SafeCharge MPI service to perform a 3D Secure only request. This method is called after the /initPayment method and returns the information regarding whether the merchant has to perform a Challenge or if they receive a frictionless response.
    This method has the exact same fields and works the same as the /payment method, with only the following differences:

    All are under the acquirer class, which is under the threeD class as described in the following table:

    PARAMETER DESCRIPTION
    bin
    String
    The BIN number representing the acquirer in which the transaction is eventually processed, following the 3D authentication process.
    merchantId
    String
    Your merchant ID (MID) with the acquirer you are going to process the transaction with.
    merchantName
    String
    Your merchant name as registered with the acquirer you are going to process the transaction with.



    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
    
    {  
       "merchantSiteId":"51001",
       "merchantId":"5288945245833474115",
       "sessionToken 9e07802d-5126-4b02-b4b3-ef09dfb94219",
       "clientRequestId":"20190605094208",
       "clientUniqueId":"uniqueIdCC",
       "currency":"EUR",
       "amount":"10",
       "paymentOption":{  
          "card":{  
             "cardNumber":"5115806139808464",
             "cardHolderName":"test name",
             "expirationMonth":"01",
             "expirationYear":"2020",
             "CVV":"122",
             "threeD":{  
                "acquirer":{  
                   "bin":"411111",
                   "merchantId":"123456789",
                   "merchantName":"Merchant Inc."
                },
                "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"
       },
       "shippingAddress":{  
          "address":"address",
          "city":"city",
          "country":"DE",
          "state":"",
          "zip":"1340"
       },
       "billingAddress":{  
          "address":"address",
          "city":"city",
          "country":"DE",
          "state":"",
          "zip":"1335"
       },
       "merchantDetails":{  
          "customField1":"customField1",
          "customField2":"customField2",
          "customField3":"customField3",
          "customField4":"customField4",
          "customField5":"customField5"
       }
    }
    

    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 DESCRIPTION
    merchantId
    String(20)
    Required
    The merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    The merchant Site ID provided by SafeCharge.
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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
    Read more
    Read less
    currency
    String(3)
    Required
    The three-character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption
    Class
    Required
    This class represents the details about the payment method.
    Can have either card, alternativePaymentMethod, or userPaymentOptionId:
    card class has the following fields:
    cardNumber string(20) – The card number
    cardHolderName string(70) – The card holder name
    expirationMonth string(2) – Card expiration month
    expirationYear string4() – Card expiration year
    CVV string(4) – The CVV/CVC security code
    threeD (class) – Contains the required 3D Secure information. Refer to the threeD (in) section for details.
    -or-
    alternativePaymentMethod class – Contains the relevant field required for the specific payment method. Please refer to alternativePaymentMethod Class for details.
    -or-
    userPaymentOptionId – This is a field identifying a payment option that has already been used by the customer and is now requested for re-use. SafeCharge keeps payment option details from previous uses.
    Read more
    Read less
    relatedTransactionId
    String(19)
    Required
    Sets the transactionId returned from the preceding initPayment call.
    orderId
    String(45)
    Optional
    The order ID provided by SafeCharge.
    This parameter is passed to define which merchant order to update.
    userTokenId
    String(255)
    Optional
    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)
    Optional
    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 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.
    Read more
    Read less
    clientRequestId
    String(255)
    Optional
    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 to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    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 recognised). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.
    Read more
    Read less
    userDetails
    Class
    Optional
    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)
    Read more
    Read less
    shippingAddress
    Class
    Optional
    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)
    Read more
    Read less
    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)
    address2 (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.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    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)
    Read more
    Read less
    urlDetails
    Class
    Optional
    Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
    pendingUrl (string, 1000)
    customSiteName
    String(50)
    Optional
    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)
    Optional
    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)
    Optional
    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)
    Optional
    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 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.
    Read more
    Read less

    Output Parameters

    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.

    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
    
    {  
       "orderId":"241494183",
       "paymentOption":{  
          "userPaymentOptionId":"8348263",
          "card":{  
             "ccCardNumber":"5****8464",
             "bin":"511580",
             "last4Digits":"8464",
             "ccExpMonth":"01",
             "ccExpYear":"20",
             "cvv2Reply":"",
             "avsCode":"",
             "threeD":{  
                "acsUrl":"https://qa1-tlv-acq1:4434/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmlj...",
                "eci":"7",
                "termUrl":"https://srv-bsf-devppptrunk.gw-4u.com/ppp/api/threeDSecure/completePayment.do?sessionToken\u003d04fcc8cf-3789-4936-b690-9801261f83a9",
                "whiteListStatus":"",
                "cavv":"",
                "acsChallengeMandated":"Y",
                "cReq":"eyJ0aHJlZURTU...",
                "authenticationType":"01",
                "cardHolderInfoText":"",
                "xid":"",
                "result":"C",
                "version":"2.1.0",
                "acsTransID":"541a88a9-f01f-4206-9137-ec1bed295955",
                "dsTransID":"f0ff3e24-cdf6-4561-900b-849a5054d776"
             }
          }
       },
       "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 DESCRIPTION
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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 represents the data retrieved from the processed payment method. Can be either card, or in case of alternative payment method it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below:
    redirectUrl String() – The redirect URL to follow in case of alternative payment method, which to process needs to be redirected to.
    -or-
    Card – Information about the card that was processed:
    bin (String) – The bin number representing the issuer.
    last4Digits (String) – The last four digits of the card number.
    ccCardNumber (String) – The credit card number in a mask, for example: ***1111
    ccExpMonth (String) – The expiration month.
    ccExpYear (String) – 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) – Contains the required 3D Secure information. Refer to the threeD (out) section for details.
    -or-
    userPaymentOptionId – In addition to the above, this field represents the ID for the newly created payment option, which can be referenced in future requests.
    For full details, refer to Returning Users.
    Read more
    Read less
    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.
    Read more
    Read less
    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 authorisation code of the transaction.
    partialApprovalDetails
    Class
    This determines whether or not the transaction is a partial approval, plus 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)
    Read more
    Read less
    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)
    score (decimal)
    recommendations (String)
    system {systemId(String),systemName (String),decision (String)
    rules [ruleId(String),ruleDescription (String)]}

    The 'score’ refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model.
    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:
  • Accept – The risk management system accepts the transactions.
  • Reject – The risk management system rejects the transaction. The transaction not passed to bank for authorisation. The reasons are returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review, but still accepts the transaction.
  • Error – An error occurred during the risk management system operation. The gateway continues to process the transaction through the bank.
  • 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.
    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less

    /verify3d

    Call this method if you need to use the SafeCharge MPI service to perform a 3D Secure only request. This method is called after the /authorize3d method in case of the Challenge.

    This method retrieves the generic 3D Secure result (ECI and CAVV) that you need to send to your PSP or acquirer to benefit from the 3D Secure liability shift received from the SafeCharge 3D Secure 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
    
    {
       "merchantSiteId":"51001",
       "merchantId":"5288945245833474115",
       "sessionToken":" 9e07802d-5126-4b02-b4b3-ef09dfb94219",
       "relatedTransactionId":"2110000000000644998",
       "currency":"USD",
       "amount":"0.1",
       "paymentOption":{
          "card":{
             "cardNumber":"5413330056003511",
             "cardHolderName":"john Smith",
             "expirationMonth":"12",
             "expirationYear":"25",
             "CVV":"123"
          }
       },
       "billingAddress":{
          "country":"DE",
       },
    }
    
    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    The merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    The merchant Site ID provided by SafeCharge.
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption
    Class
    Required
    This class represents the details about the payment method.
    Can have either card, alternativePaymentMethod, or userPaymentOptionId:
    card class has the following fields:
    cardNumber string(20) – The card number
    cardHolderName, string(70) – The card holder name
    expirationMonth, string(2) – Card expiration month
    expirationYear – string(4)– Card expiration year
    CVV, string(4) – The CVV/CVC security code
    threeD (class) – Contains the required 3D Secure information. Refer to the threeD (in) section for details.
    -or-
    alternativePaymentMethod class – Contains the relevant field required for the specific payment method. Please refer to alternativePaymentMethod Class for details.
    -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 use.
    Read more
    Read less
    relatedTransactionId
    String(19)
    Required
    The transaction ID of the of the call to /authorize3d.
    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)
    address2 (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.
    Read more
    Read less

    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
    
    {
        "orderId": "29264489",
        "transactionStatus": "APPROVED",
        "transactionType": "VerifyAuth3D",
        "transactionId": "2110000000000644999",
        "customData": "customData",
        "merchantDetails": {
            "customField1": "merchantName",
            "customField2": "merchantName",
            "customField3": "merchantName",
            "customField4": "merchantName",
            "customField9": "merchantName"
        },
        "paymentOption": {
            "card": {
                "ccCardNumber": "5****3511",
                "bin": "541333",
                "last4Digits": "3511",
                "ccExpMonth": "12",
                "ccExpYear": "25",
                "threeD": {
                    "threeDFlow": "0",
                    "eci": "2",
                    "version": "2.1.0",
                    "serverTransId": "34cfeb35-5ba6-4df3-a5f1-bf4b93e14476",
                    "whiteListStatus": "",
                    "cavv": "ZkhQRHd3Mzd6Z2t2MlFLQmRMbW8=",
                    "sdk": {},
                    "xid": "",
                    "result": "Y",
                    "acsTransID": "",
                    "dsTransID": "9bd98ea9-035e-4ec3-a863-831fc547473f"
                }
            }
        },
        "sessionToken": "9e07802d-5126-4b02-b4b3-ef09dfb94219",
        "clientUniqueId": "clientUniqueId",
        "internalRequestId": 3329188,
        "status": "SUCCESS",
        "errCode": 0,
        "reason": "",
        "merchantId": "9216377689920778293",
        "merchantSiteId": "6",
        "version": "1.0",
        "clientRequestId": "20190702145241"
    }
    
    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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 represents the details about the payment method. This can be one of two options:
    card – Representing credit/debit card.
    -or-
    alternativePaymentMethod – Representing an alternative payment method.

    In addition, if a user option ID was either created or an existing one was used in the transaction, it returns the ID to this payment option:
    userPaymentOptionId – This is a field identifying a payment option that already has been used by the customer and is now requested for re-use. SafeCharge keeps the payment option details from previous uses.
    Read more
    Read less
    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.
    Read more
    Read less
    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 authorisation code of the transaction.
    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)
    score (decimal)
    recommendations (String)
    system {systemId(String),systemName (String),decision (String)
    rules [ruleId(String),ruleDescription (String)]}

    The 'score’ refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model.
    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:
  • Accept – The risk management system accepts the transactions.
  • Reject – The risk management system rejects the transaction. The transaction not passed to bank for authorisation. The reasons are returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review, but still accepts the transaction.
  • Error – An error occurred during the risk management system operation. The gateway continues to process the transaction through the bank.
  • 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.
    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less

    Class Objects

    threeD Input Class

    This class contains the 3D Secure information required as an input for /payment or /authorize3d to perform the 3D authorisation request (the first /payment call) as defined in the 3D Guide.

    Most of the fields specified in the table below are required for 3D only for the first call to /payment (or /authorize3d) that performs the 3D authorisation before proceeding for payment.
    The following are exceptions to this:

    Parameter Description
    notificationURL
    String
    Required
    The notification URL for redirecting the browser after the challenge completion, which receives the CRes message.
    merchantURL
    String
    Required
    The merchant website fully qualified URL.
    version
    String
    Required
    The 3DS version used.
    1 or empty – 3DS 1.0
    2 – 3DS 2.0
    methodCompletionInd
    String
    Required
    Indicates whether the 3DS method was successfully completed.
    Y – Successfully completed
    N – Did not successfully complete
    U – Unavailable (3DS Method URL was not present)
    platformType
    String
    Required
    The device channel.
    01 – App-based (only for SDK implementation, not in the scope of this document)
    02 – Browser
    convertNonEnrolled
    String
    Set this field to automatically convert the request for payment in case of 3DS 1.0 failure to authenticate. The transaction in this case is non-3D Secure.
    paResponse
    String
    Conditional
    The payment authorisation response returned by the card issuer/bank. Relevant only to the second payment call and only if 3D 1.0 authentication was performed.
    externalMpi
    class
    External MPI
    isExternalMpi (String,1) – Set to 1 to mark External MPI is in use.
    Eci (String,2) – The Electronic Commerce Indicator as received from the MPI
    Cavv( String50) – The card authentication verification value as received from the MPI.
    Xid (string, 50) – The transaction ID received from the MPI for 3D v1.
    dsTransID (string, 30) – The transaction ID received from the MPI for 3D v2.
    Read more
    Read less
    browserDetails
    Class
    3D 2.0
    acceptHeader (string, not mandatory)
    ip (string, not mandatory)
    javaEnabled (string, not mandatory)
    javaScriptEnabled (string, not mandatory)
    language (string, not mandatory)
    colorDepth (string, not mandatory)
    screenHeight (string, not mandatory)
    screenWidth (string, not mandatory)
    timeZone (string, not mandatory)
    userAgent (string, not mandatory)
    Read more
    Read less
    v2AdditionalParams
    Class
    3D 2.0
    For the list of parameters in this class for the new version of 3D Secure, please see the table below.
    sdk
    Class
    3D 2.0 SDK
    This class is mandatory for 3D Secure 2.0 for transactions originating from a mobile device. It contains the following 3D mobile relevant information:

    appSdkInterface – String(2) – Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.
    appSdkUIType – String(2) – Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.
    appID – String(36) – SDK App ID - guid
    encData – String(64000) – SDK Encrypted Data
    ephemPubKey – String(256) – SDK Ephemeral Public Key (Qc)
    maxTimeout –String(2) – SDK Maximum Timeout
    referenceNumber – String(32) – SDK Reference Number
    transID – String(36) – SDK Transaction ID – guid
    Read more
    Read less

    v2AdditionalParams

    Parameter Description
    challengePreference
    String
    Optional
    The 3DS challenge requestor indication.
    01 – No preference
    02 – No challenge requested
    03 – Challenge requested: 3DS Requestor Preference
    04 – Challenge requested: Mandate
    Read more
    Read less
    deliveryEmail
    String
    Optional
    For electronic delivery, the email address to which the merchandise was delivered.
    deliveryTimeFrame
    String
    Optional
    Indicates the merchandise delivery timeframe.
    01 – Electronic Delivery
    02 – Same day shipping
    03 – Overnight shipping
    04 – Two-day or more shipping
    Read more
    Read less
    giftCardAmount
    String
    Optional
    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
    Optional
    For prepaid or gift card purchase, the total count of individual prepaid or gift cards/codes purchased.
    giftCardCurrency
    String
    Optional
    For prepaid or gift card purchase, the ISO 4217 three-digit currency code of the gift card.
    preOrderDate
    String
    Optional
    For a pre-ordered purchase, the expected date that the merchandise is available (YYYYMMDD).
    preOrderPurchaseInd
    String
    Optional
    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
    01 – Merchandise available
    02 – Future availability
    PreOrderItemsInd
    String
    Optional
    Indicates whether the cardholder is reordering previously purchased merchandise.
    01 – First time ordered
    02 – Reordered
    shipIndicator
    String
    Optional
    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”/Pickup 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.)
    Read more
    Read less
    rebillExpiry
    String
    Optional
    Recurring Expiry - Required if sg_rebill = 1 (format: YYYYMMDD)
    rebillFrequency
    String
    Optional
    Recurring Expiry - Required if sg_rebill = 1 in number of days.
    challengeWindowSize
    String
    Optional
    The dimensions of the challenge window.
    01 – 250 x 4000
    02 – 390 x 4000
    03 – 500 x 6000
    04 – 600 x 4000
    05 – Full screen
    Read more
    Read less

    threeD Output Class

    This class contains the 3D Secure information returned from the call to the /payment or /authorize3d methods after performing the 3D authorisation request (the first /payment call) as defined in the 3D Guide.

    The output table is separate into 2 parts:

    The following fields are returned on the first call to /payment or /verify3d:

    PARAMETER DESCRIPTION
    acsUrl
    String
    URL or endpoint used to redirect the consumer to the card issuer/bank’s 3D Secure verification page.
    acsChallengeMandate
    String(1)
    The 3D Secure 2.0 challenge required indication.
    Possible values:
    N – not required
    Y – required (only in case of 3D Secure 2.0)
    cReq
    String
    The Base64 encoded cReq relevant for the 3D Secure 2.0.
    acsUrl is also sent as a separate field (only in case of 3D Secure 2.0)
    paRequest
    String
    The 3D Secure request data for the card issuer/bank (only in case of 3D 1.0)
    threeDFlow
    String
    Indicates which 3D flow is taking place:
  • 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 returned and the merchant does NOT need to redirect to issuer or call payment3Dmethod later on).
  • Read more
    Read less
    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.

    The following fields are returned after the challenge or after a successful frictionless (either first or second call):

    PARAMETER DESCRIPTION
    cavv
    String(28)
    A cryptogram created by the issuer that serves as a proof that the merchant is entitled to this authentication.
    eci
    String
    This is returned from banks and indicates the 3D Secure result.
    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.
    Read more
    Read less
    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.
    Returned in the end of the 3D Secure after successful frictionless.
    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
    Returned on a second call to /payment or /verify3d following a challenge.
    Read more
    Read less
    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.”
    Returned on a second call to /payment or /verify3d following a challenge
    Read more
    Read less

    alternativePaymentMethod Class

    Parameter Description
    paymentMethod
    String(50)
    Required
    Specifies the payment method name of the payment option to be charged.
    Please refer to APM ACCOUNT IDENTIFIERS (Pay In) under Supported Payment Methods.
    The second column in the Excel file shows the payment method name string to be used per each APM.
    Read more
    Read less
    Payment method fields
    Specific fields per method
    Please refer to APM ACCOUNT IDENTIFIERS (Pay In) under Supported Payment Methods.
    The third column in the Excel file details the relevant APM input fields per each APM.

    Deprecated Methods

    This section describes deprecated payment methods that are still valid, but should not be used for new integrations. They do not support newer features and do not support the new 3D Secure 2.0 initiative.

    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":"",
                "ticketIssueAddress":"",
                "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 DESCRIPTION
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    orderId
    String(45)
    Optional
    The order ID provided by SafeCharge.
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Optional
    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)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent 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)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    isDynamic3D
    String(1)
    Required
    Always send isDynamic3D = 1.
    dynamic3DMode
    String
    Optional
    If the merchant wants to force the transaction to go to 3D, send dynamic3DMode = ON.
    isRebilling
    Integer(2)
    Optional
    This indicates whether this is a regular transaction or a recurring/rebilling transaction.
    Possible values:
    0 – This is a regular transaction.
    1 – This is a recurring/rebilling transaction.
    Rebilling can be performed using userPaymentOptionId or cardData. If done using cardData, then it is highly recommended to send its relatedTransactionId as well.

    Note that if isRebilling=1 sent, then you must also send isDynamic3D=1 and dynamic3DMode=OFF.
    Read more
    Read less
    isPartialApproval
    String(1)
    Optional
    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.
    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
    Read more
    Read less
    currency
    String(3)
    Required
    The three character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount.
    amountDetails
    Class
    Required
    totalShipping(String, 255)
    totalHandling(String, 10)
    totalDiscount
    totalTax(String, 10)

    The items’ and amountDetails prices should be summed up (if device type cannot be recognised) in the amount parameter and sent separately.
    All prices must be in the same currency.
    Read more
    Read less
    items
    Class
    Required
    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.
    Read more
    Read less
    deviceDetails
    Class
    Required
    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.

    ipAddress parameter can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.
    Read more
    Read less
    userDetails
    Class
    Optional
    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 must be sent using the billingAddress parameter.
    Read more
    Read less
    shippingAddress
    Class
    Optional
    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 must be sent using the billingAddress parameter.
    Read more
    Read less
    billingAddress
    Class
    Required
    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 as needed by SafeCharge’s Integration Team.

    Note that the country parameter is always mandatory.

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

    This allows the merchant to define a dynamic descriptor, which appears in the payment statement. The name field should contain the merchant name. The phone field should contain either a 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.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    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 payments gateway and is not used for processing.
    Read more
    Read less
    cardData
    Class
    Optional
    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 is not required, you need to send it with NULL value or to not provide the CVV parameter at all in the request.

    Please avoid sending a card that was expired as it may cause a transaction to be declined.
    Read more
    Read less
    userPaymentOption
    Class
    Optional
    userPaymentOptionId(String, 45)
    CVV(String, 4)

    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 cardData (above) is not sent.

    CVV can be mandatory or non-mandatory per configuration.
    Read more
    Read less
    relatedTransactionId
    String(19)
    Required
    The ID of the original transaction. It is required in case recurring/rebilling transaction was requested (isRebilling=1 sent) using cardData and not using userPaymentOptionId.

    The value sent must contain digits only, meaning this string value cannot contain any character that is not a digit.
    Read more
    Read less
    addendums
    Class
    Optional
    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

    The nationalId parameter must 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.
    Read more
    Read less
    urlDetails
    Class
    Optional
    notificationUrl(String, 1000)

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

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

    Possible values for isExternalMpi:
    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 Electronic Commerce Indicator (ECI) that 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 if isExternalMpi=1 sent, then you must also send isDynamic3D=1 and dynamic3DMode=OFF.
    Read more
    Read less
    storedCredentials
    Class
    Optional
    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 the 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.
    Read more
    Read less
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    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)
    Optional
    This parameter can be used to pass any type of information.
    If sent in request, then it is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting, and is returned in response.
    externalTokenProvider
    Class
    Optional
    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, the following values must be passed:
    externalTokenProvider – “ApplePay”,
    mobileToken – The token received from Apple during Dynamic Server to Server JS Button Solution.
    To work with external token, providers special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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 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.
    Read more
    Read less
    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, 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 isnot passed to the payments gateway and is not used for processing.
    Read more
    Read less
    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)
    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)
    Authorisation 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 a third-party payment provider which generate card tokens).
    Read more
    Read less
    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.
    Read more
    Read less
    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 is returned in response only if its value is 1 or 6 or 7.
    Read more
    Read less
    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.
    Read more
    Read less
    avsCode
    String
    The AVS response.
    Possible values:
    A – The street address matches, the zip code does not.
    W – Whole 9-digit zip code match, the street address does not.
    Y – Both the 5-digit zip code and the street address match.
    X – An exact match of both the 9-digit zip code and the street address.
    Z – Only the 5-digit zip code matches, 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.
    Read more
    Read less
    transactionType
    String(45)
    The type of transaction: Auth3D or Sale or Auth.
    Note that this requires 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)
    score (decimal)
    recommendations(String)
    system{systemId(String), systemName(String), decision(String)
    rules[ruleId(String), ruleDescription(String)]}

    score – A number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model.
    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:
  • Accept – The risk management system accepts the transactions.
  • Reject – The risk management system rejects the transaction. The transaction not passed to bank for authorisation. The reasons returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review but still accept the transaction.
  • Error – An error occurred during risk management system operation. The gateway continues to process the transaction through the bank.
  • 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.

    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less



    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’ to complete the 'auth3D’ transaction previously performed in dynamic3D method).
    Read more
    Read less
    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.
    Read more
    Read less



    /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":"",
                "ticketIssueAddress":"",
                "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 DESCRIPTION
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    It is required to provide the same sessionToken value sent to dynamic3D method that was celled before.
    orderId
    String(45)
    Required
    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)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Optional
    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)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent 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)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    transactionType
    String(45)
    Required
    The type of transaction: Sale or Auth.
    isPartialApproval
    String(1)
    Optional
    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.
    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
    Read more
    Read less
    currency
    String(3)
    Required
    The three character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount. This amount must be identical to the amount listed in the dynamic3D.
    amountDetails
    Class
    Required
    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.
    Read more
    Read less
    items
    Class
    Required
    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.
    Read more
    Read less
    deviceDetails
    Class
    Required
    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 recognised).

    ipAddress parameter can be defined as mandatory or non-mandatory per need by SafeCharge Integration Team.
    Read more
    Read less
    userDetails
    Class
    Optional
    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.
    Read more
    Read less
    shippingAddress
    Class
    Optional
    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.
    Read more
    Read less
    billingAddress
    Class
    Required
    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 the country parameter is always mandatory.

    If billingAddress is provided when the user payment option (UPO) is created/updated, then it is used for the transaction.
    If billingAddress is sent in orders/payments methods request as a separate parameter, then it is used for the transaction, and after the transaction is performed, it overrides the one saved in the UPO.
    If billingAddress was not saved in the UPO, and was not sent in orders/payments methods request as a separate parameter, then the value from userDetails parameter is used, but billingAddress is not saved in the UPO.
    Read more
    Read less
    dynamicDescriptor
    Class
    Optional
    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 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.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    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 payments gateway and is not used for processing.
    Read more
    Read less
    addendums
    Class
    Optional
    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.
    Read more
    Read less
    cardData
    Class
    Optional
    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 a card that was expired as it may cause a transaction to be declined.
    Read more
    Read less
    userPaymentOption
    Class
    Optional
    userPaymentOptionId(String, 45)
    CVV(String, 4)

    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.
    Read more
    Read less
    paResponse
    String
    Required
    The payment authorisation response returned by the card issuer/bank.
    urlDetails
    Class
    Optional
    notificationUrl(String, 1000)

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    storedCredentials
    Class
    Optional
    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.
    Read more
    Read less
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    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)
    Optional
    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)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    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 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, 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 payments gateway and is not used for processing.
    Read more
    Read less
    errCode