Navbar
JSON Node.JS java php C#

Home

Introduction

Welcome to the SafeCharge API developers portal. This API breaks down into a 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, APMs, 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 Checkout 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.

Checkout Page

The quickest way to integrate to SafeCharge and benefit from all our features is via our 'Checkout Page’ solution.
With our Checkout Page, you only need to load the page via IFrame or by full page redirect and all features and functionalities are seamlessly integrated.

In addition, you can even perform basic customisation of your payment page via the Page Builder menu located in the Control Panel. Speak to your account manager regarding more complex customisation.

Steps for using the Checkout Page:

  1. Prepare the Authentication
  2. Submit a Request to the Checkout Page
  3. Handle the Response

STEP 1: Prepare the Authentication

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:


For example:

COPIED
1
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: Submit a Request to the Checkout Page

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):

COPIED
1
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.

STEP 3: Handle the Response

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.

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:


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

Web 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.

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

STEP 3: Generate the Payment Form

Create your payment form with the placeholder for SafeCharge Fields, which can be customised.

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>', // received from Step 1.
      env: 'int', // the environment you’re running on, if omitted prod is default
      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 Parameters table.)

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


 

API Guides

APM Submethods

In several cases, payment methods have optimised flows for certain scenarios. For example, 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.

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 submethod. 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 have their own requirements for identifying their end users.
Payment methods account fields can be sent in the getUserUPOs method (upoData parameter) and in the paymentAPM method (userAccountDetails parameter).

The following tables provide a list of the supported payment submethods:

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 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
Checkout 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:

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:

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 cumulative sum of €100, or 5 consecutive transactions since the 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 cumulative sum of €150 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. There are several use cases for handling 3D Secure, all which are covered in this section.

Best Practice Integration

The quickest and seamless way, as well as 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 summarise the steps, you need to perform the following:

If you wish to only perform the 3D Secure validation without directly proceeding to payment, please refer to 3D Secure Only Transaction (MPI) below.

3D Secure for Tokenized Cards

SafeCharge provides tokenization solutions for cases when you need to run 3D Secure transactions for tokenized cards.

Example of createPayment:


3D Secure Only Transaction (MPI)

MPI stands for Merchant Plugin, which is the 3D Secure terminology for a third-party 3D Secure provider.

These are the steps you must follow to only perform the 3D Secure validation, without processing the payment:

  1. Server-side: Call the /openOrder API method to place an order on our server.

If you would like to process the payment with another acquirer or PSP, you must also set the acquirer block under the threeD block, with the following fields:

Sample:


2. Call the JavaScript authenticate3d() method of our Web SDK. This method performs the 3D secure validation only, without continuing to payment.

The authenticate3d() method returns the 3D Secure authentication values:

After the 3D Secure validation is completed, you can use the authentication values to continue and process a 3D Secured (with liability shift) with any third-party payment provider.

Naturally, you can also process the transaction with SafeCharge using the /payment API method:

Perform a Non-3D Secure Transaction

Though not recommended, in some case you may want to avoid 3D Secure altogether. To avoid 3D Secure, you must set the paymentOption.card.threeD.dynamic3DMode field to “OFF”.

External MPI (Third-Party 3D Secure)

SafeCharge supports processing 3D Secured transactions using 3D Secure authentication values received from a third-party provider. This practice is most commonly used for merchants who are processing with more than one payment provider and have one 3D Secure provider for all their transactions.

To do this, you must be sure you retrieve the relevant 3D Secure authentication value from your third-party 3D Secure provider:

Then, when calling the SafeCharge /payment API method, you must set them in the ExternalMpi block:

Server to Server Integration

If you prefer to perform an API-only integration, meaning to not use or only partly use our Web SDK, you need to understand the full 3D Secure flow, which is illustrated and described here.

3DSecureFlow

Step 1: Authentication with /getSessionToken API

A server-side call is made to initiate the authentication with SafeCharge using /getSessionToken, an API method to initialise the security token.

Step 2: Render Payment Form

On your checkout page, you need to render the form, which collects the cardholder information details.

Step 3: Initialise 3D Secure with /initPayment API

The /initPayment(API) method does the following:

Once the payment form is submitted, you need to determine the 3D Secure version and retrieve the 3D secure version of the card. 3D 2.0 then returns the 3D method URL information, which is required for the next step.
For a full description, please refer to /initPayment(API).

Step 4: Web Browser Fingerprinting

If 3D 2.0: On the client side, you have to implement the 3D Secure method URL and collect the 3D Browser information.
According to 3D Secure 2.0, the issuer can request that you perform browser fingerprinting (also known as “Method Url”). This is a hidden IFrame that you must implement to allow the Issuer to collect thumbnail browsing information directly.
The sample code shows how to implement browser fingerprinting by using the retrieved methodUrl and methodPayload field values in the web form.

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

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

