Navbar
JSON Node.JS java php C#

Home

Introduction

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

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

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

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

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

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

Getting Started

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 customization of your payment page.

API and SDK

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

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

For the full Web SDK reference, please click here.

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

STEP 1: SET UP AN ORDER BY API CALL

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

Sample Request

Sample Response


STEP 2: REFERENCE THE WEB SDK LIBRARY

Import the safecharge.js JavaScript library.

STEP 3: GENERATE THE PAYMENT FORM

Create your payment form with the placeholder for SafeCharge Fields.

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

STEP 4: ACTIVATE SAFECHARGE FIELDS

Use our API to inject SafeCharge Card Fields:

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

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

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

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

STEP 5: SUBMIT PAYMENT WITH THE TOKEN

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

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

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

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

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

Sample Response

Checkout Page

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

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

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

STEP 1: AUTHENTICATION PREPARATION

To prevent errors that may occur while transferring HTTPS requests, and for SafeCharge to authenticate HTTPS requests, you must create and include an MD5 checksum into your request.

The checksum must be a single string without spaces with the values of the following parameters in the exact order as listed below:
- Secret Key
- Merchant ID
- Currency
- Total amount
- Item list (item_name_1, Item_amount_1, item_quantity_1 to item_name_N, Item_amount_N,item_quantity_N)
- Timestamp


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

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

STEP 2: SENDING THE REQUEST

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

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

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

Code Sample:

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

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

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

STEP 3: HANDLING RESPONSES

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

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

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

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

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

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


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



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

AJHFH9349JASFJHADJ9834115USD2007-11-13.13:22:343453459APPROVEDYourProduct

The calculated checksum would then be:
826fb8c4a2451e86f41df511c46f5a9b

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


API Guides

SDK

SERVER SDK (Java)

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

SERVER SDK (PHP)

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

CLIENT SDK

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

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

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



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

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

Alternative Payment Method

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

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

GET SESSION TOKEN

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

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

RENDER APM PAYMENT FORM

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

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

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

INITIATE APM SESSION

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

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



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

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


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

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

RESPONSE FOR THE APM VIA DMN

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

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

Supported Payment Methods

APM Unique SafeCharge Names

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


Sub Methods

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


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



PayPal Quick Registration
These PayPal features allow you to register your user based on their registration to their PayPal registration.
In order to invoke:



APM Account Identifiers

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



APM UNIQUE SAFECHARGE NAMES (Pay In)

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




APM UNIQUE SAFECHARGE NAMES (Pay Out)

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




APM ACCOUNT IDENTIFIERS (Pay In)

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




APM ACCOUNT IDENTIFIERS (Pay Out)

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




Returning Users

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

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

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

Rebilling

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

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

createPlan

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

Input Parameters

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



Output Parameters

Example Response

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


editPlan

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

Input Parameters

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



Output Parameters

Example Response

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



getPlansList

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

Input Parameters

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



Output Parameters

Example Response

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



createSubscription

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

Input Parameters

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



PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

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



editSubscription

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

Input Parameters

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



Output Parameters

Example Response

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



getSubscription

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

Input Parameters

Example Request
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

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

PARAMETER TYPE DESCRIPTION



cancelPlan

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

Input Parameters

Example Request
COPIED
1
2
3
{

}
PARAMETER TYPE MANDATORY DESCRIPTION



Output Parameters

Example Response

COPIED
1
2
3
{

}
PARAMETER TYPE DESCRIPTION



cancelSubscription

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

Input Parameters

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



Output Parameters

Example Response

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



HOW TO EXECUTE

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

Additionally, to perform payment actions for saved cards and returning customers, the following customer/card identifiers are required to be provided with relevant API calls:

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

PCI and Tokenization

DESCRIPTION

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

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

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

SAFECHARGE.JS

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

SAFECHARGE WEB SDK FIELDS

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

FEATURES

For step by step guide please refer to SafeCharge Fields.

3D Secure Overview

INTRODUCTION

What is 3D Secure 2.0?

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

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

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

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

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

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

Audience

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

Strong Customer Authentication

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

Frictionless vs Challenge Customer Authentication

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

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

Strong Customer Authentication Exemptions

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

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

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

Exclusions and Exemptions

Exemption for Low-Value Remote Payments

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

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

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

Exemption for Low-Value Contactless Payments

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

Transaction Risk Assessment (TRA) Exemptions

3D SECURE 1.0 FALLBACK

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

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

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

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

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

RECURRING TRANSACTIONS

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

LIABILITY SHIFT

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

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

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

3D Secure Guide

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

BEST PRACTICE INTEGRATION

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

SPECIAL 3D SECURE HANDLING

Avoid 3D Secure

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

Handle non-enrolled user

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

Recurring Transaction Parameters

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

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

The first call to payment must include the following parameters:

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

Any call to the payment transaction must include the field:

Partial Approval

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

OVERVIEW

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

This option is enabled by contacting customer support.

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

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

HOSTED PAYMENT PAGE SUPPORT

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

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

REVERSING A PARTIAL APPROVAL

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

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

DIRECT API SOLUTION

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

Apple Pay

CERTIFICATES

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

Apple Pay Certification

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


Creating a Payment Processing Certificate

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


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





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

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

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

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


DYNAMIC SERVER TO SERVER JS BUTTON SOLUTION

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

Minimum Requirements

iOS device:

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

Instructions

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

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

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


2. Create a button handler.

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

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

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


3. Create a result handler.

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

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


4. Passing information from frontend to backend.

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


5. Call processing method with required information.

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

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

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


6. Passing information from backend to frontend.

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

This is 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 Apple Pay button to the payment page page.
(Here’s how: https://developer.apple.com/reference/applepayjs/applepaysession) and include the following attributes in the tag:

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


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

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


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

HOSTED PAYMENT PAGE IFRAME SOLUTION USING IOS SDK

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

HOSTED PAYMENT PAGE IFRAME SOLUTION

This solution is relevant for a merchant which is integrated to SafeCharge hosted payment page while presenting it as an an IFrame in 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 web site.
2. The merchant must include SafeCharge IFrame directly on the merchant’s web site (not nested in other IFrame).
3. The SafeCharge JS script https://cdn.safecharge.com/safecharge_resources/v1/sc_applepay.min.js must be included before SafeCharge IFrame is initiated.


HTML example:

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

Notifications (using DMN)

HANDLING DMNs

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

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

INTEGRATING DMNs

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

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

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

For example, the SafeCharge server executes the following HTTPS GET/HTTPS POST request to the merchant’s server to send the response via the DMN channel:

http://myserver.com/SafeCharge/dmn/listen.to?ppp_status=OK&PPP_TransactionID=547&TransactionID=45402&userid=111&merchant_unique_id=234234unique_id&customData=342dssdee&productId=12345product_id&first_name=Diyan&last_name=Yordanov&email=dido%40domain.com&totalAmount=47.25&currency=USD&Status=APPROVED

SafeCharge sends DMNs from the following IP addresses:

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

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

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

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

RECEIVING DMNs

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

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

APMs AND DMNs

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

There are three possible values of the status parameter:
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 Decline) is received from the APM processor, SafeCharge sends the merchant an additional DMN call containing the same transaction data as the previous DMN call, with the exception of the status parameter that is now updated and contains the final status of the transaction.

AUTHENTICATING A DMN CHECKSUM

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

The HTTPS parameter containing the DMN checksum is named advanceResponseChecksum.

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

To Authenticate a DMN Response Checksum:

1. Concatenate the following parameters in the exact order as follows:

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

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

Example Of DMN Response Checksum:

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

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

After concatenation you have the following string:

AJHFH9349JASFJHADJ9834115USD2016-11-13.13:22:343453459APPROVEDYour Product

