Navbar
JSON Node.JS java php C#

Home

Introduction

Welcome to the SafeCharge API developers portal.

If this is your first time visiting our dev portal, we recommend you also visit our documentation site.

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

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

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

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


 

API Guides

Direct Merchant Notifications (DMNs)

After the merchant sends a transaction to SafeCharge, SafeCharge communicates with the customer’s bank to transfer the deposit from the customer’s account to the merchant’s account. When SafeCharge receives a response from the bank, SafeCharge notifies the merchant of the result of the deposit via a Direct Merchant Notification (DMN), also known as a webhook.

For more details, please refer to our DMNs Guide.

DMN Parameters

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

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

Currency Codes

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

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

Web SDK Overview

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

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

For a full explanation of the Web SDK, its advantages and a complete guide, please refer to the Web SDK chapter in our main documentation portal. There you can find the following topics:

Web SDK Initialisation

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

Server-Side Authentication

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

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

Reference the Web SDK Library

Import the safecharge.js JavaScript library.

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

Initialise the Web SDK

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

COPIED
1
2
3
4
5
6
// Instantiate Safecharge API
var sfc = SafeCharge({
sessionToken : '<sessionToken>', // received from Server-Side Authentication
      env:'int', // the environment you’re running on, if omitted prod is default
      merchantSiteId : 152358 // your merchantsite id provided by Safecharge
});


 

Card Data Representation

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:

SafeCharge Fields

SafeCharge Fields is a Web SDK feature that provides full PCI descoping. It 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.

SafeCharge Fields can be used with the following methods, by passing to them the cardholder details collected by SafeCharge Fields:

Simple Card Integration

  1. Import the safecharge.js library.

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


2. Create a simple container for your form.

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


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

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

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

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

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

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


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

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


5. Instantiate SafeCharge Fields.

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


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


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

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


8. Process the card.
You can use the cardNumber returned from the previous step to be processed either by the createPayment() or authenticate3d() Web SDK methods.
If you prefer to process the payment server to server, you can use the getToken() to receive the temporary token to be processed with the payment API method. The temporary token is passed within the paymentOption field that is returned from getToken().

createPayment Method

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

getToken Method

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

    }
});

Three-Part Card Fields Integration

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

  1. Import safecharge.js

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


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

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


3. Instantiate SafeCharge Web SDK.

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


4. Instantiate SafeCharge Fields.

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


5. Create custom styles and classes for SafeCharge Fields.

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

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

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

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


6. Create and attach fields to the DOM.

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

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

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


7. Process the card.
You can use the cardNumber returned from the previous step to be processed either by the createPayment() or authenticate3d() Web SDK methods.
If you prefer to process the payment server to server, you can use the getToken() to receive the temporary token to be processed with the payment API method. The temporary token is passed within the paymentOption field that is returned from getToken().

createPayment Method

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

getToken Method

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

    }
});

Additional Features

Additional Methods

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

An example of selecting an element and invoking the method:

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

SafeCharge Fields Custom Styling – States and Attributes

Supported States

We support custom styling for 4 states of SafeCharge Fields.

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

            },
            empty: {

            },
            valid: {

            },
            invalid: {
            },
   };

Supported Attributes

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

Supported Events

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

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

Validation Errors Handling

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

For errors, the following events are thrown:

Error sample:

 

SDK Methods

createPayment()

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

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

Input

Input Parameters

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



In addition, you can send the fields that appear in the following table. You can send these fields either with the preceding authentication server-side or /openOrder API call or directly to createPayment.

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

Output

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

Output Parameters

PARAMETER DESCRIPTION
result
String(20)
The cashier status of merchant request. Possible statuses:
APPROVED
DECLINED
ERROR
Read more
Read less
errCode
String(11)
If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0.
Values as detailed in Errors Handling. In addition, it can have the value of “-5”, which means the 3D Secure process was aborted.
Read more
Read less
errorDescription
String(400)
If an error occurred on the request side, an error reason is returned in this parameter; for example, failure in checksum validation, timeout from processing engine, etc.
Values as detailed in Errors Handling. In addition, it can have the value of “General 3D error”, which means the 3D Secure process was aborted.
Read more
Read less
Canceled
Boolean
If the process was cancelled by the end user
transactionId
String(20)
The gateway transaction ID.
ccCardNumber
String(20)
The credit card number in a mask, for example: 4****1111.
bin
String(2)
The bin number representing the issuer.
last4Digits
String(4)
The last four digits of the card number.
ccExpMonth
String(2)
The expiration month
ccExpYear
String(4)
The expiration year.
userPaymentOptionId
String
This field represents the ID for the newly created payment option, which can be referenced in future requests.
Refer to Card-on-File for further details.
Read more
Read less
threeDReasonId
String
Reason ID for a failed 3DS authorisation as received from the issuer.
threeDReason
String
Reason description for a failed 3DS authorisation as received from the issuer.
challengeCancelReasonId
String
Reason ID for a cancelled 3DS authorisation as received from the issuer.
ChallengeCancelReason
^String
isLiabilityOnIssuer
String
Indicates if there is 3D secure liability shift.
isExemptionRequestInAuthentication
String
Indicates if an exemption was requested during authorisation.
challengePreferenceReason
String
If a challenge is requested, this fields provides the reason for it.

getApms()

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

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

Code Sample:

Input Parameters

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

Output Parameters

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

Code Sample:


 

authenticate3d()

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

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

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

Input

Input Parameters

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



In addition, you can send the fields that appear in the following table. You can send these fields either with the preceding authentication server-side or /openOrder API call or directly to authenticate3d.

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

Output

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

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

(For the complete response specification, please refer to the /payment Output Parameters table.)

Output Parameters

PARAMETER DESCRIPTION
eci
String(2)
The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are:
ECI = 5(VISA), 2(MC): The cardholder was successfully authenticated.
ECI = 6(VISA), 1(MC): The issuer or cardholder does not participate in a 3D Secure program.
ECI = 7: Payment authentication was not performed.
Read more
Read less
cavv
String(50)
The card authentication verification value as received from the MPI.
xid
String(50)
The transaction ID received from the MPI for 3D v1.
dsTransID
String(36)
The transaction ID received from the MPI for 3D v2.
result
String(20)
The cashier status of merchant request. Possible statuses:
APPROVED
DECLINED
ERROR
Read more
Read less
errCode
String(11)
If an error occurred on the request side, an error code is returned in this parameter. In case of success (declined or approved), returns 0.
Values as detailed in Errors Handling. In addition, it can have the value of “-5”, which means the 3D Secure process was aborted.
Read more
Read less
errorDescription
String(400)
If an error occurred on the request side, an error reason is returned in this parameter; for example, failure in checksum validation, timeout from processing engine, etc.
Values as detailed in Errors Handling. In addition, it can have the value of “General 3D error”, which means the 3D Secure process was aborted.
Read more
Read less
Canceled
Boolean
If the process was cancelled by the end user
transactionId
String(20)
The gateway transaction ID.
ccCardNumber
String(20)
The credit card number in a mask, for example: 4****1111.
bin
String(2)
The bin number representing the issuer.
last4Digits
String(4)
The last four digits of the card number.
ccExpMonth
String(2)
The expiration month
ccExpYear
String(4)
The expiration year.
userPaymentOptionId
String
This field represents the ID for the newly created payment option, which can be referenced in future requests.
Refer to Card-on-File for further details.
Read more
Read less
threeDReasonId
String
Reason ID for a failed 3DS authorisation as received from the issuer.
threeDReason
String
Reason description for a failed 3DS authorisation as received from the issuer.
challengeCancelReasonId
String
Reason ID for a cancelled 3DS authorisation as received from the issuer.
ChallengeCancelReason
^String
isLiabilityOnIssuer
String
Indicates if there is 3D secure liability shift.
isExemptionRequestInAuthentication
String
Indicates if an exemption was requested during authorisation.
challengePreferenceReason
String
If a challenge is requested, this fields provides the reason for it.

getToken()

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

Payment API

/getSessionToken

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getSessionToken.do
Example Request
COPIED
1
2
3
4
5
6
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "timeStamp": "20170118191622",
    "checksum": "58fc84fe0fccf3be3f77278884a868d5b26cd35d3a27a80e30603a65ff5ddd17"
}

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0"
}

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

Input Parameters

PARAMETER DESCRIPTION
merchantId
String(20)
Required
Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
Required
Merchant Site ID provided by SafeCharge.
timeStamp
String(14)
Required
The local time when the method call is performed in the following format: YYYYMMDDHHmmss
checksum
String(256)
Required
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.
clientRequestId
String(255)
Required
ID of the API request in merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.

Output Parameters

PARAMETER DESCRIPTION
sessionToken
String(36)
The returned session identifier returned. To be used as an input.
merchantId
String(20)
Required
Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
Required
Merchant Site ID provided by SafeCharge.
internalRequestId
String(20)
SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
status
String(20)
The status of merchant’s API request/call. Possible statuses:
SUCCESS
ERROR.
errCode
String(11)
The error code in the event of an error.
reason
String(400)
The error reason in the event of an error (i.e. failure in checksum validation, timeout from processing engine, etc.).
version
String(10)
The current version of the merchant request. Current version is 1.
clientRequestId
String(20)
ID of the API request in merchant’s system.

/openOrder

Definition

https://ppp-test.safecharge.com/ppp/api/v1/openOrder.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": " 487106",
    "clientUniqueId": "12345",
    "currency": "USD",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
    "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "",
        "deviceOS": "",
        "browser": "",
        "ipAddress": ""
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "sippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "addendums": {
        "localPayment": {
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        }
    },
    "timeStamp": "20170118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0"
}

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

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

Input Parameters