Example:

Step 5: Payment Request

After the 3D Secure initialisation is done, you are ready to submit the payment request using the /payment API. This request must include all the relevant 3D Secure fields you have collected in the previous steps. These are placed under the threeD block (which is under the paymentOption.card block).

Card details are placed under the paymentOption block:

Parsing the /payment Response
The response contains information about the transaction and about the payment, but most importantly it returns the status of the transaction – transactionStatus.
The transaction status can be:

If payment returns a frictionless response, the process ends here. If a challenge is returned, continue to the next step.

Step 6: 3D Secure Challenge

Before performing a challenge, you should first verify if a challenge is indeed required. This is done by examining the response of the preceding payment request. If the response transactionStatus is REDIRECT, it means a challenge is required; otherwise you get a transaction response (approved, declined or error). To perform a challenge, redirect the user to the Issuer Authentication URL (acsUrl) as received in the paymentOption.card.threeD.acsUrl field.

If the 3D Secure version to be performed for the cardholder is not 3D 2.0 (i.e. version 1.x), then you will need to concatenate the following HTTP GET fields to the acsUrl (not needed for 3D 2.0):

PARAMETER DESCRIPTION
PaReq
String
Required
This is the paReq (note the capitalization), same value you received with the paymentOption.card.threeD.paRequest field, with your first call to the payment API request.
TermUrl
String
Required
This is the URL your customer is returned to at the end of the 3D Secure authentication process.
MD
String
Optional
This is your merchant data, which is posted back to your TermUrl at the end of the 3D Secure authentication process.

The challenge response is received differently between versions 1.x and 2.0 of 3D Secure:
For 3DS 1.0 The response redirects to your TermUrl with the PaRes GET field set with a Base64 value that you need to submit on the following payment API call as the value for the paymentOption.card.threeD.paResponse field. For 3DS 2.0 Once a challenge is completed, the ACS/Issuer posts a CRes JSON object (encoded in Base64) to the notificationURL field supplied at the Payment. The CRes message contains the outcome of the challenge.

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

CRes Example:

Step 7: Post Challenge Payment Request

After the 3D 2.0 challenge is completed, you need to make another call to /payment. This time you do not need to provide the 3DS information (without the 3D block) and you only need to reference the first payment call using the relatedTransactionId field.

Input

Same as with the first call, with the following differences:

Output
- threeD block, which shows only the following:

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

Server to Server MPI Integration

MPI stands for Merchant Plugin, which is the 3D Secure terminology for a third-party 3D Secure provider. If you wish to consume 3D Secure services only from SafeCharge, or if you would like to separate the 3D Secure process from the payment process, you should follow the instructions the Server to Server Integration topic above but with the following differences:

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.

Checkout 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 Checkout 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

Obtaining an Apple Pay CSR

If you are a merchant and want to obtain an Apple Pay Certificate Signing Request (CSR) via Apple’s developer website, please follow these instructions.

  1. Go to https://developer.apple.com/.
  2. Click “Account” and sign in. If you do not yet have an Apple ID, click the relevant link to create one.
  3. Click “Certificates, IDs & Profiles”.



  4. Click “+”.



  5. In the Services section, select Apple Pay Payment Processing Certificate and select Continue.



  6. From the dropdown, select the relevant Merchant ID and click Continue.



  7. Answer No to the question 'Will payments associated with this Merchant ID be processed exclusively in China?’ and click Continue.
  8. Click Choose File and browse to the .csr request file you received from SafeCharge and click Continue.



  9. In the Download Your Certificate screen, click Download. When the request is received, a certificate file is downloaded to your computer.



  10. Repeat Steps ‎4 through ‎9 but in Step ‎5 select Apple Pay Merchant Identity Certificate instead and skip Step 7.
  11. Send these two received certificate files (Processing and Identity) to SafeCharge.
  12. Implement a JavaScript code that SafeCharge provides on the page that holds the cashier in IFRAME, as described in Dynamic Server to Server JS Button Solution.

SafeCharge configures Apple Pay on its backend system.

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:

Instructions

  1. Include CDN located SafeCharge provided JavaScript 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.

Checkout Page IFrame Solution using iOS SDK

This solution is relevant for a merchant that is integrated with a SafeCharge Checkout Page using the iOS SDK, which allows the merchant to present the Checkout 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.

Checkout Page IFrame Solution