The calculated checksum is:

6501f10efbfc9599d3e79fc0e24a5662e60292b0025834d0e2d09c58945aedbb

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

DMN PARAMETERS

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

PARAMETER DESCRIPTION
ppp_status
Required
The status of the transaction. OK indicates that the transaction was approved. Pending occurs only for APM transactions when the final status is not immediately returned. FAIL indicates that the transaction was declined or there was an error.
PPP_TransactionID
Required
A unique 64-bit number that identifies the SafeCharge payment page transaction.
totalAmount
Required
Total amount of items contained in the consumer’s purchase sent to the payment page. For merchants with the currency conversion feature enabled, the value of this parameter is the original total amount of items before the currency is converted.
currency
Required
The currency, as selected by the consumer, that was sent. For merchants with currency conversion enabled, the value of this parameter is the original currency that was sent to the payment page.
convertedCurrency
Optional
The final currency, as selected by the consumer, in which the transaction was processed through the acquirer bank. This feature is only available for merchants with currency conversion enabled.
convertedAmount
Optional
The final amount of the transaction after the consumer converted the currency. This is the amount that was processed through the acquirer bank. This feature is only available for merchants with currency conversion enabled.
responsechecksum
Required
Deprecated checksum parameter.
advanceResponseChecksum
Required
Advanced response checksum that ensures that the DMN callback is authentic.
transactionID
Optional
A unique 64-bit number that identifies the fiscal transaction in the SafeCharge payment gateway. If no fiscal transaction actually occurred, then the ppp_status is FAIL and this parameter is left empty.
transactionType
Optional
The type of transaction; Sale, Auth, Settle, Credit or Void. This service is only available upon request.
Status
Optional
Status of the SafeCharge Payment Gateway fiscal transaction; Approved, Success, Declined, Error, Pending. If no fiscal transaction actually occurred, the ppp_status is FAIL and this parameter is left empty.
userPaymentOptionId
Optional
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
Optional
The transaction ID of the transaction in the event that 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. The possible values are Visa, Amex, MasterCard, Diners, Discover, JCB, LaserCard, Maestro, Solo, and Switch. This value is provided when the value of the payment_method parameter is cc_card or dc_card.
customFieldX
Optional
Fifteen custom fields that may be used by replacing X with 1 to 15. The customFieldX that was initially passed as the customFieldX parameter during the first request.
invoice_id
Optional
The invoice_id that that was initially passed as the invoice_id parameter during the first request.
address1
Optional
Street address of the user processing the transaction, if supplied.
address2
Optional
Street address of the user processing the transaction, if supplied.
country
Optional
The country of the user processing the transaction, if supplied.
state
Optional
State of the user processing the transaction, if supplied.
city
Optional
City of the user processing the transaction, if supplied.
zip
Optional
ZIP 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, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
expMonth
Optional
Expiration month of the card used to process the transaction, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
expYear
Optional
Expiration year of the card used to process the transaction, if supplied. The parameter is mandatory if the payment method is credit card or debit card. If another payment method is used, an empty string is returned.
Token
Optional
Tokens are strings of random digits, letters, and symbols characters that represent a single credit card number. When a merchant submits their consumers’ full credit card number, SafeCharge provides a token in the response representing the consumers’ credit cards.
tokenId
Optional
Deprecated ID of the token. Used in combination with the token.
orderTransactionId
Optional
This value helps to identify individual transactions that are related to the same orderID.
3dflow
Optional
This parameter indicates whether the transaction was processed through the 3D Secure flow or not.
0 – Not processed through 3D Secure.
1 – Processed through 3D Secure.
promoCode
Optional
This value is a promotional code to apply discounts to products or services. SafeCharge does not apply any discounts and only returns the value sent in the HTTPS request.
ExErrCode
Optional
Error indication. When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the specific error.
ErrCode
Optional
When a transaction is successful, this parameter is 0. When a transaction is not successful, the parameter is the code of the generic error.
errApmCode
Optional
The error code returned from an APM.
errApmDescription
Optional
The error description returned from an APM.
errScCode
Optional
The error code returned by SafeCharge for an APM transaction.
errScDescription
Optional
The error description returned by SafeCharge for an APM transaction.
AuthCode
Optional
Authorization 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, which uniquely defines a particular merchant customization.
requestVersion
Required
The version of the request.
message
Required
A message from SafeCharge about the transaction that has been completed.
merchantLocale
Optional
The language of the payment page. The possible values of this parameter are provided below:
English (US): en_US
English (UK): en_UK
German: de_DE
Chinese(PRC): zh_CN
Hebrew: iw_IL
French: fr_FR
Dutch(Standard): nl_NL
Greek: el_GR
Indonesia: in_ID
Italian: it_IT
Japanese: ja_JP
Korean: ko_KR
Lithuanian: lt_LT
Spanish: es_ES
English (Canada): en_CA
English (Australia): en_AU
Russian: ru_RU
Arabic: ar_AA
Norwegian: no_No
Portuguese: pt_BR
Swedish: sv_SE
Turkish: tr_TR
Slovenian: sl_SI
Danish: da_DK
Romanian: ro_RO
Bulgarian: bg_BG
Polish: pl_PL
Hungarian: hu_HU
Vietnamese: vi_VL
Read more
Read less
unknownParameters
Optional
When an unknown parameter is sent to SafeCharge, i.e. a misspelled parameter, SafeCharge returns this parameter whose value is the unknown parameter. This enables the merchant to identify and correct any erroneous parameters.
payment_method
Required
The payment method used for this transaction such as cc_card, dc_card, giro, etc. For a complete list, see the NAME IN SAFECHARGE column in the tables in APM Account Identifiers.
ID
Optional
Hebrew ID.
merchant_id
Required
The unique merchant ID supplied by SafeCharge.
responseTimeStamp
Required
The time set by SafeCharge (in GMT) that the response is received from the Gateway in the format YYYY-MM-DD.HH:MM:SS for example: 2019-01-10.15.38.40
buyButtonProductId
Optional
Contains the ID of the product when the ‘buy button payment’ was processed.
dynamicDescriptor
Required
Dynamic descriptor passed to the SafeCharge gateway for the current transaction.
Reason
Optional
The reason that the Gateway request was returned if the transaction fails. See Gateway specification. N/A is returned if it is not a regular transaction.
ReasonCode
Optional
The reason code that the Gateway request was returned if the transaction fails. See Gateway specification. N/A is returned if it is not a regular transaction.
item_name_X
Required
The item name that was passed as the item_name_X parameter when making the initial request to the Public Payment Page. N/A is displayed if it is not a regular transaction.
item_number_X
Optional
The item number that was passed as the item_number_X parameter when making the initial request. N/A is displayed if it is not a regular transaction.
item_amount_X
Required
The item amount that was passed as the item_amount_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_quantity_X
Optional
The item quantity that was passed as the item_quantity_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_discount_X
Optional
The item discount that was passed as the item_discount_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_handling_X
Optional
The item handling that was passed as the item_handling_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
item_shipping_X
Optional
The item shipping that was passed as the item_shipping_X parameter initially when making the initial request. N/A is displayed if it is not a regular transaction.
appliedPromotions
Optional
Indicates that the purchase was completed using a promotion or coupon. This parameter contacts all successfully applied promotion codes. If more than one promotion was used, the promotion names are separated by a # character.
client_ip
Required
The IP address from which the client made the purchase.
uniqueCC
Optional
A unique value assigned to the credit card number.
user_token_id
Optional
This is a unique identifier for each consumer generated by the merchant.
ExternalAccountID
Optional
This is the consumer’s username or unique identifier provided by the APM. This value is not returned for all APMs.
APMReferenceID
Optional
This is SafeCharge’s reference identifier for each APM.
webMasterId
Optional
The webMasterID passed in the request.
finalFraudDecision
Optional
This parameter indicates the final fraud analysis decision made by SafeCharge Risk Management. Possible values are Accept – The transaction is redirected for processing
Reject – The transaction is rejected due to a Fraud Filter.
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-digits ZIP code match, the street address does not.
Y – Both the 5-digits ZIP code and the street address match.
X – An exact match of both the 9-digits ZIP code and the street address.
Z – Only the 5-digits ZIP code match, the street code does not.
U – Issuer Unavailable
S – Not Supported
R – Retry
B – Not Authorized (declined)
N – Both street address and ZIP code do not match.
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/re-billing transaction. Possible values:
0 – This is a regular transaction.
1 – This is a recurring/re-billing transaction.
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.
cavv
Optional
The card holder authentication verification value. Relevant for external MPI.
xid
Optional
The transaction identification value. Relevant for external MPI.
eci
Optional
The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are:
ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated
ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program.
ECI = 7: Payment authentication was not performed.
Read more
Read less
type
Optional
The type of the notification. Possible values:
DEPOSIT
WITHDRAWAL
KYC
DOCUP
KYC and DOCUP are only relevant for merchants implementing SafeCharge’s KYC solutions.
Read more
Read less
clientRequestId
Optional
ID of the API request in merchant’s system. This value must be unique. Can be used to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
relatedTransactionId
Optional
The ID of the related transaction used in case it was required for processing.
merchant_unique_id
Optional
If transaction sent through SafeCharge payment page, this parameter is populated by the ID of the transaction in the merchant’s system.
clientUniqueId
Optional
If transaction sent through SafeCharge API, this parameter is populated by the ID of the transaction in the merchant’s system.
externalTokenProvider
Optional
External token provider is a type of entity in the payment industry with its own flow (for example: Visa Checkout, Apple Pay). This indicates which external token provider was used in current transaction.
isDecrypeService
Optional
External token provider is a type of entity in the payment industry with its own flow (for example: Visa Checkout). This indicates whether the payments gateway decrypted the external token data provided, which was required for processing.