PARAMETER DESCRIPTION
merchantId
String(20)
Required
Merchant ID provided by SafeCharge.
merchantSiteId
String(20)
Required
Merchant Site ID provided by SafeCharge.
userTokenId
String(255)
Optional
ID of the user in the merchant’s system.
clientUniqueId
String(45)
Required
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
Read more
Read less
currency
String(3)
Conditional
The three-character ISO currency code.
This field is mandatory when using the Web SDK createPayment method.
amount
Double(12)
Conditional
The transaction amount.
This field is mandatory when using the Web SDK createPayment method.
amountDetails
Class
Optional
totalShipping
totalHandling
totalDiscount
totalTax

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

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

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognised).
Read more
Read less
userDetails
Class
Optional
firstName(String, 30)
lastName(String, 40)
address(String, 60)
phone(String, 18)
zip(String, 10)
city(String, 30)
country (two-letter ISO country code)(String, 2),
state (two-letter ISO state code)(2),
email (String, 100)
county (String, 255)

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
Read more
Read less
shippingAddress
Class
Optional
firstName (String, 30)
lastName (String, 40)
address (String, 60)
cell (String, 18)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (two-letter ISO country code)(String, 2)
state(two-letter ISO state code)(String, 2)
email(100)
shippingCounty (String, 255)
addressLine2 (string, 50)
addressLine3 (string, 50)
If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using the billingAddress parameter.
Read more
Read less
billingAddress
Class
Optional
firstName (String, 30)
lastName (String, 40)
address (String, 60)
cell (String, 18)
phone (String, 18)
zip (String, 10)
city (String, 30)
country (two-letter ISO country code)(String, 2),
state (two-letter ISO state code)(String, 2),
email (String, 100)
county (String, 255)
addressMatch (String, 1) – Set to “Y” when address matches shipping address
addressLine2(String, 50)
addressLine3(String, 50)
homePhone(String)
workPhone (String)
Read more
Read less
dynamicDescriptor
Class
Optional
merchantName (String, 25)
merchantPhone (String, 13)

merchantName - The merchant name, as is displayed for the transaction on the consumer’s card statement.
For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
“XXX"<merchant name>”
“XXX” must be 3 characters and identifies the payment facilitator.
“<merchant name>” must be maximum of 18 characters.

merchantPhone - The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
Read more
Read less
merchantDetails
Class
Optional
customField1 (String, 255, not mandatory)
customField2 (String, 255, not mandatory)
customField3 (String, 255, not mandatory)
customField4 (String, 255, not mandatory)
customField5 (String, 255, not mandatory)
customField6 (String, 255, not mandatory)
customField7 (String, 255, not mandatory)
customField8 (String, 255, not mandatory)
customField9 (String, 255, not mandatory)
customField10 (String, 255, not mandatory)
customField11 (String, 255, not mandatory)
customField12 (String, 255, not mandatory)
customField13 (String, 255, not mandatory)
customField14 (String, 255, not mandatory)
customField15 (String, 255, not mandatory)

This allows the merchant to send information with the request to be saved in the API level and returned in response. It will not be passed to the payments gateway and will not be used for processing.
Read more
Read less
urlDetails
Class
Optional
Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
successUrl (string, 1000)
failureUrl (string, 1000)
pendingUrl (string, 1000)
notificationUrl (string, 1000)
Read more
Read less
addendums
Class
Optional
This block contains industry specific addendums. The addendum fields that appear are based on the specific addendum type.

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

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

The nationalId parameter must be sent during processing by local banks in certain countries, for example: Israel, Latin America (LATAM). For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
Read more
Read less
timeStamp
String(14)
Required
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String(256)
Required
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.
clientRequestId
String(255)
Required
ID of the API request in the merchant’s system. This value must be unique.
This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
Read more
Read less
subMerchant
Class
Conditional
countryCode (String,2) – The payment facilitator’s sub-merchant’s two-character ISO country code.
city (String, 20) – The payment facilitator’s sub-merchant’s city name.
id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
Read more
Read less

Output Parameters

PARAMETER DESCRIPTION
sessionToken
String
Session identifier to be used by the request that processed the newly opened order.
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.
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.
orderId
String
The order ID provided by SafeCharge.
clientRequestId
String
ID of the API request in the merchant’s system.

/payment

Definition

https://ppp-test.safecharge.com/ppp/api/v1/payment.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
{ 
   "sessionToken":"3993eb0c-5f64-4a6c-b16c-485818eb76eb",
   "merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "userTokenId":"230811147",
   "clientRequestId":"1C6CT7V1L",
   "clientUniqueId":"12345",
   "orderId":"34383481",
   "currency":"USD",
   "amount":"10",
   "paymentOption":{ 
      "card":{ 
         "cardNumber":"4017356934955740",
         "cardHolderName":"John Smith",
         "expirationMonth":"12",
         "expirationYear":"2022",
         "CVV":"217"
      }
   },
   "deviceDetails":{ 
      "ipAddress":"93.146.254.172"
   },
  "billingAddress":{ 
       "address":"address",
       "city":"city",
       "country":"DE",
       "state":"",
       "zip":"1335"
   },
   "timeStamp":"20191105081132",
   "checksum":"5582d0189dd440f4bbf960569ec22e77"
}

Example Response

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

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

Mandatory Fields

Selecting a Payment Method (paymentOption Class)

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

Input Parameters

PARAMETER DESCRIPTION
merchantId
String(20)
Required
The merchant ID provided by SafeCharge (part of the authentication credentials).
merchantSiteId
String(20)
Required
The merchant Site ID provided by SafeCharge (part of the authentication credentials).
sessionToken
String(36)
Required
Session identifier returned by /getSessionToken.
See /getSessionToken for details.
timeStamp
String(14)
Required
The local time when the method call is performed in the format: YYYYMMDDHHmmss. Needed for the “checksum” hashing calculation.
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
View hashing calculation for details or use the Checksum tool.
Read more
Read less
currency
String(3)
Required
The three-character ISO currency code.
amount
Double(12)
Required
The transaction amount.
This amount must be identical to the amount listed in the dynamic3D.
paymentOption
Class
Required
This class represents the details on the payment method.
Can be one of 3 options:
card – Represents a credit/debit card. Fields:
- cardNumber, string(20) – The card number
- cardHolderName, string(70) – The card holder name
- expirationMonth, string(2) – The card expiration month
- expirationYear, string(4) – The card expiration year
- CVV, string(4) – The CVV/CVC security code
- threeD, (class) – Stores the 3D information. Please refer to threeD class.
More options for cards:
externalToken (class) – For using external token provider such as ApplePay or Visa Checkout (instead of card details). Class details please find here
ccTempToken – If you are using the Web SDK getToken(), you can send the returned ccTempToken as a substitute to the card number and CVV.
-or-
alternativePaymentMethod – Represents an alternative payment method. For details, please refer to alternativePaymentMethod Class.
-or-
userPaymentOptionId – This is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. SafeCharge keeps payment option details from previous uses.
Read more
Read less
transactionType
String(45)
Optional
The type of transaction: Sale or Auth.
Sale – is a regular payment request
Auth – Performs an authorisation only request. For details, see Auth and Settle.
subMethodDetails
Class
Optional
subMethod(String) – details below
email(String) – details below

This JSON class is for advanced APMs flows. See APM Submethods for details.
The submethod parameter enables working with a specific payment method in a few different flows.