This solution is relevant for a merchant that is integrated to the SafeCharge Checkout 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_resources/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. In addition, you need to create a DMN response checksum. (For more information, see Authenticating a DMN Response Checksum.)

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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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.
Read more
Read less
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 Response Codes and Gateway Filter Error Codes. 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 Response Codes and Gateway Filter Error Codes. 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.
Read more
Read less
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
Optional
This parameter shows if the payment page required existing customers to register for the specific transaction.
When user_token=register, the payment page required the customer to register even if they are already registered in the system. The previously registered payment methods are deleted.
When user_token=auto, the payment page checked the SafeCharge database to determine if the customer was already registered.
Read more
Read less
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
3DauthenticationType
Optional
Presents whether transaction has been processed via challenge or frictionless authentication flow.
The parameter should be calculated based on the combination of acsChallengeMandated/Result parameters in Auth3D response to Cashier by GW.
Values: Challenge or Frictionless
If the parameter is empty, the parameter is not included in the DMN.
This field is relevant only for a 3DS 2.0 deposit flow.
Read more
Read less
3Dauthentication
Optional
Result: ThreeDSAuthenticator -> result ->authenticationStatus.
In case of frictionless, result value in Auth3d response to Cashier.
In case of challenge, send transStatus value from CRes.
If the parameter is empty, the parameter is not included in the DMN.
This field is relevant only for a 3DS 2.0 deposit flow.
Read more
Read less
3Dreason
Optional
From final GW response to Cashier’s Sale TRX.
If the parameter is empty, the parameter is not included in the DMN.
This field is relevant only for a 3DS 2.0 deposit flow.
Read more
Read less
3DwhiteListStatus
Optional
From final GW response to Cashier’s Sale TRX.
If the parameter is empty, the parameter is not included in the DMN.
This field is relevant only for a 3DS 2.0 deposit flow.
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
The ID value that was initially passed in the merchant_unique_id parameter when making the original request to the SafeCharge Checkout Page.
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.
Read more
Read less
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.
Read more
Read less
apmPayerInfo
Optional
Additional customer information that is received back from an external alternative payment service provider.

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 (please refer to Gateway Decline Reasons below)
0
0
PENDING
-1100
greater than 0
ERROR (filter error) (please refer to Gateway 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.
Please contact SafeCharge’s Integration Team at integration@safecharge.com for further information.

EXERRCODE DESCRIPTION
1001
Invalid Expiration Date
1002
Expiration Date Too Old
1101
Invalid Card Number (Alpha Numeric)
1102
Invalid Card Number (Digits Count)
1103
Invalid Card Number (MOD 10)
1104
Invalid CVV2
1105
Auth Code/Trans ID/Credit Card Number Mismatch
1106
Credit Amount Exceed Total Charges
1107
Cannot Credit this CC company
1108
Illegal interval between auth and force
1109
Not allowed to process this CC 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
&lt;Custom Fraud Screen Filter&gt;
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 ceiling
1127
Limit exceeding amount
1128
Invalid Transaction Type Code
1129
General Filter Error
1130
Bank required fields are missing or incorrect
1131
This transaction type is not allowed for this bank
1132
Amount exceeds bank limit
1133
GW 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 CCC restriction
1138
Invalid Credit Type
1139
This card is not supported in the CFT Program
1140
Card must be processed in the GW System
1141
Transaction type is not allowed
1142
AVS required fields are missing or incorrect
1143
Country does not match ISO Code
1144
Must provide UserID in a Rebill transaction
1145
Your Rebill profile do not support this transaction type
1146
Void is not allowed due to CCC restriction
1147
Invalid Account Number
1148
Invalid Cheque Number
1149
Account Number/Trans ID Mismatch
1150
UserID/Trans Type /Trans ID Mismatch
1151
Transaction does not exist in the rebill system.
1152
Transaction was already cancelled
1153
Invalid Bank Code(Digits Count)
1154
Invalid Bank Code (Alpha Numeric)
1155
3D Related transaction is missing or incorrect
1156
Debit card required fields are missing or incorrect
1157
No update parameters were supplied
1158
3D PaRes value is incorrect
1158
PayPal account is already registered by another user
1159
State does not match ISO Code
1159
The user already registered with a different Payer email
1160
Invalid Bank Code (Checksum Digit)
1160
Single account validation failed
1161
This Bank allows only 3 digits in CVV2
1162
Age verification Failed
1163
Transaction must contain a Card/Token/Account
1164
Invalid Token
1165
Token Mismatch
1166
Invalid Email address
1167
Transaction already settled
1167
Missing external MPI parameters
1168
Transaction already voided
1169
sg_ResponseFormat field is not valid
1170
Version field is missing or incorrect
1171
Issuing Country is invalid
1172
Phone is missing or format error
1173
Check number is missing or incorrect
1174
Birth date format error
1175
Zip code format error
1176
Cannot void an auth transaction
1177
Cannot void a credit transaction
1178
Cannot void a void transaction
1179
Cannot perform this void
1180
Invalid start date
1181
Merchant Name is too long (&gt;25)
1182
Transaction must be sent as 3DSecure
1183
Account is not 3D enabled
1184
Transaction 3D status is incorrect
1185
Related transaction must be Auth3D, APPROVED, same 3DS version and same merchant
1186
Related transaction must be 3D authenticated
1187
Country does not support the CFT program
1188
Invalid token id
1190
Risk processor error
1191
RiskOnly is supported from version 4.0.0 and above
1192
AGV processor error
1193
AGVOnly is supported from version 4.0.1 and above
1194
Age verification mismatch
1195
Requested acquirer is unrecognised
1196
sale transaction isn’t processed on acquirer side yet
1197
Input data is not sufficient
1198
Credit card details are not allowed for the given Payment Method
1199
Envoy payout transaction requires credit transaction of type 1
1200
invalid issuing bank country code
1201
Invalid Amount
1202
Invalid Currency
1203
IBAN does not match country code
1204
Payment method is not supported
1205
APM risk processor error
1206
Settle amount exceeds total charges
1207
Cannot perform this credit
1208
Converted transaction cannot be handled, please use alternative interfaces
1209
Client is not allowed for Partial Approval
1210
NameOnCard is missing
1214
Invalid FinalizationURL
1220
Expired Token
1230
Invalid or missing PFSubMerchantId input parameter
1231
Invalid or missing MerchantName input parameter
1232
Invalid or missing PFSubMerchantCountry input parameter
1233
Invalid or missing PFSubMerchantCity input parameter
1265
One year passed since last sale, Payout declined
1266
Submethod not supported
1267
This card is not supported in the Visa Direct OCT program.
1268
Token is inactive
1269
Cannot get cryptogram
1270
The client is not configured to account update
1271
sg_transaction must be of type InitAuth3D, Approved and the same merchant
1272
Card number must be equal for all transaction in a specific 3DS flow
1273
Card number, Currency and Amount must be equal in a specific 3DS flow
1274
Requested Auth3D 2.0 but card number is not supported with 3DS 2.0
1275
initAuth3D represented by sg_transactionId was already used in another 3D flow
1276
authentication request could not be completed – timeout, please try again later
1277
DS responded with an error, please verify request and try again
1278
Authentication is expired, new InitAuth3d is required
1279
3D related transaction was already used for Sale/Auth
1280
Mandatory field is missing: sg_threeDSMethodNotificationURL
1281
Authentication has not completed
1282
Authentication failed
1283
Required field sg_ThreeDSPlatformType is missing or invalid
1284
Invalid external MPI parameters format
1285
Exceeding refund time frame
1500
Client Is Not Allowed To Use This Channel
1501
Client Is Not Allowed To Use Suppress Auth
1550
Not all the auto reversal parameters were sent in the request
1551
Client is not permitted to use auto reversal functionality
1552
Input parameter data type incorrect
1553
Currency of auto reversal does not match the currency of the settle
1554
Amount of auto reversal does not match the amount of the settle and auth
1555
Auto Reversal Cannot be Allowed with Multiple Settle
1556
Settle amount plus AutoReversal Amount should bequal to Original Auth
1557
Original currency does not match auto reversal currency
1558
Incorrect Auto-Reversal Input Parameters
1559
Cannot void auth, transaction has already been settled
1560
Not Allowed to Process this Auth Type
2001
The requested acquirer bank is temporarily unavailable
2002
ApmRisk is disabled
2025
External MPI not supported for this acquirer
2030
Invalid external token provider
3001
Invalid Interval for sale reversal
3002
Invalid Interval for refund reversal
3003
Invalid Interval for OCT reversal
3004
Transaction has already been reversed
3005
Transaction is not approved
3006
Transaction type does not match reversal type
3007
Transaction has not been transmitted
3008
Transaction already has chargeback record
3500
Invalid POS Parameter
3501
Mandatory POS Parameter is missing
3502
KYC parameters error
10012
Saved payment option no longer valid
10013
Cannot register payment option at APM
10014
APM authentication error

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.
Read more
Read less
-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.
Read more
Read less
-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.
Read more
Read less
-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, cancelled, 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, cancelled, 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, cancelled, or does not exist.
-1
0
Expired card
The credit card is no longer valid or was cancelled. 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.
Read more
Read less
-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.
Read more
Read less
-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.
Read more
Read less
-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.
Read more
Read less
-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.
-1
0
Soft Decline – Authentication is Advised
The issuer has declined the transaction for authentication reasons. Running the transaction again with 3DS 2.0 / 1.0 might help to get the transaction approved.

Currency Codes

The following table lists the standard ISO codes for all supported currencies.

Currency Code Currency Code
British Pound
GBP
Norwegian Krone
NOK
Euro
EUR
South African Rand
ZAR
US Dollar
USD
Swedish Krone
SEK
Hong Kong Dollar
HKD
Swiss Frank
CHF
Japanese Yen
JPY
Israeli Shekels
NIS
Australian Dollar
AUD
Mexican Pesos
MXN
Canadian Dollar
CAD
Russian Rubles
RUB
Chinese Yuan
CNY
Kazah Tenge
KZT
Slovak Koruna
SKK
New Zealand Dollar
NZD
Thai Baht
THB
Polish Zloty
PLN
Turkish Lira
TRY
Romanian New Leu
RON
Taiwan Dollar
TWD
Singapore Dollar
SGD
Estonian Kroon
EEK
Colombian Peso
COP
Hong Kong Dollar
HKD
Czech Koruna
CZK
Hungarian Forint
HUF
Danish Krone
DKK
Indian Rupee
INR
Bulgarian Lev
BGN
Icelandic Krona
ISK
Brazil Real
BRL
Ukrainian Hryvnia
UAH
Argentine Peso
ARS
South Korean Won
KRW
United Arab Emirates Dirham
AED
Egyptian Pound
EGP

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 and 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 the issuer.
Soft Decline - Authentication is Advised
4021937195658141 (UK)
4217641329972469 (US)
5118081410264525 (UK)
5109486948867999 (US)
N/A
Please try again or contact the 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.
Read more
Read less
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 the 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 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 may 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
  • Read more
    Read less
    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.

    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 does not 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.

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

    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>', // received from Server-Side Authentication
          env:'int', // the environment you’re running on, if omitted prod is default
          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: 'int', // the environment you’re running on, if omitted prod is default
            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. Process the card.
    You can use the cardNumber returned from the previous step to be processed either by the createPayment() or authenticate3d() Web SDK methods.
    If you prefer to process the payment server to server, you can use the getToken() to receive the temporary token to be processed with the payment API method. The temporary token is passed within the paymentOption field that is returned from getToken().

    createPayment Method

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
    fc.createPayment({
                    "sessionToken"   : result.sessionToken, //received from openOrder API 
                    "merchantId"     : '1475082432483184221', //as assigned by SafeCharge
                    "merchantSiteId" : '184941', //as assigned by SafeCharge
                     "userTokenId"    : "230811147",
                     "clientUniqueId" : "695701003", // optional
                    "currency"       : "USD", 
                    "amount"         : "500",
                    "paymentOption" : cardNumber
                }, function (res) {
                    console.log(res)
                })
    

    getToken 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. to pass on to the /payment API method
        } 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
    23
    24
    25
    26
    27
    28
    
    <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.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.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.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. Process the card.
    You can use the cardNumber returned from the previous step to be processed either by the createPayment() or authenticate3d() Web SDK methods.
    If you prefer to process the payment server to server, you can use the getToken() to receive the temporary token to be processed with the payment API method. The temporary token is passed within the paymentOption field that is returned from getToken().

    createPayment Method

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
    fc.createPayment({
                    "sessionToken"   : result.sessionToken, //received from openOrder API 
                    "merchantId"     : '1475082432483184221', //as assigned by SafeCharge
                    "merchantSiteId" : '184941', //as assigned by SafeCharge
                     "userTokenId"    : "230811147",
                     "clientUniqueId" : "695701003", // optional
                    "currency"       : "USD", 
                    "amount"         : "500",
                    "paymentOption" : cardNumber
                }, function (res) {
                    console.log(res)
                })
    

    getToken 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. to pass on to the /payment API method
        } 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 sample:

     

    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.
    Read more
    Read less
    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

    PARAMETER DESCRIPTION
    result
    String(20)
    The cashier status of merchant request. Possible statuses:
    APPROVED
    DECLINED
    ERROR
    Read more
    Read less
    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.
    Read more
    Read less
    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 cancelled 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.
    Read more
    Read less
    threeDReasonId
    String
    Reason ID for a failed 3DS authorisation as received from the issuer.
    threeDReason
    String
    Reason description for a failed 3DS authorisation as received from the issuer.
    challengeCancelReasonId
    String
    Reason ID for a cancelled 3DS authorisation as received from the issuer.
    ChallengeCancelReason
    ^String
    isLiabilityOnIssuer
    String
    Indicates if there is 3D secure liability shift.
    isExemptionRequestInAuthentication
    String
    Indicates if an exemption was requested during authorisation.
    challengePreferenceReason
    String
    If a challenge is requested, this fields provides the reason for it.

    getApms()

    This function returns the APMs supported with all their metadata needed for displaying them to the user and preparing them for processing, such as their display name, logo, required input to collect from the end user, and so on. One important field it returns for each APM is the APM identifier with SafeCharge that you need to submit when requesting the payment (with the createPayment() method).

    The function can retrieve either the entire APM set supported by your account with SafeCharge, or alternatively, a customised set of APMs. For example, you can request to retrieve APMs that correspond to certain criteria such as by transaction currency or by the user country.

    Code Sample:

    Input Parameters

    PARAMETER DESCRIPTION
    currencyCode
    String(20)
    Optional
    If currencyCode is provided, the returned APM set consists only of APMs that support this currency. If not provided, the APM set includes all APMs regardless of their supported currencies.
    The three letter ISO currency code.
    countryCode
    String(2)
    Optional
    If a countryCode is provided, the returned APM set consists only of APMs supported in this country. If not provided, the APM set includes all APMs regardless of where they are supported.
    The two-letter ISO country code.
    languageCode
    String(5)
    Optional
    The language in which the transaction is to be completed.
    type
    String
    Optional
    This is relevant for gaming, forex or other industries that pay out to their customers, but not relevant for other industries. The type of the payment methods to be returned.
    Possible values:
    DEPOSIT
    WITHDRAWAL
    If no value is sent, then the default value is DEPOSIT.
    Read more
    Read less

    Output Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Merchant Site ID provided by SafeCharge.
    clientRequestId
    String(20)
    ID of the API request in the merchant system.
    internalRequestID
    String(20)
    SafeCharge Internal unique request ID (used for reconciliation purposes, etc.).
    paymentMethods[]
    Class
    An array of payment methods and their attributes:
    paymentMethod(String, 50)
    paymentMethodDisplayName {language(String, 2), message(String, 400)},
    isDirect (String, 5)
    countries (String, 2)
    currencies (String, 3)
    logoURL (String, 255)
    Fields:
    name (String, 45)
    regex (String, 128)
    type (String, 45)
    validationMessage {language(String, 2), message(String, 400)},caption {language(String, 2), message(String, 400)}
    Read more
    Read less
    type
    String
    The type of the payment methods to be returned.
    Possible values:
    DEPOSIT
    WITHDRAWAL. If no value is sent, then the default value is DEPOSIT.
    Read more
    Read less
    result
    String(20)
    The status of merchant’s API request/call.
    Possible statuses:
    APPROVED or ERROR.
    errCode
    String(11)
    If an error occurred on the request side, then an error code is returned in this parameter.
    errorDescription
    String(400)
    If an error occurred on the request side, then an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
    version
    Integer(10)
    The current version of your request.
    The current version is 1.

    Code Sample:


     

    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.
    Read more
    Read less
    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 Parameters table.)

    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(36)
    The transaction ID received from the MPI for 3D v2.
    result
    String(20)
    The cashier status of merchant request. Possible statuses:
    APPROVED
    DECLINED
    ERROR
    Read more
    Read less
    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.
    Read more
    Read less
    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 cancelled 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.
    Read more
    Read less
    threeDReasonId
    String
    Reason ID for a failed 3DS authorisation as received from the issuer.
    threeDReason
    String
    Reason description for a failed 3DS authorisation as received from the issuer.
    challengeCancelReasonId
    String
    Reason ID for a cancelled 3DS authorisation as received from the issuer.
    ChallengeCancelReason
    ^String
    isLiabilityOnIssuer
    String
    Indicates if there is 3D secure liability shift.
    isExemptionRequestInAuthentication
    String
    Indicates if an exemption was requested during authorisation.
    challengePreferenceReason
    String
    If a challenge is requested, this fields provides the reason for it.

    getToken()

    Use this method to get a temporary token (ccTempToken). This is a temporary one-time token.
    A temporary token is valid only for an API session, and is used only if you are processing with our server-to-server API and wish to be PCI descope.
    The return value from the function is ccTempToken, which can then be used in the server-to-server API /payment API call.

    Payment API

    /getSessionToken

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

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

    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

    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.
    Read more
    Read less
    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

    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

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

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

    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

    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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
    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
    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

    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

    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
    
    { 
       "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
       "merchantId":"2502136204546424962",
       "merchantSiteId":"126006",
       "userTokenId":"230811147",
       "clientRequestId":"1C6CT7V1L",
       "clientUniqueId":"695701003",
       "orderId":"34383481",
       "currency":"USD",
       "amount":"100",
       "paymentOption":{ 
          "card":{ 
             "cardNumber":"4017356934955740",
             "cardHolderName":"John Smith",
             "expirationMonth":"12",
             "expirationYear":"2022",
             "CVV":"217"
          }
       },
       "deviceDetails":{ 
          "ipAddress":"93.146.254.172"
       },
       "timeStamp":"20191105081132",
       "checksum":"5582d0189dd440f4bbf960569ec22e77"
    }
    

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

    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.
    More options for cards:
    externalToken (class) – For using external token provider such as ApplePay or Visa Checkout (instead of card details). Class details please find here
    ccTempToken – If you are using the Web SDK getToken(), you can send the returned ccTempToken as a substitute to the card number and CVV.
    -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)
    Optional
    This class contains the 3D Secure information required as an inputThe 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.
    Read more
    Read less
    subMethodDetails
    Class
    Optional
    subMethod(String) – details below
    email(String) – details below

    The submethod 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 submethod 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 the 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.
    The value is mandatory for rebilling\recurring transactions and represents the reference to the original transaction ID of the initial transaction.
  • 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.
    Read more
    Read less
    isRebilling
    Integer(2)
    Optional
    When performing recurring/rebilling, use this field to indicate the recurring step with the following vales:
    0 – For the initiating recurring event (first recurring transaction).
    1 – For all following recurring transactions.
    Notes:
  • Rebilling can be performed using userPaymentOptionId or card (under the paymentOption block). If done using card, then it is highly recommended to send its relatedTransactionId as well.
  • If isRebilling=1:
    - It can never be sent with the threeD block (under the paymentOption block)
    - For a 3DS transaction, you also must specify rebillExpiry and rebillFrequency under the v2AdditionalParams block, under the threeD block.
  • Read more
    Read less
    rebillingType
    String
    Optional
    When performing recurring/rebilling, use this field to indicate the recurring type with the following vales:
    RECURRING – Regular, recurring charging of the consumer
    MIT – Merchant Initiated Transaction. In case this is a one-time payment, initiated by the merchant.
    Read more
    Read less
    authenticationOnlyType
    String(2)
    Optional
    This is an advanced field, intended for merchants using the Zero Authorisation feature.
    Most merchants do not need to use this field, as this is managed by SafeCharge. Only merchants that are not using tokenization and/or are not using the user payment option management are required to set this field.
    The field marks the type of Zero Authorisation and the purpose it is being used for.
    Possible values:
    01 = for Recurring transactions
    02 = for Instalment transactions
    03 = When performing just an “Add card” action for future use
    04 = Maintain card information
    05 = Account verification only.
    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 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)
    isMoto
    String(1)
    Optional
    Set this field to “1” to mark the transaction as MOTO (mail order/telephone order).
    Leave null or “0” for regular transaction.
    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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

    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.
    Possible values:
    APPROVED - The transaction was authorised and approved.
    DECLINED – The transaction authorisation failed.
    ERROR – An error occurred. Please refer to Errors and Declines for details
    REDIRECT – The transaction was not completed. The end user needs to be redirected to a webpage to complete the transaction.
    There are two cases in which this response is returned:
  • 3D Secure – The user needs to be redirected to paymentOption.threeD.acsUrl. See 3D Secure Guide for full details.
  • Alternative payment method that requires redirection – The URL is on paymentOption.redirectURL.
  • Read more
    Read less
    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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

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

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

    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

    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.
    Read more
    Read less
    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 settled.
    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.
    Read more
    Read less
    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.
    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 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

    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.
    Read more
    Read less
    version
    Integer(10)
    The current version of the request. The current version is 1.

    /refundTransaction

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

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

    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

    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.
    Read more
    Read less
    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 settle transaction.
    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.
    Read more
    Read less

    Output Parameters

    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.
    Read more
    Read less
    version
    Integer(10)
    The current version of the request. The current version is 1.

    /voidTransaction

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

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

    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

    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.
    Read more
    Read less
    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.
    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.
    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.
    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 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.
    Read more
    Read less

    Output Parameters

    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.
    Read more
    Read less
    version
    Integer(10)
    The current version of the request. The current version is 1.

    /payout

    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
    40
    41
    42
    43
    44
    45
    46
    
    {
        "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": ""
        },
       "deviceDetails":{ 
          "deviceType":"DESKTOP",
          "deviceName":"deviceName",
          "deviceOS":"deviceOS",
          "browser":"browser",
          "ipAddress":"127.0.0.1"
       },
        "userPaymentOption":{
            "userPaymentOptionId":"1459503"
        },
        "comment": "some comment",
        "urlDetails": {
            "notificationUrl": ""
        },
        "timeStamp": "20150915143321",
        "checksum": "1cff28783432713e5dfc4fdc8f011b76"
    }
    

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

    The payout method allows performing a payout (transfer funds from merchant to consumer, with no connection to a previous transaction).

    Input Parameters

    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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.
    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
    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

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

    /getPaymentStatus

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/getPaymentStatus.do
    Example Request
    COPIED
    1
    2
    3
    
    {
      "sessionToken": "274ff0d9-c859-42f5-ae57-997641f93471"
    }
    

    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
    
    {
        "gwExtendedErrorCode": 0,
        "gwErrorCode": 0,
        "gwErrorReason": "",
        "authCode": "1234567",
        "transactionType": "Sale",
        "transactionStatus": "APPROVED",
        "userTokenId": "230811147",
        "transactionId": "1110000000004198292",
        "paymentOption": {
            "userPaymentOptionId": "14958143",
            "card": {
                "uniqueCC": "8/AOqY3oRC28rNNtUbtVPXjEtX0="
            }
        },
        "sessionToken": "274ff0d9-c859-42f5-ae57-997641f93471",
        "clientUniqueId": "256623868",
        "internalRequestId": 177988948,
        "status": "SUCCESS",
        "errCode": 0,
        "reason": "",
        "merchantSiteId": "180083",
        "version": "1.0",
        "clientRequestId": "d9819a40-5b8c-11ea-b626-b159cf3c9542"
    }
    

    This method retrieves the status of a payment recently performed. It receives the session ID and queries if a payment was performed. If a payment was performed, the method returns the status of this payment.

    Use this method when you need to retrieve the status of a payment to verify a payment response or to check if the response was not received or was not received correctly or completely.

    Use cases:

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    Required
    Session identifier returned by getSessionToken.

    Output Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    Session identifier returned by getSessionToken or generated by the openOrder.
    version
    String(10)
    The current version of the API method.
    Current version is 1.
    status
    String(20)
    The cashire status of merchant request.
    Possible statuses:
    SUCCESS
    ERROR
    Read more
    Read less
    transactionStatus
    String(20)
    The gateway transaction status.
    customData
    String(255)
    General data about the customer provided by the merchant. This parameter can be used to pass any type of information to the gateway, which is returned in response for the merchant records.
    This field is visible in cPanel reports with transaction information.
    Read more
    Read less
    clientUniqueId
    String(255)
    The ID of the transaction in merchant system.
    gwExtendedErrorCode
    Integer(11)
    Error code if 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
    gwErrorCode
    Integer(11)
    The error code if 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 error occurred at the gateway side.
    paymentMethodErrorCode
    Integer(11)
    The error code if error occurred at the APM side.
    paymentMethodErrorReason
    String(400)
    The error reason if error occurred at the APM side.
    authcode
    String(128)
    Auth code.
    merchantSiteId
    String(20)
    The Merchant Site ID provided by SafeCharge.
    transactionType
    String(45)
    The type of transaction: Sale or Auth.
    Note that, this require the merchant to be configured to gateway version 4.1.2 and up.
    Read more
    Read less
    userTokenId
    String(255)
    The ID of the user in merchant system.
    transactionId
    String(20)
    The gateway transaction ID.
    errCode
    Integer(11)
    The error code if error occurred at the cashier side.
    reason
    String(400)
    The error reason if error occurred at the cashier side.
    For example: failure in checksum validation, timeout from processing engine, etc.)
    Read more
    Read less
    clientRequestId
    String(20)
    The ID of the API request in merchant system.
    paymentOption.card
    Class
    uniqueCC, String(28) – Unique identifier for the credit card.
    paymentOption.alternativePaymentmethod
    Class
    externalAccountID, String – This is the consumer’s username or unique identifier provided by the APM. This value is not returned for all APMs.
    externalAccountDescription, String – Additional parameters that define the APM account in the following format:
    [parameter name]: [parameter value]
    [parameter name]: [parameter value]
    Not including the account password.
    externalTransactionId, String(20) – Bank transaction ID or APM transaction ID
    APMReferenceID, String – This is SafeCharge’s reference identifier for each APM.
    orderTransactionId, String – This value helps to identify individual transactions that are related to the same orderID.
    paymentMethod, String(256) – The type of payment method selected by the customer (pre-selected), each APM has a different name.
    userPaymentOptionId, String(45) – This is the ID of the newly-generated userPaymentOption when a new userPaymentOption is generated, or userPaymentOptionId that has been used for transaction processing and it has been sent into the request.
    Read more
    Read less

    /initPayment

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/initPayment.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
    
    {
                    "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"
    }
    

    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

    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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)
    If initPayment was processed with userPaymentOptionId rather than having provided the card block, this field echos back the same userPaymentOptionId that was provided in the input.
    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.
    ccTempToken, String(36) – A temporary card token to be used during the same session.
    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 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
    cardType
    Optional
    The type of card used in the transaction.
    Possible values:
    credit
    debit
    issuerCountry
    String(2)
    ISO code of the card issuer’s country.

    MPI Methods

    /authorize3d (API)

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

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

    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 with which the transaction is eventually processed, following the 3D authentication process.
    merchantId
    String
    Your merchant ID (MID) with the acquirer with which you are going to process the transaction.
    merchantName
    String
    Your merchant name as registered with the acquirer with which you are going to process the transaction.

    Input Parameters

    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.
    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
    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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

    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.
    Read more
    Read less
    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.
    Read more
    Read less
    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

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

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