Errors and Declines

STATUS AND ERROR INDICATIONS

The payment process consists of three stages:

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

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

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

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

API RESPONSE CODES

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



GATEWAY RESPONSE CODES

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

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



GATEWAY FILTER ERROR CODES

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

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

GATEWAY DECLINE REASONS

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

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

Testing

OVERVIEW

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

TEST CARD NUMBERS

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

Valid Test Cards

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



Invalid Test Cards

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

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

TEST APM CREDENTIALS

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

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

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

Web SDK

Web SDK Overview

The Web SDK offers you the easiest way to integrate to SafeCharge payment services while maintaining your own custom user experience and your own custom payment form.

The Web SDK is a JavaScript library you can incorporate into your payment form to invoke payment functionality and the SafeCharge payment services.

Using the Web SDK guarantees a full PCI descoping.

What you can do with the SDK?

Web SDK Initialization

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

Server-Side Authentication

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

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

Reference the Web SDK Library

Import the safecharge.js JavaScript library.

Initialise the Web SDK

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

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

Card Data

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

The card holder data is always be placed under the paymentOption class, which is the input field to receive the card holder data. This applies to the following methods:

SafeCharge Fields

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


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

Simple Card Integration

  1. Import the safecharge.js library.

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


2. Create a simple container for your form.

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


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

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

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

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

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

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


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

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


5. Instantiate SafeCharge Fields.

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


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


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

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


8. Send the card to be tokenized by SafeCharge using the initPayment method.

In return you get a result containing the paymentOption structure that contains the ccTempToken required for the server-side call to the dynamic3D API method.

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

        }
    });

Three-Part Card Fields Integration

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

  1. Import safecharge.js

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


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

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


3. Instantiate SafeCharge Web SDK.

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


4. Instantiate SafeCharge Fields.

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


5. Create custom styles and classes for SafeCharge Fields.

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

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

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

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


6. Create and attach fields to the DOM.

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

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

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


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

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

    }
});

Additional Features

ADDITIONAL METHODS

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

Example for selecting an element and invoking method:

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

SAFECHARGE FIELDS CUSTOM STYLING – STATES AND ATTRIBUTES

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

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

            },
            empty: {

            },
            valid: {

            },
            invalid: {
            },
   };

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

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

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

Validation Errors Handling

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

For errors, the following events are thrown:

Error samples:

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 of 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 Initialization section.

INPUT

Input Parameters

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

Or by a userPaymentOptionId field, received from a previous transaction with SafeCharge that represents and tokenizes the cardholder card information.
Read more
Read less

OUTPUT

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

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

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

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

Output Parameters

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
"status": "SUCCESS",
"transactionStatus": "APPROVED",
"errCode": 0,
"orderId": "241494183",
"authCode": "1234567",
"userTokenId": "someone@site.com",
"paymentOption": {
    "userPaymentOptionId": "8348263",
    "card": {
        "ccCardNumber": "5****8464",
        "bin": "511580",
        "last4Digits": "8464",
        "ccExpMonth": "01",
        "ccExpYear": "20",
        "cvv2Reply": "",
        "avsCode": ""
    }
},
"gwErrorCode": 0,
"gwErrorReason": "",
"gwExtendedErrorCode": 0,
"transactionType": "Auth3D",
"transactionId": "1110000000000347161",
"externalTransactionId": "",
"customData": "",
"sessionToken": "5bd76168-844c-4fb1-9cfb-f7812ca31950",
"clientUniqueId": "695701003",
"internalRequestId": 134148663,
"merchantId": "5288945245833474115",
"merchantSiteId": "51001",
"clientRequestId": "20190411173319",
"version": "1.0",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"

}
PARAMETER DESCRIPTION
sessionToken
String(36)
The session identifier returned by the getSessionToken parameter.
status
String(20)
The cashier status of merchant request. Possible statuses:
SUCCESS
ERROR
transactionStatus
String(20)
The gateway transaction status.
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.
timestamp
String(14)
The local time when the method call is performed in the format: YYYYMMDDHHmmss. It is required to validate the response checksum.
checksum
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:
- transactionId
- transactionType
- clientUniqueId (if provided)
- clientRequestId (if provided)
- transactionStatus
- errCode
- timestamp received with the response
- merchantSecretKey
Read more
Read less
paymentOption
Class
This class represents the card data retrieved form the processed transaction. In addition, the userPaymentOptionId field is retrieved. userPaymentOptionId – The unique value identifies the card that was processed and is used as a token in following up transactions.
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: 4***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 that processed the transaction.
- threeD (class) – Contains the required 3D secure information. Refer to the threeD (out) chapter for details
Read more
Read less
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.).
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 as well as 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
fraudDetails
Class
finalDecision (String)
recommendations (String)
system { systemId (String)
systemName (String)
decision (String)
rules [ ruleId (String)
ruleDescription (String)]}
The 'system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
The 'rule’ refers to the risk management system rules triggered by the transaction.
The 'decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction.
There are five possible values for the decision parameter:
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 the 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.

finalDecision refers to 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 lead 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

authenticate3d()

Use this method to perform a 3D-only authorization 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 benefit 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 previous Web SDK Initialization section.

INPUT

Input Parameters

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

OUTPUT

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

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

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

Output Parameters