Supported Flows:
  • PayPal quick registration mode
         subMethod should be set to QuickRegistration. No other fields are required.
  • PayPal Membership Agreement
         subMethod should be set to referenceTransaction.
  • Skrill1tap
         subMethod should be set to skrill1Tap. No other submethod fields are required.
         email field should be provided.
  • Trustly PayNPlay
         subMethod should be set to PayNPlay.
  • Post Finance Alias Recurring
         subMethod should be set to AliasRegistration.
  • Read more
    Read less
    relatedTransactionId
    String(19)
    Conditional
    Mandatory in the following cases:
    For 3D Secure 2.0 (refer to the 3D Secure 2.0 guide for details):
  • The transaction ID of the initPayment on the first call.
  • The transaction ID of the first Payment call of the second call.
    For recurring/rebilling and MIT:
    Represents the reference to the original transaction ID of the initial transaction (see Merchant Initiated Payments for details).
  • Read more
    Read less
    userTokenId
    String(255)
    Optional
    This field uniquely identifies your consumer/user in your system.
    Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details.
    Read more
    Read less
    clientUniqueId
    String(45)
    Optional
    This ID identifies the transaction in your system. Optionally, you can pass this value to us and we will store it with the transaction record created in our system for your future reference.
    isRebilling
    Integer(2)
    Optional
    When performing recurring/rebilling, use this field to indicate the recurring step with the following vales:
    0 – For the initiating recurring event (first recurring transaction).
    1 – For all following recurring transactions.
    Notes:
  • Rebilling can be performed using userPaymentOptionId or card (under the paymentOption block). If done using card, then it is highly recommended to send its relatedTransactionId as well.
  • If isRebilling=1:
    - It can never be sent with the threeD block (under the paymentOption block)
    - For a 3DS transaction, you also must specify rebillExpiry and rebillFrequency under the v2AdditionalParams block, under the threeD block.
  • Read more
    Read less
    rebillingType
    String
    Optional
    When performing recurring/rebilling, use this field to indicate the recurring type with the following vales:
    RECURRING – Regular, recurring charging of the consumer
    MIT – Merchant Initiated Transaction. In case this is a one-time payment, initiated by the merchant.
    Read more
    Read less
    authenticationOnlyType
    String(2)
    Optional
    This is an advanced field, intended for merchants using the Zero Authorisation feature.
    Most merchants do not need to use this field, as this is managed by SafeCharge. Only merchants that are not using tokenization and/or are not using the user payment option management are required to set this field.
    The field marks the type of Zero Authorisation and the purpose it is being used for.
    Possible values:
    01 = for Recurring transactions
    02 = For Instalment transactions
    03 = When performing just an “Add card” action for future use
    04 = Maintain card information
    05 = Account verification only.
    Read more
    Read less
    isPartialApproval
    String(1)
    Optional
    This describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds within the desired payment method.
    Partial approval is only supported by SafeCharge acquiring. For partial approval to be available for the merchant it should be configured by SafeCharge’s Integration Team.
    Possible values:
    1 – allow partial approval
    0 – not allow partial approval
    Read more
    Read less
    amountDetails
    Class
    Optional
    totalShipping (String, not mandatory)
    totalHandling (String, not mandatory)
    totalDiscount (String, not mandatory)
    totalTax (String, not mandatory)

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

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

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

    These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.
    Read more
    Read less
    dynamicDescriptor
    Class
    Optional
    descriptorMerchantName (String, 25, not mandatory)
    descriptorMerchantPhone (String, 13, not mandatory)

    merchantName - The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    merchantPhone - The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
    Read more
    Read less
    isMoto
    String(1)
    Optional
    Set this field to “1” to mark the transaction as MOTO (mail order/telephone order).
    Leave null or “0” for regular transaction.
    merchantDetails
    Class
    Optional
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)
    Read more
    Read less
    urlDetails
    Class
    Optional
    Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
    successUrl (string, 1000)
    failureUrl (string, 1000)
    pendingUrl (string, 1000)
    notificationUrl (string, 1000)
    Read more
    Read less
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    Risk rules and traffic management rules are usually built based on this field value.
    Read more
    Read less
    productId
    String(50)
    Optional
    A free text field used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this field value.
    Read more
    Read less
    customData
    String(255)
    Optional
    This parameter can be used to pass any type of information.
    If sent in request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    This is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SafeCharge API SDKs to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SafeCharge API.
    Read more
    Read less
    orderId
    String(45)
    Optional
    The order ID provided by SafeCharge.
    This parameter is passed to define which merchant order to update.
    clientRequestId
    String(255)
    Optional
    Use this advanced field to prevent idempotency. Use it to uniquely identify the request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
    Read more
    Read less
    subMerchant
    Class
    Conditional
    countryCode (String,2) – The payment facilitator’s sub-merchant’s two-character ISO country code.
    city (String, 20) – The payment facilitator’s sub-merchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    Read more
    Read less

    Output Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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.
    internalRequestId
    Long(20)
    SafeCharge’s internal unique request ID (used for reconciliation purpose, etc.).
    status
    String(20)
    The cashier status of merchant request.
    Possible statuses: SUCCESS or ERROR
    transactionStatus
    String(20)
    The gateway transaction status.
    Possible values:
    APPROVED - The transaction was authorised and approved.
    DECLINED – The transaction authorisation failed.
    ERROR – An error occurred. Please refer to Error Handling for details
    REDIRECT – The transaction was not completed. The end user needs to be redirected to a webpage to complete the transaction.
    There are two cases in which this response is returned:
  • 3D Secure – The user needs to be redirected to paymentOption.threeD.acsUrl. See 3D Secure Guide for full details.
  • Alternative payment method that requires redirection – The URL is on paymentOption.redirectURL.
  • Read more
    Read less
    paymentOption
    Class
    This class represents the data retrieved from the processed payment method. Can be either card, or in case of alternative payment method, it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below:

    redirectUrl – String() – The redirect URL to follow for an alternative payment method, which needs to be redirected to in order to process.
    -or-
    Card – Information about the card that was processed:
    bin (String) – The bin number representing the issuer.
    last4Digits (String) – The last four digits of the card number.
    ccCardNumber (String) – The credit card number in a mask, for example:***1111
    ccExpMonth (String) – The expiration month.
    • ccExpYear (String) – The expiration year.
    cvv2Reply (String) – The CVV2 (card verification value).
    avsCode (String) – The AVS (address verification) response.
    acquirerId (String) – The acquirer ID of the acquirer which processed the transaction.
    threeD (class) – Contains the required 3D Secure information. Refer to the threeD (out) chapter for details.

    userPaymentOptionId – In addition to the above, this field represents the ID for the newly created payment option, which can be referenced in future requests.
    For full details, refer to Card-on-File.
    Read more
    Read less
    merchantDetails
    Class
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)

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

    isPartialApproval (String-True or False)
    amountInfo:
    requestedAmount (String),
    requestedCurrency (String),
    processedAmount (String),
    processedCurrency (String)
    Read more
    Read less
    transactionType
    String(45)
    The type of transaction: Sale or Auth.
    Sale – is a regular payment request
    Auth – Performs an authorisation only request. For details, see Auth and Settle.
    customData
    String(255)
    This parameter can be used to pass any type of information.
    If sent in the request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
    Read more
    Read less
    fraudDetails
    Class
    finalDecision (String)
    score (decimal)
    recommendations (String)
    system {systemId(String),systemName (String),decision (String)
    rules [ruleId(String),ruleDescription (String)]}

    The 'score’ refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model.
    The ‘system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
    The ‘rule’ refers to the risk management system rules triggered by the transaction.
    The ‘decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction.
    There are five possible values for the decision parameter:
  • Accept – The risk management system accepts the transactions.
  • Reject – The risk management system rejects the transaction. The transaction is not passed to bank for authorisation. The reasons are returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review, but still accepts the transaction.
  • Error – An error occurred during the risk management system operation. The gateway continues to process the transaction through the bank.
  • None – No risk analysis was performed. The gateway continues to process the transaction through the bank.
    The finalDecision refers to when deciding whether to accept or reject a transaction. The risk management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a ‘Reject’ decision, the finalDecision accepts the transaction. If at least one of the rules leads to a ‘Reject’ decision, the finalDecision rejects the transaction.
    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less
    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.
    clientRequestId
    String(20)
    The ID of the API request in merchant system.

    /settleTransaction

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/settleTransaction.do
    Example Request
    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    
    {
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "clientUniqueId": "12345",
        "amount": "9.0",
        "currency": "EUR",
        "relatedTransactionId": "8495798459",
        "authCode": "8378749",
        "descriptorMerchantName": "Name",
        "descriptorMerchantPhone": "+4412378",
        "comment": "some comment",
        "urlDetails": {
            "notificationUrl": ""
        },
        "addendums": {
            "airline": {
            "addendumSent":"",
            "pnrCode":"",
            "bookingSystemUniqueId":"",
            "computerizedReservationSystem":"",
            "ticketNumber":"",
            "documentType":"",
            "flightDateUTC":"",
            "issueDate":"",
            "travelAgencyCode":"",
            "travelAgencyName":"",
            "travelAgencyInvoiceNumber":"",
            "travelAgencyPlanName":"",
            "restrictedTicketIndicator":"",
            "issuingCarrierCode":"",
            "isCardholderTraveling":"",
            "passengersCount":"",
            "infantsCount":"",
            "payerPassportId":"",
            "totalFare":"",
            "totalTaxes":"",
            "totalFee":"",
            "boardingFee":"",
            "ticketIssueAddress":"",
            "passengerDetails": {
                "passengerId":"",
                "passportNumber":"",
                "customerCode":"",
                "frequentFlyerCode":"",
                "title":"",
                "firstName":"",
                "lastName":"",
                "middleName":"",
                "dateOfBirth":"",
                "phoneNumber":""
            },
            "flightLegDetails": {
                "flightLegId":"",
                "airlineCode":"",
                "flightNumber":"",
                "departureDate":"",
                "arrivalDate":"",
                "departureCountry":"",
                "departureCity":"",
                "departureAirport":"",
                "destinationCountry":"",
                "destinationCity":"",
                "destinationAirport":"",
                "legType":"",
                "flightType":"",
                "ticketDeliveryMethod":"",
                "ticketDeliveryRecipient":"",
                "fareBasisCode":"",
                "serviceClass":"",
                "seatClass":"",
                "stopOverCode":"",
                "departureTaxAmount":"",
                "departureTaxCurrency":"",
                "fareAmount":"",
                "feeAmount":"",
                "taxAmount":"",
                "layoutIntegererval":""
                }
            }
        },
        "customSiteName":"",
        "productId":"",
        "customData":"",
        "webMasterId":"",
        "timeStamp": "20150915143321",
        "checksum": "1cff28783432713e5dfc4fdc8f011b76"
    }
    

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    {
       "merchantId": "8263015379487437770",
       "merchantSiteId": "39",
       "internalRequestId": "45",
       "transactionId": "8498764859",
       "externalTransactionId": "",
       "status": "SUCCESS",
       "transactionStatus": "APPROVED",
       "authCode": "8378749",
       "errCode": "0",
       "reason": "",
       "paymentMethodErrorCode": "0",
       "paymentMethodErrorReason": "",
       "gwErrorCode": "0",
       "gwErrorReason": "",
       "gwExtendedErrorCode": "0",
       "customData":"",
       "version": "1"
    }
    

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

    Input Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    clientUniqueId
    String(255)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    Read more
    Read less
    amount
    Decimal
    (12)
    Required
    The transaction amount.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    It is required to send the same currency as the one sent before for the related transaction.
    relatedTransactionId
    String(19)
    Required
    The ID of the original transaction to be settled.
    authCode
    String(128)
    Required
    The authorisation code of the original transaction to be refunded.
    descriptorMerchantName
    String(25)
    Optional
    Allows the merchant to define a dynamic descriptor, which appears in the payment statement. The name field should contain the merchant name.

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

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

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

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

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

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

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

    For more information and for required SafeCharge configurations settings, please contact SafeCharge’s Integration Team at integration@safecharge.com.
    Read more
    Read less
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    A free text field used to identify the product/service sold.
    If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
    Read more
    Read less
    customData
    String(255)
    Optional
    This parameter can be used to pass any type of information.
    If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order:
    merchantId
    merchantSiteId
    clientRequestId
    clientUniqueId
    amount
    currency
    relatedTransactionId
    authCode
    descriptorMerchantName
    descriptorMerchantPhone
    comment
    urlDetails
    timeStamp
    merchantSecretKey
    Read more
    Read less
    clientRequestId
    String(128)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Read more
    Read less
    subMerchant
    Class
    Conditional
    countryCode (String,2) – The payment facilitator’s sub-merchant’s two-character ISO country code.
    city (String, 20) – The payment facilitator’s sub-merchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    Read more
    Read less

    Output Parameters

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

    /refundTransaction

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/refundTransaction.do
    Example Request
    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    {
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "clientUniqueId": "12345",
        "amount": "9.0",
        "currency": "EUR",
        "relatedTransactionId": "8495798459",
        "authCode": "8378749",
        "comment": "some comment",
        "urlDetails": {
            "notificationUrl": "http://notificationUrl.com"
        },
        "customSiteName":"",
        "productId":"",
        "customData":"",
        "webMasterId":"",
        "timeStamp": "20150915143321",
        "checksum": "1cff28783432713e5dfc4fdc8f011b76"
    }
    

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    {
       "merchantId": 8263015379487437770,
       "merchantSiteId": "39",
       "internalRequestId": 45,
       "transactionId": "8498764859",
       "externalTransactionId": "",
       "status": "SUCCESS",
       "transactionStatus": "APPROVED",
       "authCode": "8378749",
       "errCode": "0",
       "errReason": "",
       "paymentMethodErrorCode": "0",
       "paymentMethodErrorReason": "",
       "gwErrorCode": "0",
       "gwErrorReason": "",
       "gwExtendedErrorCode": "0",
       "customData":"",
       "version": "1"
    }
    

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

    Input Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    clientUniqueId
    String(255)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    Read more
    Read less
    amount
    Decimal(12)
    Required
    The transaction amount.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    It is required to send the same currency as the one sent before for the related transaction.
    relatedTransactionId
    String(19)
    Required
    The ID of the settle transaction.
    authCode
    String(128)
    Required
    The authorisation code of the related settle transaction, to be compared to the original one.
    This is mandatory for cards, non-mandatory for APMs.
    comment
    String(255)
    Optional
    Enables the addition of a free text comment to the request.
    urlDetails
    Class
    Optional
    notificationUrl(String, 1000)

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    A free text field used to identify the product/service sold.
    If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
    customData
    String(255)
    Optional
    This parameter can be used to pass any type of information.
    If sent in request, then is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey.
    Read more
    Read less
    clientRequestId
    String(128)
    Required
    ID of the API request in merchant system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Read more
    Read less
    subMerchant
    Class
    Conditional
    countryCode (String,2) – The payment facilitator’s sub-merchant’s two-character ISO country code.
    city (String, 20) – The payment facilitator’s sub-merchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    Read more
    Read less

    Output Parameters

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

    /voidTransaction

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/voidTransaction.do
    Example Request
    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    {
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "clientUniqueId": "12345",
        "amount": "9.0",
        "currency": "EUR",
        "relatedTransactionId": "8495798459",
        "authCode": "8378749",
        "comment": "some comment",
        "urlDetails": {
            "notificationUrl": "http://notificationUrl.com"
        },
        "customSiteName":"",
        "productId":"",
        "customData":"",
        "webMasterId":"",
        "timeStamp": "20150915143321",
        "checksum": "1cff28783432713e5dfc4fdc8f011b76"
    }
    

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    {
       "merchantId": 8263015379487437770,
       "merchantSiteId": "39",
       "internalRequestId": 45,
       "transactionId": "8498764859",
       "externalTransactionId": "",
       "status": "SUCCESS",
       "transactionStatus": "APPROVED",
       "authCode": "8378749",
       "errCode": "0",
       "errReason": "",
       "paymentMethodErrorCode": "0",
       "paymentMethodErrorReason": "",
       "gwErrorCode": "0",
       "gwErrorReason": "",
       "gwExtendedErrorCode": "0",
       "customData":"",
       "version": "1"
    }
    

    The voidTransaction method is used for voiding a previously performed authorisation, within a two-phase Auth-Settle process. Please note that a Void action is not always supported by the payment method or the card issuer.

    Input Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    clientUniqueId
    String(255)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    Read more
    Read less
    amount
    Decimal(12)
    Required
    The transaction amount.
    It is required to send an amount that is equal to the amount sent in the related transaction that this void aim to cancel.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    It is required to send the same currency as the one sent before for the related transaction.
    relatedTransactionId
    String(19)
    Required
    The ID of the original auth transaction.
    authCode
    String(128)
    Required
    The authorisation code of the related settle transaction, to be compared to the original one.
    comment
    String(255)
    Optional
    Enables the addition of a free text comment to the request.
    urlDetails
    Class
    Optional
    notificationUrl(String, 1000)

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    A free text field used to identify the product/service sold.
    If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until parameter maximum length.
    customData
    String(255)
    Optional
    This parameter can be used to pass any type of information.
    If it is sent in the request, then it is passed on to the payments gateway and is visible in SafeCharge’s back-office tool for transaction reporting and is returned in response.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, clientUniqueId, amount, currency, relatedTransactionId, authCode, comment, urlDetails, timeStamp, merchantSecretKey.
    Read more
    Read less
    clientRequestId
    String(128)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Read more
    Read less
    subMerchant
    Class
    Conditional
    countryCode (String,2) – The payment facilitator’s sub-merchant’s two-character ISO country code.
    city (String, 20) – The payment facilitator’s sub-merchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    Read more
    Read less

    Output Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Merchant Site ID provided by SafeCharge.
    internalRequestId
    String(20)
    SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
    transactionId
    String(255)
    The transaction ID of the void transaction for future actions.
    externalTransactionId
    String(20)
    The transaction ID of the transaction in the event that an external service is used.
    status
    String(20)
    The status of merchant’s API request/call.
    Possible statuses: SUCCESS or ERROR.
    transactionStatus
    String(20)
    The gateway transaction status.
    Possible values: APPROVED, DECLINED, ERROR.
    authCode
    String(128)
    Authorisation code of the transaction.
    errCode
    String(11)
    If an error occurred on the request side, an error code is returned in this parameter.
    reason
    String(400)
    If an error occurred on the request side, an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
    paymentMethodErrorCode
    Integer(11)
    If an error occurred on the APM side, an error code is returned in this parameter.
    paymentMethodErrorReason
    String(400)
    If an error occurred on the APM side, an error reason is returned in this parameter.
    gwErrorCode
    Integer(11)
    If an error occurred in the gateway, then an error code is returned in this parameter.
    gwErrorReason
    String(400)
    If an error occurred in the gateway, then an error reason is returned in this parameter. (e.g. failure in checksum validation, timeout from processing engine, etc.)
    gwExtendedErrorCode
    Integer(11)
    Error code if error occurred on the bank’s side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    customData
    String(255)
    This parameter can be used to pass any type of information.
    If it is sent in the request, then it is passed on to the payments gateway and is visible in SafeCharge’s back-office tool for transaction reporting and is returned in response.
    Read more
    Read less
    version
    Integer(10)
    The current version of the request. The current version is 1.
    clientRequestId
    String(20)
    ID of the API request in merchant system.

    /payout

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/payout.do
    Example Request
    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    
    {
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "userTokenId": "487106",
        "clientUniqueId": "12345",
        "amount": "9.0",
        "currency": "EUR",
        "dynamicDescriptor": {
            "merchantName": "merchantName",
            "merchantPhone": "merchantPhone"
        },
        "merchantDetails": {
            "customField1": "",
            "customField2": "",
            "customField3": "",
            "customField4": "",
            "customField5": "",
            "customField6": "",
            "customField7": "",
            "customField8": "",
            "customField9": "",
            "customField10": "",
            "customField11": "",
            "customField12": "",
            "customField13": "",
            "customField14": "",
            "customField15": ""
        },
       "deviceDetails":{ 
          "deviceType":"DESKTOP",
          "deviceName":"deviceName",
          "deviceOS":"deviceOS",
          "browser":"browser",
          "ipAddress":"127.0.0.1"
       },
        "userPaymentOption":{
            "userPaymentOptionId":"1459503"
        },
        "comment": "some comment",
        "urlDetails": {
            "notificationUrl": ""
        },
        "timeStamp": "20150915143321",
        "checksum": "1cff28783432713e5dfc4fdc8f011b76"
    }
    

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    
    {
       "merchantId": "8263015379487437770",
       "merchantSiteId": "39",
       "userTokenId": "487106",
       "clientUniqueId": "12345",
       "internalRequestId": "866",
       "transactionId": "8498764859",
       "externalTransactionId": "",
       "status": "SUCCESS",
       "transactionStatus": "APPROVED",
       "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
       },
       "userPaymentOptionId": "12442",
       "errCode": "0",
       "reason": "",
       "paymentMethodErrorCode": "0",
       "paymentMethodErrorReason": "",
       "gwErrorCode": "0",
       "gwErrorReason": "",
       "gwExtendedErrorCode": "0",
       "version": "1"
    }
    

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

    Input Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    Required
    ID of the user in the merchant’s system.
    clientUniqueId
    String(45)
    Required
    ID of the transaction in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Appears in DMN as merchant_unique_id parameter.
    Read more
    Read less
    amount
    Double(12)
    Required
    The transaction amount.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    dynamicDescriptor
    Class
    Optional
    merchantName(String, 25)
    merchantPhone(String, 13)



    merchantName - The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    merchantPhone - The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)

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

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

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

    This parameter determines where to return the DMN.
    Each parameter is limited for up to 1000 characters.
    deviceDetails
    Class
    Only ipAddress
    deviceType (String, 10)
    deviceName (String, 255)
    deviceOS (String, 255)
    browser (String, 255)
    ipAddress (String, 15)

    Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (if device type cannot be recognised). The ipAddress parameter can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.
    Read more
    Read less
    timeStamp
    String(14)
    Required
    The local time of the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.
    clientRequestId
    String(255)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Read more
    Read less

    Output Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Merchant Site ID provided by SafeCharge.
    userTokenId
    String(255)
    ID of the user in the merchant’s system.
    clientUniqueId
    String(45)
    ID of the transaction in the merchant’s system.
    Appears in DMN as merchant_unique_id parameter.
    internalRequestId
    String(20)
    ID of the API request in merchant system.
    transactionId
    String(20)
    The gateway transaction ID.
    externalTransactionId
    String(20)
    The transaction ID of the transaction in the event that an external service is used.
    status
    String(20)
    The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
    transactionStatus
    String
    The gateway transaction status.
    Possible values: APPROVED, DECLINED, ERROR.
    merchantDetails
    Class
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)

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

    /getPaymentStatus

    Definition

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

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    
    {
        "gwExtendedErrorCode": 0,
        "gwErrorCode": 0,
        "gwErrorReason": "",
        "authCode": "1234567",
        "transactionType": "Sale",
        "transactionStatus": "APPROVED",
        "userTokenId": "230811147",
        "transactionId": "1110000000004198292",
        "paymentOption": {
            "userPaymentOptionId": "14958143",
            "card": {
                "uniqueCC": "8/AOqY3oRC28rNNtUbtVPXjEtX0="
            }
        },
        "sessionToken": "274ff0d9-c859-42f5-ae57-997641f93471",
        "clientUniqueId": "256623868",
        "internalRequestId": 177988948,
        "status": "SUCCESS",
        "errCode": 0,
        "reason": "",
        "merchantSiteId": "180083",
        "version": "1.0"
    }
    

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

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

    Use cases:

    Input Parameters

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

    Output Parameters

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

    /initPayment

    Definition

    https://ppp-test.safecharge.com/ppp/api/v1/initPayment.do
    Example Request
    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    
    {
                    "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
                    "merchantId": "2502136204546424962",
                    "merchantSiteId": "126006",
                    "userTokenId": "230811147",
                    "orderId": "33704071",
                    "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": "merchant custom data",
                    "webMasterId": "M9UOWGECHKD2",
                    "timeStamp": "20190617110903",
                    "checksum": "eaca71a67d972fd47b796a02cf02b51844c8adeba734c54fea504c69bb16a171"
    }
    

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    
    {
        "reason": "",
        "orderId": "33704071",
        "transactionStatus": "APPROVED",
        "customData": "merchant custom data",
        "internalRequestId": 10036001,
        "version": "1.0",
        "transactionId": "2110000000000587378",
        "merchantSiteId": "126006",
        "transactionType": "InitAuth3D",
        "gwExtendedErrorCode": 0,
        "gwErrorCode": 0,
        "merchantId": "2502136204546424962",
        "clientUniqueId": "695701003",
        "errCode": 0,
        "paymentOption": {
            "card": {
                "ccCardNumber": "5****5761",
                "bin": "511142",
                "threeD": {
                    "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
                    "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
                    "v2supported": "true",
                    "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
                    "version": "2.1.0",
                    "directoryServerId":"A000000003",
                    "directoryServerPublicKey":"MIIFrjCCBJagAwIBAgIQB2rJm.."
                },
                "ccExpMonth": "12",
                "ccExpYear": "25",
                "last4Digits": "5761"
            }
        },
        "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
        "userTokenId": "230811147",
        "status": "SUCCESS"
    }
    

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

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

    Request Parameters

    Parameter Description
    sessionToken
    String(36)
    Required
    The session identifier returned by /getSessionToken.
    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.
    currency
    String(3)
    Required
    The ISO currency code.
    If the merchant did not call openOrder prior, then a value must be sent by the merchant in this parameter.
    amount
    String(12)
    Required
    The transaction amount.
    If the merchant did not call openOrder prior, then a value must be sent by the merchant in this parameter.
    deviceDetails
    Class
    Conditional
    The device’s details (conditional per configuration).
    deviceType (string, 10)
    deviceName (string, 255)
    deviceOS (string, 255)
    browser (string, 255)
    ipAddres (string, 15)
    Support device types: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognised).
    Read more
    Read less
    paymentOption
    Class
    Required
    Card payment information inside the card sub-class
    paymentOption.card
    Class
    Required
    Card data that must be passed as a parameter in the payment methods, and not prior in the payment flow (openOrder, updateOrder) as it may not be saved in the cashier/checkout DB.
    cardNumber (string, 20)
    cardHolderName (string, 70) expirationMonth (string, 2)
    expirationYear (string, 4)
    cvv (string, 4)
    OR
    ccTempToken(string, 45)
    cvv(string, 4)
    cardHolderName (string, 70)

    threeD class with the following field:
    threeD.methodNotificationUrl (string, 255) – The URL the ACS redirects to after performing the 3DS 2.0 fingerprinting. Refer to the 3D Secure 2.0 guide for details.
    Read more
    Read less
    customData
    String(255)
    Optional
    General data about the customer is provided by the merchant.This parameter can be used to pass any type of information to the gateway, which is returned in a response for the merchant records. This field is visible in Control Panel reports with transaction information.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send and is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SC REST API SDK’s to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SC REST API.
    Read more
    Read less
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss.
    checksum
    Hexi-decimal
    String(256)
    Required
    Hash (used hash algorithm, MD5 or SHA256, depends on merchantSite setting) of the values of the request parameters UTF-8 encoded, and concatenated in this order:
    merchantId
    merchantSiteId
    clientRequestId
    amount
    currency
    timestamp
    merchantSecretKey
    Read more
    Read less
    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.
    clientRequestId
    String(255)
    Required
    The ID of the API request in merchant system.

    Response Parameters

    Parameter Description
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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.
    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
    status
    String(20)
    The cashier status of merchant request.
    Possible statuses: SUCCESS or ERROR
    transactionStatus
    String(20)
    The gateway transaction status.
    errCode
    Integer(11)
    The error code if an error occurred at the cashier side.
    reason
    String(400)
    The error reason, if an error occurred on the cashier side.
    For example: failure in checksum validation, timeout from processing engine, etc.
    Read more
    Read less
    gwErrorCode
    Integer(11)
    The error reason code, if an error occurred on the gateway side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the specific error.
    Read more
    Read less
    gwErrorReason
    String(400)
    The error reason, if an error occurred on the gateway side.
    gwExtendedErrorCode
    Integer(11)
    The error reason code, if an error occurred on the bank side.
    When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
    Read more
    Read less
    version
    String(10)
    The version of the API.
    The current version of the API method. The current version is 1.
    paymentOption
    Class
    This class contains the card information inside the card sub-class and the userPaymentOptionId , as detailed in the following lines.
    paymentOption.userpaymentOptionId
    String(45)
    If initPayment was processed with userPaymentOptionId rather than having provided the card block, this field echos back the same userPaymentOptionId that was provided in the input.
    Read more
    Read less
    paymentOption.card
    Class
    bin, String(6) – The bin number of the credit card.
    last4Digits, String(4) – The last four digits of the credit card number.
    ccCardNumber, String(20) – The masked credit card number, for example: 4****1111.
    ccExpMonth, String(2) – The two-digit value representing the expiration month.
    ccExpYear, String(4) – The four-digit value representing the expiration year.
    ccTempToken, String(36) – A temporary card token to be used during the same session.
    threeD, Class – A class containing the 3D Secure information as detailed in the following line.
    Read more
    Read less
    paymentOption.card.threeD
    Class
    methodUrl, String(256) – The 3D Secure 2.0 URL.
    version, String(8) – The 3D Secure version.
    Possible values: 1 or 2.
    ver2supported Boolean (1) – The 3D Secure 2 support indication.
    serverTransID, String – 3DS Server Transaction ID to be used in the threeDSMethod in the merchant website.
    methodPayload, String – To be used in thethreeDSMethod in merchant website.
    Possible values: 0 (not supported) or 1 (supported).
    ver1supported Boolean (1) – The 3D Secure 1 support indication.
    Possible values: 0 (not supported) or 1 (supported).

    directoryServerId (String) – The 3DS directory server ID. Relevant only for the 3D Mobile SDK
    directoryServerPublicKey (String) – The 3DS directory public encryption key. Relevant only for the 3D Mobile SDK
    Read more
    Read less
    cardType
    Optional
    The type of card used in the transaction.
    Possible values:
    credit
    debit
    Read more
    Read less
    issuerCountry
    String(2)
    ISO code of the card issuer’s country.
    orderId
    String(20)
    The ID returned from the MerchantOrderID input parameter in update and payment methods. This parameter is returned to define which merchant order to update.
    Read more
    Read less
    clientRequestId
    String(20)
    The ID of the API request in merchant system.

    MPI Methods

    /authorize3d (API)

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

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    
    {  
       "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"
    }
    

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

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

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

    Input Parameters

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    The merchant ID provided by SafeCharge (part of the authentication credentials).
    merchantSiteId
    String(20)
    Required
    The merchant Site ID provided by SafeCharge (part of the authentication credentials).
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    See /getSessionToken for details.
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss. Needed for the “checksum” hashing calculation.
    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
    View hashing calculation for details or use the Checksum tool.
    Read more
    Read less
    currency
    String(3)
    Required
    The three-character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption
    Class
    Required
    This class represents the details about the payment method.
    Can have either card, alternativePaymentMethod, or userPaymentOptionId:
    card class has the following fields:
    cardNumber string(20) – The card number
    cardHolderName string(70) – The card holder name
    expirationMonth string(2) – Card expiration month
    expirationYear string4() – Card expiration year
    CVV string(4) – The CVV/CVC security code
    threeD (class) – Contains the required 3D Secure information. Refer to the threeD (in) section for details.
    -or-
    alternativePaymentMethod class – Contains the relevant field required for the specific payment method. Please refer to alternativePaymentMethod Class for details.
    -or-
    userPaymentOptionId – This is a field identifying a payment option that has already been used by the customer and is now requested for re-use. SafeCharge keeps payment option details from previous uses.
    Read more
    Read less
    relatedTransactionId
    String(19)
    Required
    Sets the transactionId returned from the preceding initPayment call.
    userTokenId
    String(255)
    Optional
    This field uniquely identifies your consumer/user in your system.
    Required if you wish to use the paymentOptionId field for future charging of this user without re-collecting the payment details (see User Payment Management for details.
    Read more
    Read less
    clientUniqueId
    String(45)
    Optional
    This ID identifies the transaction in your system. Optionally, you can pass this value to us and we will store it with the transaction record created in our system for your future reference.
    deviceDetails
    Class
    Only ipAddress
    deviceType (String, 10)
    deviceName (String, 255)
    deviceOS (String, 255)
    browser (String, 255)
    ipAddress (String, 15)

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

    These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)
    Read more
    Read less
    urlDetails
    Class
    Optional
    Although DMN responses can be configured per merchant site, it allows dynamically returning the DMN to the provided address per request.
    pendingUrl (string, 1000)
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    Risk rules and traffic management rules are usually built based on this field value.
    Read more
    Read less
    productId
    String(50)
    Optional
    A free text field used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this field value.
    Read more
    Read less
    customData
    String(255)
    Optional
    This parameter can be used to pass any type of information.
    If sent in request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    This is used by SafeCharge’s eCommerce Plugins (Magento, Demandware) and also SafeCharge API SDKs to send the Plugin/SDK name and version, so that support is able to identify from where the transaction arrived to the gateway through SafeCharge API.
    Read more
    Read less
    orderId
    String(45)
    Optional
    The order ID provided by SafeCharge.
    This parameter is passed to define which merchant order to update.
    clientRequestId
    String(255)
    Optional
    Use this advanced field to prevent idempotency. Use it to uniquely identify the request you are submitting. If our system receives two calls with the same clientRequestId, it refuses the second call as it will assume idempotency.
    subMerchant
    Class
    Conditional
    countryCode (String,2) – The payment facilitator’s sub-merchant’s two-character ISO country code.
    city (String, 20) – The payment facilitator’s sub-merchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    Read more
    Read less

    Output Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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.
    internalRequestId
    Long(20)
    SafeCharge’s internal unique request ID (used for reconciliation purpose, etc.).
    status
    String(20)
    The cashier status of merchant request.
    Possible statuses: SUCCESS or ERROR
    transactionStatus
    String(20)
    The gateway transaction status.
    paymentOption
    Class
    This class represents the data retrieved from the processed payment method. Can be either card, or in case of alternative payment method it shows the redirectUrl. In addition, the userPaymentOptionId field is retrieved as detailed below:
    redirectUrl String() – The redirect URL to follow in case of alternative payment method, which to process needs to be redirected to.
    -or-
    Card – Information about the card that was processed:
    bin (String) – The bin number representing the issuer.
    last4Digits (String) – The last four digits of the card number.
    ccCardNumber (String) – The credit card number in a mask, for example: ***1111
    ccExpMonth (String) – The expiration month.
    ccExpYear (String) – The expiration year.
    cvv2Reply (String) – The CVV2 (card verification value).
    avsCode (String) – The AVS (address verification) response.
    acquirerId (String) – The acquirer ID of the acquirer which processed the transaction.
    threeD (class) – Contains the required 3D Secure information. Refer to the threeD (out) section for details.
    -or-
    userPaymentOptionId – In addition to the above, this field represents the ID for the newly created payment option, which can be referenced in future requests.
    For full details, refer to Card-on-File.
    Read more
    Read less
    merchantDetails
    Class
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)

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

    isPartialApproval (String-True or False)
    amountInfo:
    requestedAmount (String)
    requestedCurrency (String)
    processedAmount (String)
    processedCurrency (String)
    Read more
    Read less
    transactionType
    String(45)
    The type of transaction: Sale or Auth.
    Sale – is a regular payment request
    Auth – Performs an authorisation only request. For details, see Auth and Settle.
    customData
    String(255)
    This parameter can be used to pass any type of information.
    If sent in the request, then it is passed on to the payments gateway, and is visible in SafeCharge’s back-office tool transaction reporting and is returned in response.
    Read more
    Read less
    fraudDetails
    Class
    finalDecision (String)
    score (decimal)
    recommendations (String)
    system {systemId(String),systemName (String),decision (String)
    rules [ruleId(String),ruleDescription (String)]}

    The 'score’ refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model.
    The ‘system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
    The ‘rule’ refers to the risk management system rules triggered by the transaction.
    The ‘decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter:
  • Accept – The risk management system accepts the transactions.
  • Reject – The risk management system rejects the transaction. The transaction not passed to bank for authorisation. The reasons are returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review, but still accepts the transaction.
  • Error – An error occurred during the risk management system operation. The gateway continues to process the transaction through the bank.
  • None – No risk analysis was performed. The gateway continues to process the transaction through the bank.
    The finalDecision refers to when deciding whether to accept or reject a transaction. The risk Management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a ‘Reject’ decision, the finalDecision accepts the transaction. If at least one of the rules leads to a ‘Reject’ decision, the finalDecision rejects the transaction.
    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less
    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.
    clientRequestId
    String(20)
    The ID of the API request in merchant system.

    /verify3d

    Example Request
    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    {
       "merchantSiteId":"51001",
       "merchantId":"5288945245833474115",
       "sessionToken":" 9e07802d-5126-4b02-b4b3-ef09dfb94219",
       "relatedTransactionId":"2110000000000644998",
       "currency":"USD",
       "amount":"0.1",
       "paymentOption":{
          "card":{
             "cardNumber":"5413330056003511",
             "cardHolderName":"john Smith",
             "expirationMonth":"12",
             "expirationYear":"25",
             "CVV":"123"
          }
       },
       "billingAddress":{
          "country":"DE"
       }
    }
    

    Example Response

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

    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

    PARAMETER DESCRIPTION
    merchantId
    String(20)
    Required
    The merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Required
    The merchant Site ID provided by SafeCharge.
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    currency
    String(3)
    Required
    The three-character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount.
    This amount must be identical to the amount listed in the dynamic3D.
    paymentOption
    Class
    Required
    This class represents the details about the payment method.
    Can have either card, alternativePaymentMethod, or userPaymentOptionId:
    card class has the following fields:
    cardNumber string(20) – The card number
    cardHolderName, string(70) – The card holder name
    expirationMonth, string(2) – Card expiration month
    expirationYear – string(4)– Card expiration year
    CVV, string(4) – The CVV/CVC security code
    threeD.paResponse (class) – Only relevant if 3D Secure is v1. To verify, you need to provide the paResponse retrieved from the termUrl. See the 3D Secure Guide for a full explanation. For 3D Secure v2, no threeD field needs to be submitted.
    -or-
    alternativePaymentMethod class – Contains the relevant field required for the specific payment method. Please refer to alternativePaymentMethod Class for details.
    -or-
    userPaymentOptionId – This is a field identifying a payment option that has already been used by the customer and now it is requested for re-use. SafeCharge keeps payment option details from a previous use.
    Read more
    Read less
    relatedTransactionId
    String(19)
    Required
    The transaction ID of the of the call to /authorize3d.
    billingAddress
    Class
    Only country
    The billing address related to a user payment option. Since an order can contain only one payment option, the billing address is part of the order parameters.
    firstName (String, 30)
    lastName (String, 40)
    address (String, 60)
    address2 (String, 60)
    phone (String, 18)
    zip (String, 10)
    city (String, 30)
    country (two-letter ISO country code)(String, 2), must be entered in Uppercase
    state (two-letter ISO state code)(String, 2)
    email (String, 100)
    county (String, 255)

    These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.
    Read more
    Read less
    subMerchant
    Class
    Conditional
    countryCode (String,2) – The payment facilitator’s sub-merchant’s two-character ISO country code.
    city (String, 20) – The payment facilitator’s sub-merchant’s city name.
    id (String, 15) – This field represents the ID of internal merchants and will be forwarded to Mastercard as “SubMerchantId”.
    Read more
    Read less

    Output Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    The session identifier returned by /getSessionToken.
    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.
    internalRequestId
    Long(20)
    SafeCharge’s internal unique request id (used for reconciliation purpose, etc.).
    status
    String(20)
    The cashier status of merchant request.
    Possible statuses: SUCCESS or ERROR
    transactionStatus
    String(20)
    The gateway transaction status.
    paymentOption
    Class
    This class represents the details about the payment method. This can be one of two options:
    card – Representing credit/debit card.
    -or-
    alternativePaymentMethod – Representing an alternative payment method.

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

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

    The 'score’ refers to a number between 0 and 1 that indicates the probability of a transaction becoming fraudulent, which is calculated using a risk machine learning model.
    The ‘system’ refers to which risk management system provided the fraud information. The provider can be SafeCharge (systemId=1) or an external provider.
    The ‘rule’ refers to the risk management system rules triggered by the transaction.
    The ‘decision’ refers to the risk management system decisions regarding the rules that were triggered by the transaction. There are five possible values for the decision parameter:
  • Accept – The risk management system accepts the transactions.
  • Reject – The risk management system rejects the transaction. The transaction not passed to bank for authorisation. The reasons are returned in ruleDescription parameter.
  • Review – The risk management system flags a transaction for review, but still accepts the transaction.
  • Error – An error occurred during the risk management system operation. The gateway continues to process the transaction through the bank.
  • None – No risk analysis was performed. The gateway continues to process the transaction through the bank.
    The finalDecision refers to when deciding whether to accept or reject a transaction. The risk Management system bases its finalDecision on individual decisions made regarding rules triggered. If none of the rules leads to a ‘Reject’ decision, the finalDecision accepts the transaction. If at least one of the rules leads to a ‘Reject’ decision, the finalDecision rejects the transaction.
    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less
    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.
    clientRequestId
    String(20)
    The ID of the API request in merchant system.

    Class Objects

    threeD Input Class

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

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

    Parameter Description
    notificationURL
    String
    3D 2.0
    The notification URL for redirecting the browser after the challenge completion, which receives the CRes message.
    merchantURL
    String
    3D 2.0
    The merchant website fully qualified URL.
    version
    String
    3D 2.0
    The number of the 3DS version used, as indicated by the value returned from /initpayment(API)
    methodCompletionInd
    String
    3D 2.0
    Indicates whether the 3DS method was successfully completed.
    Y – Successfully completed
    N – Did not successfully complete
    U – Unavailable (3DS Method URL was not present)
    Read more
    Read less
    platformType
    String
    3D 2.0
    The device channel.
    01 – App-based (only for SDK implementation, not in the scope of this document)
    02 – Browser
    convertNonEnrolled
    String
    Optional
    Set this field to automatically convert the request for payment in case of 3DS 1.0 failure to authenticate. The transaction in this case is non-3D Secure.
    paResponse
    String
    Conditional
    The payment authorisation response returned by the card issuer/bank. Relevant only to the second payment call and only if 3D 1.0 authentication was performed.
    externalMpi
    class
    External MPI
    Eci (String,2) – The Electronic Commerce Indicator as received from the MPI
    Cavv(String50) – The card authentication verification value as received from the MPI.
    threeDProtocolVersion (String, 2) – Specifies the 3D Secure version (1 or 2)
    Xid (string, 50) – The transaction ID received from the MPI for 3D v1.
    dsTransID (string, 36) – The transaction ID received from the MPI for 3D v2.

    You can also use challengePreference and externalRiskScore to increase the chances for 3DSv2 exemption. For details, please scroll down and view the descriptions of these fields.
    Read more
    Read less
    browserDetails
    Class
    3D 2.0
    acceptHeader (string) - Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.
    Value accepted:
    If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
    ip (string) - IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
    Value accepted:
    • IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 to 255. Example IPv4 address: 1.12.123.255
    • IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets. The groups are separated by colons (:). Example IPv6 address: 2011:0db8:85a3:0101:0101:8a2e:0370:7334
    javaEnabled (string) - Boolean that represents the ability of the cardholder browser to execute Java.
    Value is returned from the navigator.javaEnabled property.
    Values accepted:
    • Y=TRUE
    • N=FALSE
    javaScriptEnabled (string) - Determines whether the browser is JavaScript enabled (from navigator.javaEnabled property).
    Values accepted:
    • Y=TRUE
    • N=FALSE
    language (string) - Value representing the browser language as defined in IETF BCP47.
    Returned from navigator.language property.
    colorDepth (string) - Value representing the bit depth of the colour palette for displaying images, in bits per pixel.
    Obtained from Cardholder browser using the screen.colorDepth property.
    Values accepted:
    • 1 = 1 bit
    • 4 = 4 bits
    • 8 = 8 bits
    • 15 = 15 bits
    • 16 = 16 bits
    • 24 = 24 bits
    • 32 = 32 bits
    • 48 = 48 bits
    screenHeight (string) - Total height of the Cardholder’s screen in pixels.
    Value is returned from the screen.height property.
    screenWidth (string) - Total width of the cardholder’s screen in pixels.
    Value is returned from the screen.width property.
    timeZone (string) - Time difference between UTC time and the Cardholder browser local time, in minutes.
    Value accepted:
    Value is returned from the getTimezoneOffset() method.
    userAgent (string) - Exact content of the HTTP user-agent header.
    Value accepted:
    If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
    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 v2AdditionalParams table below.
    sdk
    Class
    3D 2.0 SDK
    This class is mandatory for 3D Secure 2.0 for transactions originating from a mobile device. It contains the following 3D mobile relevant information:

    appSdkInterface – String(2) – Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.
    appSdkUIType – String(2) – Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK.
    appID – String(36) – SDK App ID - guid
    encData – String(64000) – SDK Encrypted Data
    ephemPubKey – String(256) – SDK Ephemeral Public Key (Qc)
    maxTimeout –String(2) – SDK Maximum Timeout
    referenceNumber – String(32) – SDK Reference Number
    transID – String(36) – SDK Transaction ID – guide
    Read more
    Read less
    challengePreference
    String(2)
    Optional
    If you wish to use our MPI and request an exemption, you can provide this field.
    This field can also be used in conjunction with the External MPI block.
    • 01 = No preference
    • 02 = No challenge requested
    • 03 = Challenge requested: 3DS Requestor Preference
    • 04 = Challenge requested: Mandate
    • 05–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
    • 80-99 = Reserved for DS use
    Read more
    Read less
    externalRiskScore
    String(3)
    To increase your chances for exemption, you can provide the third-party risk engine score you are using, specified in this field.
    This field can be used also in conjunction with the External MPI block.
    Valid values are 0–100 where 0 is lowest risk and 100 is highest risk
    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 isRebilling = 0 (format: YYYYMMDD)
    rebillFrequency
    String
    Optional
    Recurring Frequency - Required if isRebilling = 0 in number of days.
    challengeWindowSize
    String
    Optional
    The dimensions of the challenge window.
    01 – 250 x 4000
    02 – 390 x 4000
    03 – 500 x 6000
    04 – 600 x 4000
    05 – Full screen
    Read more
    Read less

    threeD Output Class

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

    The output table is separate into 2 parts:

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

    PARAMETER DESCRIPTION
    acsUrl
    String
    URL or endpoint used to redirect the consumer to the card issuer/bank’s 3D Secure verification page.
    acsChallengeMandate
    String(1)
    The 3D Secure 2.0 challenge required indication.
    Possible values:
    N – not required
    Y – required (only in case of 3D Secure 2.0)
    Read more
    Read less
    cReq
    String
    The Base64 encoded cReq relevant for the 3D Secure 2.0.
    acsUrl is also sent as a separate field (only in case of 3D Secure 2.0)
    paRequest
    String
    The 3D Secure request data for the card issuer/bank (only in case of 3D 1.0)
    threeDFlow
    String
    Indicates which 3D flow is taking place:
  • If the gateway response parameter for threeDFlow = 1, the transaction is converted from Sale3D to Auth3D after passing the gateway rule engine. (paRequest and acsUrl are returned and the merchant needs to redirect to issuer and call payment3D method afterwards).
  • If the gateway response parameter for threeDFlow= 0, the transaction converted from Sale3D to Sale or Auth depending on the configured merchant mode of operation after passing the gateway rule engine. (paRequest and acsUrl are NOT returned and the merchant does NOT need to redirect to issuer or call payment3Dmethod later on).
  • Read more
    Read less
    externalTransactionId
    String(20)
    The transaction ID of the transaction in the event that an external service is used.
    transactionId
    String(20)
    The gateway transaction ID.
    threeDReasonId
    String
    Reason ID for a failed 3DS authorisation as received from the issuer.
    threeDReason
    String
    Reason description for a failed 3DS authorisation as received from the issuer.
    challengeCancelReasonId
    String
    Reason ID for a cancelled 3DS authorisation as received from the issuer.
    ChallengeCancelReason
    ^String
    isLiabilityOnIssuer
    String
    Indicates if there is 3D secure liability shift.
    isExemptionRequestInAuthentication
    String
    Indicates if an exemption was requested during authorisation.
    challengePreferenceReason
    String
    If a challenge is requested, this fields provides the reason for it.

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

    PARAMETER DESCRIPTION
    authenticationStatus
    String(1)
    This field is returned only from the SECOND payment.
    Indicates whether a transaction qualifies as an authenticated transaction or as an account verification.
    Possible values:
    Y = Authentication Verification Successful.
    N = Not Authenticated/Account Not Verified; Transaction denied.
    U = Authentication/Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq.
    A = Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided.
    C = Challenge Required; Additional authentication is required using the CReq/CRes.
    D = Challenge Required; Decoupled Authentication confirmed.
    R = Authentication/Account Verification Rejected; Issuer is rejecting
    Note: The Final CRes message can contain only a value of Y or N.
    Note: If the 3DS Requestor Challenge Indicator = 06 (no challenge requested; data share only), then a Transaction Status of C is not valid.
    Read more
    Read less
    whiteListStatus
    String
    Did this consumer define this merchant as whitelist or not. If the consumer defined the merchant, then this is the reason why the challenge did not happen.
    Possible values:
    Y = 3DS Requestor is whitelisted by cardholder
    N = 3DS Requestor is not whitelisted by cardholder
    E = Not eligible as determined by issuer
    P = Pending confirmation by cardholder
    R = Cardholder rejected
    U = Whitelist status unknown, unavailable, or does not apply
    Read more
    Read less
    cavv
    String(28)
    A cryptogram created by the 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.
    Read more
    Read less
    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

    externalToken class

    This class is set under the card class and is to be used if you wish to submit a payment with an external token provider as the card input.

    PARAMETER DESCRIPTION
    externalTokenProvider
    String(45)
    Optional
    The name and ID of the external token provider: ApplePay for ApplePay.
    mobileToken
    String(5000)
    Optional
    The token received from Apple during Dynamic Server to Server JS Button Solution.
    To work with external token, provider special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
    Read more
    Read less

    alternativePaymentMethod Class

    This class passes to SafeCharge the information of the APM that the merchant wishes to use to process with SafeCharge.

    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) Excel file below.
    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) Excel file below.
    The third column in the Excel file details the relevant APM input fields per each APM.


    The following Excel table presents the account identifiers that are associated with Pay In APMs.

     

    Download the APM Account Identifiers (Payin) table by clicking 'Export as CSV’.


    In addition, the following Excel table presents the unique SafeCharge names that are associated with Pay In APMs.

     

    Download the APM Unique SafeCharge Names (Payin) by clicking 'Export as CSV’.

    Deprecated Methods

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

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

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



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

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

    /dynamic3D

    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
    
    {
        "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
        "orderId":"39272",
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "userTokenId": "487106",
        "clientUniqueId": "12345",
        "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"
    }
    

    Example Response

    COPIED
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    
    {
        "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
        "orderId":"39272",
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "userTokenId": "487106",
        "clientUniqueId": "12345",
        "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":""
                }]
            }
        }
    }
    

    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

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    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.
    Read more
    Read less
    isDynamic3D
    String(1)
    Required
    Always send isDynamic3D = 1.
    dynamic3DMode
    String
    Optional
    If the merchant wants to force the transaction to go to 3D, send dynamic3DMode = ON.
    isRebilling
    Integer(2)
    Optional
    This indicates whether this is a regular transaction or a recurring/rebilling transaction.
    Possible values:
    0 – This is a regular transaction.
    1 – This is a recurring/rebilling transaction.
    Rebilling can be performed using userPaymentOptionId or cardData. If done using cardData, then it is highly recommended to send its relatedTransactionId as well.

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

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

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

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

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

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

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

    These parameters can be defined as mandatory or non-mandatory as needed by SafeCharge’s Integration Team.

    Note that the country parameter is always mandatory.

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

    merchantName - The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    merchantPhone - The merchant contact information, as is displayed for the transaction on the consumer’s card statement. It can also be an email address.
    Read more
    Read less
    merchantDetails
    Class
    Optional
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)

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

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

    CVV can be mandatory or non-mandatory per configuration.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    This parameter shows whether or not stored tokenized card data is sent to execute the transaction.
    Possible values:
    0 – The card data was entered for the first time, and, upon completion of the transaction, is tokenized and stored for future transactions.
    1 – Previously tokenized and stored card data was used to perform the transaction.
    This parameter is only applicable to merchants that store tokenized card data and is mandatory when the cardData>cardNumber parameter is populated and sent. Merchants that do not store card data or that are using SafeCharge’s tokenization feature should not send this parameter.
    Read more
    Read less
    customSiteName
    String(50)
    Optional
    The merchant’s site name. This is useful for merchants operating many websites that are distinguished only by name.
    productId
    String(50)
    Optional
    A free text field used to identify the product/service sold.
    If this parameter is not sent or is sent with empty value, then it contains the concatenation of all item names up until parameter maximum length.
    customData
    String(255)
    Optional
    This parameter can be used to pass any type of information.
    If sent in request, then it is passed on to the payments gateway, is visible in SafeCharge’s back-office tool transaction reporting, and is returned in response.
    Read more
    Read less
    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: Apple Pay.
    For Apple Pay, the following values must be passed:
    externalTokenProvider – “ApplePay”,
    mobileToken – The token received from Apple during Dynamic Server to Server JS Button Solution.
    To work with external token, providers special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
    Read more
    Read less
    webMasterId
    String(255)
    Optional
    This is an affiliate parameter that the merchant can send.
    timeStamp
    String(14)
    Required
    The local time when the method call is performed in the format: YYYYMMDDHHmmss
    checksum
    String(256)
    Required
    UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.
    orderId
    String(45)
    Optional
    The order ID provided by SafeCharge.
    clientRequestId
    String(255)
    Required
    ID of the API request in the merchant’s system. This value must be unique.
    This must be sent to perform future actions, such as reconciliation, identifying the transaction in the event of any issues, etc.
    Read more
    Read less

    Output Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    Session identifier returned by /getSessionToken.
    merchantId
    String(20)
    Merchant ID provided by SafeCharge.
    merchantSiteId
    String(20)
    Merchant Site ID provided by SafeCharge.
    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.
    internalRequestId
    String(20)
    SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
    threeDFlow
    String
    If the value sent in isDynamic3D input parameter equals 1 (i.e. 3D Secure was configured to be managed by SafeCharge’s Rules Engine) then this parameter indicates whether the performed transaction was auth3D (1), or whether the performed transaction was auth/sale(0). For the merchant required actions once the response is received, see Possible Scenarios Table.
    Read more
    Read less
    status
    String(20)
    The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
    transactionStatus
    String(20)
    The gateway transaction status.
    Possible values: APPROVED, DECLINED, ERROR.
    merchantDetails
    Class
    customField1 (String, 255, not mandatory)
    customField2 (String, 255, not mandatory)
    customField3 (String, 255, not mandatory)
    customField4 (String, 255, not mandatory)
    customField5 (String, 255, not mandatory)
    customField6 (String, 255, not mandatory)
    customField7 (String, 255, not mandatory)
    customField8 (String, 255, not mandatory)
    customField9 (String, 255, not mandatory)
    customField10 (String, 255, not mandatory)
    customField11 (String, 255, not mandatory)
    customField12 (String, 255, not mandatory)
    customField13 (String, 255, not mandatory)
    customField14 (String, 255, not mandatory)
    customField15 (String, 255, not mandatory)

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

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

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

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

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

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

    To receive this information in response special configurations are required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
  • Read more
    Read less
    orderId
    String(20)
    The order ID provided by SafeCharge.
    clientRequestId
    String(20)
    ID of the API request in the merchant’s system.

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

    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
    
    {
        "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
        "orderId":"39272",
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "userTokenId": "487106",
        "clientUniqueId": "12345",
        "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"
    }
    

    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
    
    {
        "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
        "orderId":"39272",
        "merchantId": "427583496191624621",
        "merchantSiteId": "142033",
        "userTokenId": "487106",
        "clientUniqueId": "12345",
        "internalRequestId": "866",
        "status": "SUCCESS",
        "transactionStatus": "APPROVED",
        "merchantDetails": {
            "customField1": "",
            "customField2": "",
            "customField3": "",
            "customField4": "",
            "customField5": "",
            "customField6": "",
            "customField7": "",
            "customField8": "",
            "customField9": "",
            "customField10": "",
            "customField11": "",
            "customField12": "",
            "customField13": "",
            "customField14": "",
            "customField15": ""
        },
        "errCode": "0",
        "reason": "",
        "gwErrorCode": "0",
        "gwExtendedErrorCode": "0",
        "version": "1.0",
        "userPaymentOptionId": "12442",
        "externalTransactionId": "2345346589",
        "transactionId": "1000030724",
        "authCode": "08AF6E",
        "eci": "",
        "threeDReason": "",
        "externalToken":{
            "externalToken_blockedCard":"",
            "externalToken_cardAcquirerId":"",
            "externalToken_cardAcquirerName":"",
            "externalToken_cardBin":"",
            "externalToken_cardBrandId":"",
            "externalToken_cardBrandName":"",
            "externalToken_cardExpiration":"",
            "externalToken_cardLength":"",
            "externalToken_cardMask":"",
            "externalToken_cardName":"",
            "externalToken_cardTypeId":"",
            "externalToken_cardTypeName":"",
            "externalToken_clubName":"",
            "externalToken_creditCompanyId":"",
            "externalToken_creditCompanyName":"",
            "externalToken_extendedCardType":"",
            "externalToken_Indication":"",
            "externalToken_tokenValue":"",
            "externalToken_tokenProvider":""
        },
        "partialApprovalDetails":{
            "isPartialApproval": "",
            "amountInfo":{
                "requestedAmount": "",
                "requestedCurrency": "",
                "processedAmount": "",
                "processedCurrency": ""
            }
        },
        "cvv2Reply":"",
        "avsCode":"",
        "transactionType":"",
        "customData":"",
        "fraudDetails":{
            "finalDecision":"",
            "recommendations": "",
            "system":{
                "systemId":"1",
                "systemName":"SafeCharge",
                "decision":"",
                "rules":[{
                   "ruleId": "",
                   "ruleDescription":""
                }]
            }
        }
    }
    

    This final stage performs the actual payment transaction.

    Input Parameters

    PARAMETER DESCRIPTION
    sessionToken
    String(36)
    Required
    Session identifier returned by /getSessionToken.
    It is required to provide the same sessionToken value sent to dynamic3D method that was 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.
    Read more
    Read less
    transactionType
    String(45)
    Required
    The type of transaction: Sale or Auth.
    Sale – is a regular payment request
    Auth – Performs an authorisation only request. For details, see Auth and Settle.
    isPartialApproval
    String(1)
    Optional
    This describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer’s lack of funds from the desired payment method.
    Partial approval is supported only by SafeCharge acquiring.
    For partial approval to be available for the merchant it should be configured by SafeCharge’s Integration Team.
    Possible values:
    1 – allow partial approval
    0 – not allow partial approval
    Read more
    Read less
    currency
    String(3)
    Required
    The three-character ISO currency code.
    amount
    Double(12)
    Required
    The transaction amount. This amount must be identical to the amount listed in the dynamic3D.
    amountDetails
    Class
    Required
    totalShipping(String)
    totalHandling(String)
    totalDiscount(String)
    totalTax(String)

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

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

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

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

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

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

    These parameters can be defined as mandatory or non-mandatory per need by SafeCharge Integration Team.

    Note that the country parameter is always mandatory.

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

    merchantName - The merchant name, as is displayed for the transaction on the consumer’s card statement.
    For payment facilitator only, the maximum length of the description is 22, maintaining the following structure:
    “XXX"<merchant name>”
    “XXX” must be 3 characters and identifies the payment facilitator.
    “<merchant name>” must be maximum of 18 characters.

    merchantPhone - The merchant contact information, as is displayed for the transaction