PARAMETER DESCRIPTION
sessionToken
String(36)
The session identifier returned by the getSessionToken parameter.
status
String(20)
The cashier status of merchant request. Possible statuses:
SUCCESS
ERROR
transactionStatus
String(20)
The gateway transaction status.
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.
timestamp
String(14)
The local time when the method call is performed in the format: YYYYMMDDHHmmss. It is required validate the response checksum.
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:
- transactionId
- transactionType
- clientUniqueId (if provided)
- clientRequestId (if provided)
- transactionStatus
- errCode
- timestamp – Received with the response
- merchantSecretKey
Read more
Read less
paymentOption
Class
This class represents the card data retrieved form the processed transaction. In addition, the userPaymentOptionId field is retrieved. userPaymentOptionId – The unique value identifies the card that was processed and is used as a token in following up transactions.
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: 4***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 that processed the transaction.
- threeD (class) – Contains the required 3D secure information. Refer to the threeD (out) chapter for details
Read more
Read less
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.).
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 as well as 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
fraudDetails
Class
finalDecision (String)
recommendations (String)
system { systemId (String)
systemName (String)
decision (String)
rules [ ruleId (String)
ruleDescription (String)]}
The 'system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
The 'rule’ refers to the risk management system rules triggered by the transaction.
The 'decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction.
There are five possible values for the decision parameter:
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 the 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.

finalDecision refers to 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 lead 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

initPayment()

This method performs the payment initialisation and 3D Secure initialisation of a transaction. It performs the following functionalities:

Perform the 3D Secure data collection and fingerprinting.

paymentFrame()

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

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

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

getToken()

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

Payment API

/openOrder

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

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





Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/openOrder.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": " 487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "currency": "USD",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
    "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "",
        "deviceOS": "",
        "browser": "",
        "ipAddress": ""
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "sippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "addendums": {
        "localPayment": {
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        }
    },
    "timeStamp": "20170118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}
PARAMETER DESCRIPTION
merchantId
String(20)
Required
Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
Required
Merchant Site ID provided by SafeCharge.
userTokenId
String(255)
Optional
ID of the user in the merchant’s system.
clientUniqueId
String(45)
Required
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
clientRequestId
String(255)
Required
ID of the API request in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
currency
String(3)
Conditional
The three character ISO currency code.
This field is mandatory when using the Web SDK createPayment method.
amount
Double(12)
Conditional
The transaction amount.
This field is mandatory when using the Web SDK createPayment method.
amountDetails
Class
Optional
totalShipping,
totalHandling,
totalDiscount,
totalTax

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
Read more
Read less
items
Class
Optional
name (String, 255),
price (String, 10),
quantity (String, 10)

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

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
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 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” in case 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 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),
customField2 (String, 255),
customField3 (String, 255),
customField4(String, 255),
customField5(String, 255),
customField6(String, 255),
customField7(String, 255),
customField8 (String, 255),
customField9 (String, 255),
customField10 (String, 255),
customField11 (String, 255),
customField12 (String, 255),
customField13 (String, 255),
customField14 (String, 255),
customField15 (String, 255)

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

For example, localPayment addendum 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

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s integration team at integration@safecharge.com.
Read more
Read less
timeStamp
String(14)
Required
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String(256)
Required
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0"
}
PARAMETER DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in the merchant’s system.
clientUniqueId
String
ID of the transaction in the merchant’s system.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
merchantDetails
Class
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
Read more
Read less
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode
String
If an error occurred on the request side, an error code is returned in this parameter.
reason
String
If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
version
Integer
The current version of the request. The current version is 1.

/payment

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

MANDATORY FIELDS

SELECTING A PAYMENT METHOD (paymentOption CLASS)

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



Input Parameters

Example Request

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

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

Example Response

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

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

The following table describes the full list of input fields to be sent for any call using the /payment method.

The paymentOption class field of the request is described in the follow-up table.

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

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

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

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

These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s integration team.
Read more
Read less
dynamicDescriptor
Class
Optional
descriptorMerchantName (String, 25, not mandatory),
descriptorMerchantPhone (String, 13, not mandatory)
merchantDetails
Class
Optional
customField1 (String, 255, not mandatory),
customField2 (String, 255, not mandatory),
customField3 (String, 255, not mandatory),
customField4 (String, 255, not mandatory),
customField5 (String, 255, not mandatory),
customField6 (String, 255, not mandatory),
customField7 (String, 255, not mandatory),
customField8 (String, 255, not mandatory),
customField9 (String, 255, not mandatory),
customField10 (String, 255, not mandatory),
customField11 (String, 255, not mandatory),
customField12 (String, 255, not mandatory),
customField13 (String, 255, not mandatory),
customField14 (String, 255, not mandatory),
customField15 (String, 255, not mandatory)
Read more
Read less
urlDetails
Class
Optional
Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
successUrl (string, 1000)
failureUrl (string, 1000)
pendingUrl (string, 1000)
notificationUrl (string, 1000)
Read more
Read less
customSiteName
String(50)
Optional
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
Risk rules and traffic management rules are usually built based on this field value.
productId
String(50)
Optional
A free text field used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this field value.
customData
String(255)
Optional
This parameter can be used to pass any type of information.
If sent in request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String(255)
Optional
This is an affiliate parameter that the merchant can send.
This is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SafeCharge API SDKs to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SafeCharge API.
Read more
Read less

Output Parameters

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

Example Response

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

PARAMETER DESCRIPTION
sessionToken
String(36)
The session identifier returned by the getSessionToken parameter.
orderId
String(20)
The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
merchantId
String(20)
The Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
The Merchant Site ID provided by SafeCharge.
userTokenId
String(255)
The ID of the user in merchant system.
clientUniqueId
String(255)
The ID of the transaction in merchant system.
clientRequestId
String(20)
The ID of the API request in merchant system.
internalRequestId
Long(20)
SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
status
String(20)
The cashier status of merchant request.
Possible statuses: SUCCESS or ERROR
transactionStatus
String(20)
The gateway transaction status.
paymentOption
Class
This class 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 authorization code of the transaction.
partialApprovalDetails
Class
This determines whether or not the transaction is a partial approval and other information regarding the amount.
These following parameters are returned only if the partial approval feature was in use, as per the relevant input parameter sent value.

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

The ‘system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
The ‘rule’ refers to the risk management system rules triggered by the transaction.
The ‘decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction.
There are five possible values for the decision parameter:
Accept – The risk management system accepts the transactions.
Reject – The risk management system rejects the transaction. The transaction not passed to bank for authorization. The reasons are returned in ruleDescription parameter.
Review88 – 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.
None88 – No risk analysis was performed. The gateway continues to process the transaction through the bank.

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

/settleTransaction

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



Input Parameters

Definition

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

The value sent must contain digit characters only, meaning this string value can not contain any character that is not a digit.
authCode
String(128)
Required
The authorization code of the related auth transaction, to be compared to the original one.
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 addendum. The addendum fields that appear are based on the specific addendum type.

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

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

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

Output Parameters

Example Response

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

/refundTransaction

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



Input Parameters

Definition

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

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

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

Output Parameters

Example Response

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

/voidTransaction

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



Input Parameters

Definition

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

The value sent must contain digit characters only, meaning this string value can not contain any character that is not a digit.
authCode
String(128)
Required
The authorization 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 empty value, then it contains the concatenation of all item names up until parameter maximum length.
customData
String(255)
Optional
This parameter can be used to pass any type of information.
If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String(255)
Optional
This is an affiliate parameter that the merchant can send.
timeStamp
String(14)
Required
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String(256)
Required
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey.

Output Parameters

Example Response

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

/payout

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





Input Parameters

Definition

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

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

This allows the merchant to send information with the request to be saved in API level and returned in response. It is not passed to the payments gateway and is not be used for processing.
Read more
Read less
cardData
Class
Optional
cardNumber(String, 20),
cardHolderName(String, 70),
expirationMonth(String, 2),
expirationYear(String, 4),

An alternative to sending the paymentOptionId for card payouts. Merchant has to be PCI ceritifed to use this, as it uses clear text card numbers.
When sending cardData you must also send userTokenId
Read more
Read less
userPaymentOption
Class
Required
userPaymentOptionId(String, 45),

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

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

Output Parameters

Example Response

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

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

/getPaymentPageUrl

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



Input Parameters

Definition

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

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

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

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

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

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

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

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

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

Note that the country parameter is always mandatory.
Read more
Read less
dynamicDescriptor
Class
Optional
merchantName(String, 25),
merchantPhone(String, 13)

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

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

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

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

Each parameter is limited for up to 1000 characters.
Read more
Read less
skipReviewTab
String(5)
Optional
Indicating whether or not to skip the payment page review page. Possible values: true or false.
customeSiteName
String(50)
Optional
The merchant’s site name that should replace the default MerchantSite name.
This parameter is useful for merchants operating many websites that are distinguished only by name.
merchantLocale
String(5)
Optional
The default language. The current default value is English (for example: for English (US) the value is en_US).
encoding
String(20)
Optional
The type of character encoding. Default value is ISO-8859-1.
paymentMethod
String(256)
Optional
The type of payment method selected by the customer (pre-selected): credit card: cc_card
debit card: dc_card
APMs: SafeCharge’s unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see APM Unique SafeCharge Names.
Read more
Read less
paymentMethodMode
String
Optional
This parameter filters out any payment method that is not the payment method sent in paymentMethod parameter. Possible values: filter or no value at all.
userToken
String(8)
Optional
This parameter determines if the payment page requires existing customers to register for each transaction.
When user_token=register, the payment page requires the customer to register even if they have already registered in the system. The previously registered payment methods are deleted.

When user_token=auto, the payment page checks the SafeCharge database to determine if the customer has registered before.
When user_token=readonly, the customer can only select payment methods they have previously used.

When user_token=registeronly, the payment page requires the customer to register (by entering a new payment option) even if they are already registered in the system. No other previously saved payment options are deleted. The payment page does not show any previously saved payment options.

When user_token=readonlyupo, the customer is presented with a single payment option previously saved and specified on the payment page userPaymentOptionId parameter. If payment option parameters need to be completed, they are editable on the payment page (CVV, expired expiration date, etc.).
Read more
Read less
userPaymentOptionId
String
Optional
If input parameter userToken=readonlyupo and userPaymentOptionId parameter sent then the consumer is presented only with this userPaymentOption sent that he previously registered with.
themeId
String
Optional
This parameter is configured per merchant site but if sent as input it overrides the configuration and themeId chosen is presented.
invoiceId
String(100)
Optional
A unique invoice identifier provided by the merchant or randomly generated.
webMasterId
String(255)
Optional
This is an affiliate parameter that the merchant can send.
isNative
String(1)
Optional
This value determines whether or not the payment method is redirected to appear in a new window (0) or whether it is redirected within the existing window (1).
kyc
String(TBD)
Optional
This parameter determines the point in time in the customer’s life cycle at which the merchant would like to initiate automated KYC checks.
Possible values:
PreDeposit – KYC is checked before a user places a deposit; after successful verification, the user is automatically re-directed to the SafeCharge cashier deposit page
postDeposit – KYC is checked after a user places a successful deposit
preWithdrawal – KYC is checked upon a user placing a Withdrawal request
Note: In a case when a merchant wishes to perform a check in the customer’s registration process without a redirection to the deposit page afterwards, the eKYC.do API method should be used.
Read more
Read less
ekycFlow
String(TBD)
Optional
This parameter describes the business logic layer of the KYC checks, allowing a merchant to perform one of the following:
EKYC_ONLY – perform only this type
DOC_VER_ONLY – perform only this type
FULL – Always do both

CASCADING or empty value – Do both only in a case of a fallback (cascading direction is always from eKYC to document verification)
Read more
Read less
ekycType
String(TBD)
Optional
This parameter controls the sub-checks category of the eKYC required in the API call.
Bureau – Performs eKYC check that validates a name against an address and date of birth
PEP_Sanctions – Performs Pep & sanctions checks (politically exposed persons and sanctions lists lookup)
All – Performs both Bureau and Pep & sanctions checks
Read more
Read less
dateOfBirth
String
Optional
If value sent in kyc parameter, then it is mandatory to send the consumer date of birth as it is required for KYC processing.
building
String
Optional
If value sent in kyc parameter, then it is mandatory to send the consumer building as it is required for KYC processing.
building should be populated with house number or building name.
quick_deposit
String(1)
Optional
This parameter is only relevant for merchants that have been configured by SafeCharge to preform quick deposits.
For more information, please contact SafeCharge’s integration team at integration@safecharge.com
timeStamp
String(14)
Required
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String(256)
Required
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

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

/initPayment(API)

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

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



REQUEST PARAMETERS

Example Request

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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"
}

And the response is:

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    "reason": "",
    "orderId": "33704071",
    "transactionStatus": "APPROVED",
    "clientRequestId": "TH2FFCD9T",
    "customData": "Custom Data Inserted By Darin!",
    "internalRequestId": 10036001,
    "version": "1.0",
    "transactionId": "2110000000000587378",
    "merchantSiteId": "126006",
    "transactionType": "InitAuth3D",
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode": 0,
    "paymentOption": {
        "card": {
            "ccCardNumber": "5****5761",
            "bin": "511142",
            "threeD": {
                "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
                "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
                "v2supported": "true",
                "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
                "version": "2.1.0"
            },
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "last4Digits": "5761"
        }
    },
    "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
    "userTokenId": "230811147",
    "status": "SUCCESS"
}
Parameter 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 (per configuration)
The device’s details.
deviceType (string, 10)
deviceName (string, 255)
deviceOS (string, 255)
browser (string, 255)
ipAddres (string, 15)
Support device types: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
Read more
Read less
paymentOption
Class
Required
Containing 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)
Read more
Read less
customData
String(255)
Optional
General data about the customer is provided by the merchant.This parameter can be used to pass any type of information to the gateway, which is returned in a response for the merchant records. This field is visible in Control Panel reports with transaction information.
webMasterId
String(255)
Optional
This is an affiliate parameter that the merchant can send and is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SC REST API SDK’s to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SC REST API.
Read more
Read less
timeStamp
String(14)
Required
The local time when the method call is performed in the format: YYYYMMDDHHmmss.
checksum
Hexi-decimal
String(256)
Required
Hash (used hash algorithm, MD5 or SHA256, depends on merchantSite setting) of the values of the request parameters UTF-8 encoded, and concatenated in this order:
merchantId
merchantSiteId
clientRequestId
amount
currency
timestamp
merchantSecretKey
Read more
Read less

RESPONSE PARAMETERS

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

MPI Methods

/authorize3d (API)

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

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

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



Input Parameters

Example Request

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
{
   "merchantSiteId":"51001",
   "merchantId":"5288945245833474115",
   "sessionToken 9e07802d-5126-4b02-b4b3-ef09dfb94219",
   "clientRequestId":"20190605094208",
   "clientUniqueId":"uniqueIdCC",
   "currency":"EUR",
   "amount":"10",
   "paymentOption":{
      "card":{
         "cardNumber":"5115806139808464",
         "cardHolderName":"test name",
         "expirationMonth":"01",
         "expirationYear":"2020",
         "CVV":"122",
         "threeD":{
            "acquirer":{
               "bin":"411111",
               "merchantId":"123456789",
               "merchantName":"Merchant Inc."
            },
            "browserDetails":{
               "acceptHeader":"text/html,application/xhtml+xml",
               "ip":"192.168.1.11",
               "javaEnabled":"TRUE",
               "javaScriptEnabled":"TRUE",
               "language":"EN",
               "colorDepth":"48",
               "screenHeight":"400",
               "screenWidth":"600",
               "timeZone":"0",
               "userAgent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47"
            },
            "version":"2",
            "challengePreference":"1",
            "notificationUrl":"https://www.merchant.com/notificationURL/",
            "merchantUrl":"https://www.merchant-website.com",
            "platformType":"02",
            "deliveryEmail":"deliveryEmail@somedomain.com",
            "deliveryTimeFrame":"1",
            "giftCardAmount":"456",
            "giftCardCount":"10",
            "giftCardCurrency":"826",
            "preOrderDate":"20190219",
            "preOrderPurchaseInd":"2",
            "reorderItemsInd":"2",
            "shipIndicator":"1",
            "rebillExpiry":"",
            "rebillFrequency":"",
            "ChallengeWindowSize":"2"
         }
      }
   },
   "deviceDetails":{
      "deviceType":"DESKTOP",
      "deviceName":"deviceName",
      "deviceOS":"deviceOS",
      "browser":"browser",
      "ipAddress":"127.0.0.1"
   },
   "shippingAddress":{
      "address":"address",
      "city":"city",
      "country":"DE",
      "state":"",
      "zip":"1340"
   },
   "billingAddress":{
      "address":"address",
      "city":"city",
      "country":"DE",
      "state":"",
      "zip":"1335"
   },
   "merchantDetails":{
      "customField1":"customField1",
      "customField2":"customField2",
      "customField3":"customField3",
      "customField4":"customField4",
      "customField5":"customField5"
   }
}

The following table describes the full list of input fields to be sent for any call using the /payment method.

The paymentOption class field of the request is described in the follow-up table.

PARAMETER DESCRIPTION
merchantId
String(20)
Required
The merchant ID provided by SafeCharge.
merchantSiteId
String(20)
Required
The merchant Site ID provided by SafeCharge.
sessionToken
String(36)
Required
Session identifier returned by the 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) chapter for details.
-or-
alternativePaymentMethod class – Contains the relevant field required for the specific payment method. Please refer to alternativePaymentMethod Class for details.
-or-
userPaymentOptionId – this is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. SafeCharge keeps payment option details from a previous uses.
Read more
Read less
relatedTransactionId
String(19)
Required
Set here the transactionId returned from the preceding initPayment call.
orderId
String(45)
Optional
The order ID provided by SafeCharge.
This parameter is passed to define which merchant order to update.
userTokenId
String(255)
Optional
The ID of the user in the merchant’s system. Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details.
clientUniqueId
String(45)
Optional
The ID of the transaction in the merchant’s system. This value must be unique, and though not mandatory it is recommended that it is sent.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
This parameter appears in the DMN as merchant_unique_id.
Read more
Read less
clientRequestId
String(255)
Optional
The ID of the API request in the merchant’s system. This value must be unique, and though not mandatory it is recommended that it is sent.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
deviceDetails
Class
Only ipAddress
deviceType (String, 10),
deviceName (String, 255),
deviceOS (String, 255),
browser (String, 255), ipAddress (String, 15)

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

These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s integration team.
Read more
Read less
merchantDetails
Class
Optional
customField1 (String, 255, not mandatory),
customField2 (String, 255, not mandatory),
customField3 (String, 255, not mandatory),
customField4 (String, 255, not mandatory),
customField5 (String, 255, not mandatory),
customField6 (String, 255, not mandatory),
customField7 (String, 255, not mandatory),
customField8 (String, 255, not mandatory),
customField9 (String, 255, not mandatory),
customField10 (String, 255, not mandatory),
customField11 (String, 255, not mandatory),
customField12 (String, 255, not mandatory),
customField13 (String, 255, not mandatory),
customField14 (String, 255, not mandatory),
customField15 (String, 255, not mandatory)
Read more
Read less
urlDetails
Class
Optional
Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
pendingUrl (string, 1000)
customSiteName
String(50)
Optional
The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
Risk rules and traffic management rules are usually built based on this field value.
productId
String(50)
Optional
A free text field used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this field value.
customData
String(255)
Optional
This parameter can be used to pass any type of information.
If sent in request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
webMasterId
String(255)
Optional
This is an affiliate parameter that the merchant can send.
This is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SafeCharge API SDKs to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SafeCharge API.
Read more
Read less

Output Parameters

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

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
   "orderId":"241494183",
   "paymentOption":{
      "userPaymentOptionId":"8348263",
      "card":{
         "ccCardNumber":"5****8464",
         "bin":"511580",
         "last4Digits":"8464",
         "ccExpMonth":"01",
         "ccExpYear":"20",
         "cvv2Reply":"",
         "avsCode":"",
         "threeD":{
            "acsUrl":"https://qa1-tlv-acq1:4434/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmlj...",
            "eci":"7",
            "termUrl":"https://srv-bsf-devppptrunk.gw-4u.com/ppp/api/threeDSecure/completePayment.do?sessionToken\u003d04fcc8cf-3789-4936-b690-9801261f83a9",
            "whiteListStatus":"",
            "cavv":"",
            "acsChallengeMandated":"Y",
            "cReq":"eyJ0aHJlZURTU...",
            "authenticationType":"01",
            "cardHolderInfoText":"",
            "xid":"",
            "result":"C",
            "version":"2.1.0",
            "acsTransID":"541a88a9-f01f-4206-9137-ec1bed295955",
            "dsTransID":"f0ff3e24-cdf6-4561-900b-849a5054d776"
         }
      }
   },
   "transactionStatus":"DECLINED",
   "merchantDetails":{
      "customField1":"merchantName",
      "customField2":"merchantName",
      "customField3":"merchantName",
      "customField4":"merchantName",
      "customField5":"merchantName",
      "customField6":"merchantName",
      "customField7":"merchantName",
      "customField8":"merchantName",
      "customField9":"merchantName",
      "customField10":"merchantName",
      "customField11":"merchantName",
      "customField12":"merchantName",
      "customField13":"merchantName",
      "customField14":"merchantName",
      "customField15":"merchantName"
   },
   "gwErrorCode":-1,
   "gwErrorReason":"Decline",
   "gwExtendedErrorCode":0,
   "transactionType":"Auth3D",
   "transactionId":"1110000000000347161",
   "externalTransactionId":"",
   "authCode":"",
   "customData":"",
   "sessionToken":"5bd76168-844c-4fb1-9cfb-f7812ca31950",
   "clientUniqueId":"uniqueIdCC",
   "internalRequestId":134148663,
   "status":"SUCCESS",
   "errCode":0,
   "reason":"",
   "merchantId":"5288945245833474115",
   "merchantSiteId":"51001",
   "version":"1.0",
   "clientRequestId":"20190411173319"
}
PARAMETER DESCRIPTION
sessionToken
String(36)
The session identifier returned by the getSessionToken parameter.
orderId
String(20)
The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
merchantId
String(20)
The Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
The Merchant Site ID provided by SafeCharge.
userTokenId
String(255)
The ID of the user in merchant system.
clientUniqueId
String(255)
The ID of the transaction in merchant system.
clientRequestId
String(20)
The ID of the API request in merchant system.
internalRequestId
Long(20)
SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
status
String(20)
The cashier status of merchant request.
Possible statuses: SUCCESS or ERROR
transactionStatus
String(20)
The gateway transaction status.
paymentOption
Class
This class 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) chapter 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 authorization code of the transaction.
partialApprovalDetails
Class
This determines whether or not the transaction is a partial approval and other information regarding the amount.
These following parameters are returned only if the partial approval feature was in use, as per the relevant input parameter sent value.

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

The ‘system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
The ‘rule’ refers to the risk management system rules triggered by the transaction.
The ‘decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction.
There are five possible values for the decision parameter:
Accept – The risk management system accepts the transactions.
Reject – The risk management system rejects the transaction. The transaction not passed to bank for authorization. The reasons are returned in ruleDescription parameter.
Review88 – 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.
None88 – No risk analysis was performed. The gateway continues to process the transaction through the bank.

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

/verify3d

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

This method retrieves the generic 3D Secure result (ECI and CAVV) that you need to send to your PSP or acquirer to benefit from the 3D Secure liability shift received from the SafeCharge 3D Secure service.



Input Parameters

Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "merchantSiteId":"51001",
   "merchantId":"5288945245833474115",
   "sessionToken":" 9e07802d-5126-4b02-b4b3-ef09dfb94219",
   "relatedTransactionId":"2110000000000644998",
   "currency":"USD",
   "amount":"0.1",
   "paymentOption":{
      "card":{
         "cardNumber":"5413330056003511",
         "cardHolderName":"john Smith",
         "expirationMonth":"12",
         "expirationYear":"25",
         "CVV":"123"
      }
   },
   "billingAddress":{
      "country":"DE",
   },
}
PARAMETER DESCRIPTION
merchantId
String(20)
Required
The merchant ID provided by SafeCharge.
merchantSiteId
String(20)
Required
The merchant Site ID provided by SafeCharge.
sessionToken
String(36)
Required
Session identifier returned by the getSessionToken.
currency
String(3)
Required
The three-character ISO currency code.
amount
Double(12)
Required
The transaction amount.
This amount must be identical to the amount listed in the dynamic3D.
paymentOption
Class
Required
This class represents the details about the payment method.
Can have either card, alternativePaymentMethod, or userPaymentOptionId:
card class has the following fields:
cardNumber string(20) – The card number
cardHolderName, string(70) – The card holder name
expirationMonth, string(2) – Card expiration month
expirationYear– string(4)– Card expiration year
CVV, string(4) – The CVV/CVC security code
threeD (class) – Contains the required 3D secure information. Refer to the threeD (in) chapter for details.
-or-
alternativePaymentMethod class – Contains the relevant field required for the specific payment method. Please refer to alternativePaymentMethod Class for details.
-or-
userPaymentOptionId – this is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. SafeCharge keeps payment option details from a previous uses.
Read more
Read less
relatedTransactionId
String(19)
Required
The transaction ID of the of the call to /authorize3d.
billingAddress
Class
Only country
The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters.
firstName (String, 30),
lastName (String, 40),
address (String, 60),
address2 (String, 60),
phone (String, 18),
zip (String, 10),
city (String, 30),
country (two-letter ISO country code)(String, 2), must be entered in Uppercase
state (two-letter ISO state code)(String, 2),
email (String, 100),
county (String, 255)

These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s integration team.
Read more
Read less

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    "orderId": "29264489",
    "transactionStatus": "APPROVED",
    "transactionType": "VerifyAuth3D",
    "transactionId": "2110000000000644999",
    "customData": "customData",
    "merchantDetails": {
        "customField1": "merchantName",
        "customField2": "merchantName",
        "customField3": "merchantName",
        "customField4": "merchantName",
        "customField9": "merchantName"
    },
    "paymentOption": {
        "card": {
            "ccCardNumber": "5****3511",
            "bin": "541333",
            "last4Digits": "3511",
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "threeD": {
                "threeDFlow": "0",
                "eci": "2",
                "version": "2.1.0",
                "serverTransId": "34cfeb35-5ba6-4df3-a5f1-bf4b93e14476",
                "whiteListStatus": "",
                "cavv": "ZkhQRHd3Mzd6Z2t2MlFLQmRMbW8=",
                "sdk": {},
                "xid": "",
                "result": "Y",
                "acsTransID": "",
                "dsTransID": "9bd98ea9-035e-4ec3-a863-831fc547473f"
            }
        }
    },
    "sessionToken": "9e07802d-5126-4b02-b4b3-ef09dfb94219",
    "clientUniqueId": "clientUniqueId",
    "internalRequestId": 3329188,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "9216377689920778293",
    "merchantSiteId": "6",
    "version": "1.0",
    "clientRequestId": "20190702145241"
}
PARAMETER DESCRIPTION
sessionToken
String(36)
The session identifier returned by the getSessionToken parameter.
orderId
String(20)
The ID returned from the merchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
merchantId
String(20)
The Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
The Merchant Site ID provided by SafeCharge.
userTokenId
String(255)
The ID of the user in merchant system.
clientUniqueId
String(255)
The ID of the transaction in merchant system.
clientRequestId
String(20)
The ID of the API request in merchant system.
internalRequestId
Long(20)
SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
status
String(20)
The cashier status of merchant request.
Possible statuses: SUCCESS or ERROR
transactionStatus
String(20)
The gateway transaction status.
paymentOption
Class
This class represents the details about the payment method. This can be one of two options:
card – Representing credit/debit card.
-or-
alternativePaymentMethod – Representing an alternative payment method.

In addition, if a user option ID was either created or an existing one was used in the transaction, it returns the ID to this payment option:
userPaymentOptionId – This is a field identifying a payment option that already has been used by the customer and is now requested for re-use. SafeCharge keeps the payment option details from previous uses.
Read more
Read less
merchantDetails
Class
customField1 (String, 255, not mandatory),
customField2 (String, 255, not mandatory),
customField3 (String, 255, not mandatory),
customField4 (String, 255, not mandatory),
customField5 (String, 255, not mandatory),
customField6 (String, 255, not mandatory),
customField7 (String, 255, not mandatory),
customField8 (String, 255, not mandatory),
customField9 (String, 255, not mandatory),
customField10 (String, 255, not mandatory),
customField11 (String, 255, not mandatory),
customField12 (String, 255, not mandatory),
customField13 (String, 255, not mandatory),
customField14 (String, 255, not mandatory),
customField15 (String, 255, not mandatory)

This allows the merchant to send information with the request to be saved in the API level and returned in response. It is not passed to the payment gateway and is not used for processing.
Read more
Read less
errCode
String(11)
If an error occurred on the request side, an error code is returned in this parameter.
reason
String(400)
If an error occurred on the request side, an error reason is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
gwErrorCode
Integer(11)
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String(400)
If an error occurred in the gateway, then an error reason is returned in this parameter, for example failure in checksum validation, timeout from processing engine, etc.
gwExtendedErrorCode
Integer(11)
The error code if an error occurred on the bank’s side.
When a transaction is successful, this field is 0.
When a transaction is not successful, the parameter is the code of the generic error.
version
Integer(10)
The version of the request.
The current version is 1.
externalTransactionId
String(20)
The transaction ID of the transaction in the event that an external service is used.
transactionId
String(20)
The gateway transaction ID.
authCode
String(128)
The authorization code of the transaction.
transactionType
String(45)
The type of transaction; Sale or Auth.
Note: This requires the merchant to be configured to gateway version 4.1.2 or higher. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com
customData
String(255)
This parameter can be used to pass any type of information.
If sent in the request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
fraudDetails
Class
finalDecision (String),
recommendations (String),
system {systemId(String),
systemName (String),
decision (String),
rules [ruleId(String),
ruleDescription (String)]}

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

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

Class Objects

threeD Input Class

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

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

Parameter Description
notificationURL
String
Required
The notification URL for redirecting the browser after the challenge completion, which receives the CRes message.
merchantURL
String
Required
The merchant website fully qualified URL.
version
String
Required
The 3DS version used.
1 or empty – 3DS 1.0
2 – 3DS 2.0
methodCompletionInd
String
Required
Indicates whether the 3DS Method was successfully completed.
Y – Successfully completed
N – Did not successfully complete
U – Unavailable – 3DS Method URL was not present
platformType
String
Required
The device channel.
01 – App-based (only for SDK implementation, not in the scope of this document)
02 – Browser
paResponse
String
Conditional
The payment authorization response returned by the card issuer/bank. Relevant only to the second payment call and only if 3D 1.0 authentication was performed.
isExternalMpi
String(1)
Optional
Possible values:
1 – External MPI is used (in this case, need to send eci, cavv , and xid values obtained from the external MPI).
0 – external MPI is not used.
eci
String(2)
External MPI
The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant.
cavv
String(50)
External MPI
The card holder authentication verification value, received from the 3D Secure provider.
xid
String(50)
Optional
The transaction identification value of a 3D Secure 1.0 authorisation transaction.
browserDetails
Class
3D 2.0
acceptHeader (string, not mandatory)
ip (string, not mandatory)
javaEnabled (string, not mandatory)
javaScriptEnabled (string, not mandatory)
language (string, not mandatory)
colorDepth (string, not mandatory)
screenHeight (string, not mandatory)
screenWidth (string, not mandatory)
timeZone (string, not mandatory)
userAgent (string, not mandatory)
Read more
Read less
v2AdditionalParams
Class
3D 2.0
For the list of parameters in this class for the new version of 3D Secure, please see the table below.
sdk
Class
3D 2.0 SDK
This class is mandatory for 3D 2.0 for transactions originating from a mobile device. It contains the following 3D mobile relevant information:
appSdkInterface – String(2) – Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.
appSdkUIType – String(2) – Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.
appID – String(36) – SDK App ID - guid
encData – String(64000) – SDK Encrypted Data
ephemPubKey – String(256) – SDK Ephemeral Public Key (Qc)
maxTimeout –String(2) – SDK Maximum Timeout
referenceNumber – String(32) – SDK Reference Number
transID – String(36) – SDK Transaction ID – guid
Read more
Read less

v2AdditionalParams

Parameter Description
challengePreference
String
Optional
The 3DS challenge requestor indication.
01 – No preference
02 – No challenge requested
03 – Challenge requested: 3DS Requestor Preference
04 – Challenge requested: Mandate
Read more
Read less
deliveryEmail
String
Optional
For electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeFrame
String
Optional
Indicates the merchandise delivery timeframe.
01 – Electronic Delivery
02 – Same day shipping
03 – Overnight shipping
04 – Two-day or more shipping
Read more
Read less
giftCardAmount
String
Optional
For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).
giftCardCount
String
Optional
For prepaid or gift card purchase, the total count of individual prepaid or gift cards/codes purchased.
giftCardCurrency
String
Optional
For prepaid or gift card purchase, the ISO 4217 three-digit currency code of the gift card.
preOrderDate
String
Optional
For a pre-ordered purchase, the expected date that the merchandise is available (YYYYMMDD).
preOrderPurchaseInd
String
Optional
Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
01 – Merchandise available
02 – Future availability
PreOrderItemsInd
String
Optional
Indicates whether the cardholder is reordering previously purchased merchandise.
01 – First time ordered
02 – Reordered
shipIndicator
String
Optional
Indicates the selected shipping method for the transaction.
01 – Ship to cardholder’s billing address
02 – Ship to another verified address on file with merchant
03 – Ship to address that is different than the cardholder’s billing address
04 – “Ship to Store”/Pickup at local store (Store address shall be populated in shipping address fields)
05 – Digital goods (includes online services, electronic gift cards and redemption codes)
06 – Travel and Event tickets, not shipped
07 – Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)
Read more
Read less
rebillExpiry
String
Optional
Recurring Expiry - required if sg_rebill = 1 (format: YYYYMMDD)
rebillFrequency
String
Optional
Recurring Expiry - required if sg_rebill = 1 in number of days.
challengeWindowSize
String
Optional
The dimensions of the challenge window.
01 – 250 x 4000
2 – 390 x 4000
3 – 500 x 6000
4 – 600 x 4000
5 – Full screen
Read more
Read less

threeD Output Class

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

The output table is separate into 2 parts:

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

PARAMETER DESCRIPTION
acsUrl
String
URL/endpoint used to redirect the consumer to the card issuer/bank’s 3D secure verification page.
acsChallengeMandate
String(1)
The 3D Secure 2.0 challenge required indication. Possible values:N (not required), Y (required) Only in case of 3D 2.0
cReq
String
The Base64 encoded cReq relevant for the 3D Secure 2.0. acsUrl is sent as well as a separate field. Only in case of 3D 2.0
paRequest
String
The 3D secure request data for the card issuer/bank. Only in case of 3D 1.0
threeDFlow
String
Indicates which 3D flow is taking place:If the gateway response parameter for threeDFlow = 1 the transaction is converted from Sale3D to Auth3D after passing the gateway rule engine. (paRequest and acsUrl are returned and the merchant needs to redirect to issuer and call payment3D method afterwards). If the gateway response parameter for threeDFlow= 0, the transaction converted from Sale3D to Sale or Auth depending on the configured merchant mode of operation after passing the gateway rule engine. (paRequest and acsUrl are NOT be returned and the merchant does NOT need to redirect to issuer and call payment3Dmethod later on).
Read more
Read less
externalTransactionId
String(20)
The transaction ID of the transaction in the event that an external service is used.
transactionId
String(20)
The gateway transaction ID.

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

PARAMETER DESCRIPTION
cavv
String(28)
A cryptogram created by the issuer that serves as a proof that the merchant is entitled to this authentication.
eci
String
This is returned from banks and indicates the 3D Secure result.
Possible ECI data values are:
ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated
ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program
ECI = 7: Payment authentication was not performed
Note: In this method eci is returned in response only in case its value is 1 or 6 or 7.
Read more
Read less
threeDReason
String
If the attempt failed, this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
Returned in the end of the 3D Secure after successful frictionless.
authenticationType
String(2)
The type of authentication performed during the 3D Secure 2.0 challenge.
If the merchant wants to react differently for each authentication type, it is possible per the value returned.
Possible values:
01 (Static)
02 (Dynamic)
03 (OOB)
04 (Decoupled)
05–79 (reserved for EMVCo future use, values invalid until defined by EMVCo)
80–99 (reserved for DS use)
Returned on a second call to /payment or /verify3d. following a challenge.
Read more
Read less
cardHolderInfoText
String(128)
The text provided by the ACS/Issuer to the cardholder during a frictionless transaction that was not authenticated by the ACS. The issuer can opt to provide information to cardholder. For example: “Additional authentication is needed for this transaction, please contact [Issuer Name] at xxx-xxx-xxxx.”
Returned on a second call to /payment or /verify3d following a challenge
Read more
Read less

alternativePaymentMethod Class

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

Deprecated Methods

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

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

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



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

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

/dynamic3D

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



Input Parameters

Definition

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

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

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

The items’ and amountDetails prices should be sumif device type cannot be recognized)med up in the amount parameter and sent separately.
All prices must be in the same currency.
Read more
Read less
items
Class
Required
name(String, 255),
price(String, 10),
quantity(String, 10)

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

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (.

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

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

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

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

Note that the country parameter is always mandatory.

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

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

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

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

CVV can be mandatory or non-mandatory per configuration.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Note that in case isExternalMpi=1 sent, then must also send isDynamic3D=1 and dynamic3DMode=OFF.
Read more
Read less
storedCredentials
Class
Optional
storedCredentialsMode

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

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

Output Parameters

Example Response

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

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

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

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

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

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

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

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



Possible Scenarios Table

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

Possible Scenarios for Dynamic 3D (isDynamic3D = 1)

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



/payment3D

This final stage performs the actual payment transaction.



Input Parameters

Definition

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

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

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

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

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

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

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

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

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

Note that the country parameter is always mandatory.

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

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

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

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

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

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

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

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

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

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

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

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

CVV can be mandatory or non-mandatory per configuration.

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

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

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

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

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

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

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "",
    "gwErrorCode": "0",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "eci": "",
    "threeDReason": "",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"