Navbar
JSON Node.JS java php C#

Introduction

Welcome

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

Overview

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

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

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

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

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

Quick Start

This API allows you to perform payments quickly with as little as two API calls:
getSessionToken and dynamic3D using dynamic3D parameter with value OFF.



Glossary

Consumer
The individual purchasing a product or service from the merchant.
Merchant
SafeCharge’s customer that conducts transactions with consumers.
Transaction
An agreement between the consumer and the merchant to perform a request to the payments gateway.
UPO
The consumer’s payment method. A UPO ID is generated by SafeCharge for each payment method that a consumer defines when processing a transaction. (User Payment Option)
APM
Any payment method that is not a credit card, such as PayPal, Neteller, etc. (Alternative Payment Method)
Auth
(Authorization) A request made by the merchant to the Gateway to check the availability of a required amount of funds for a specific credit card and reserve it for a subsequent Settle. If the authorization is approved, the issuer bank returns an authorization code and the amount of the authorization. No funds are collected during an authorization. Authorizations are requests to verify that sufficient funds are available and reserved for when the transaction is settled.
Sale
A request combining both the Auth and Settle transactions that instructs the Gateway to perform both actions, one after the other: query the bank for authorization and, upon approval, immediately settle the transaction.
Credit (Refund or Payout)
There are two types of credits: Refund, a request instructing the Gateway to refund a previously settled transaction to the consumer. Payout, transferring funds from the merchant to the consumer, regardless of any previous transaction.
Settle
A request instructing the Gateway to transfer funds, previously reserved in an Auth transaction, from the customer’s bank account to the merchant’s bank account. This transaction is always preceded by an Auth Transaction.
Void
A request initiated by the merchant, SafeCharge’s Technical Support, or SafeCharge’s Risk department, instructing the Gateway to cancel (delete) a transaction before it is transmitted to the acquirer bank.



API Methods List

The API’s methods offer a variety of services.

These methods enable the merchant to manage payment transactions, perform a payment using a credit card or a credit card token, UPO, APM, 3D secure payment, etc., as well as manage orders, manage previously performed transactions (settle, refund, void, etc.), manage users and their payments, UPOs and more.
This list does not include the withdrawal methods appears at the withdrawals documentation section.

The messages that the merchant’s application sends are called request messages and the messages that the gateway returns are called response messages. Request messages include the input parameters of the method, whereas the response messages return the output parameters of the method. The basic exchange of these request and response messages typically requires the interaction of two components:

Merchant Application: This is the merchant company’s application. It may be a consumer-facing application, such as a web site, online application, etc.

API Services: This is SafeCharge’s web service that interacts with the merchant’s application to manage payments, users, user payment options, etc.

API Methods

METHOD DESCRIPTION
This method generates the session token that will be in use in all future API calls from the consumer for authentication, security, authorization (permissions) etc.).
This method allows the merchant to open an order. Orders can be updated by the merchant before they are sent to the payments gateway. This method also generates an order ID, which can be used in most future API calls.
This method enables the updating of an order previously opened by a merchant.
This method allows the return of specific order details based on order ID.
This method enables the authorization of credit cards via 3D secure payment flow. This method is used to redirect to the card issuer site. The payment 3D method must be called afterwards.
This method enables the credit card payment via 3D secure payment flow. The dynamic3D method must be called before.
This method enables the creation of a temporary credit card token according to the card data (number, etc.)
This method allows to perform payment using credit card.
This is possible via regular payment or reoccurring payment/re-bill.
This method enables payment using an alternative payment method (not a credit card).
This method allows the return of the payment methods details that are available for a specific merchant. It will be used by the merchant mostly in order to display the available payment methods in its payment page.
This method is used for creating a subscription for consumers that wish to conduct future recurring transactions based on previous successful transactions.
This method is used for canceling existing subscriptions.
This method is used for receiving a list of all existing subscriptions.
The results can be filtered by the input parameters.
This method is used for returning the available subscriptions plans for the merchant.
Creating and updating subscription plans is possible using CPanel, SafeCharge’s back-office tool. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com
Settle an already authorized transaction (when working in a two-phase auth - settle manner only).
Refund a previously settled transaction.
Void a previously performed authorization transaction.
This method allows to perform payout (transfer funds from merchant to consumer, with no relation to previous transaction).
Enables performing the entire KYC process online.
For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
As part of the KYC process, customers are required to send personal documents in order to verify their identity. This method return a URL which enables the uploading of these documents easily to help complete the KYC process quickly and securely.
For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
Creates a user.
Updates a user’s details.
Retrieves the details for a specific user.
Adds a credit card for a specific user when the credit card token is available.
Adds a credit card for a specific user when the credit card token is available.
Adds a credit card for a specific user when the credit card temporary token is available.
Adds an alternative payment method (APM) to a user’s list of UPOs.
Returns a list of a user’s payment options.
Deletes a specific payment option from a user’s list of UPOs.
Edits the credit card details for a specific user.
Edits the APM details for a specific user.
Suspends a user payment option for a specific user.
Enables a suspended user payment option for a user.
Although this is a server to server API, if a merchant wouldn’t like to build its own payment page UI but use SafeCharge hosted payment page, then this method allows retrieval of a redirect URL to a SafeCharge hosted payment page UI.
For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.

Server SDK

Server SDK (Java)

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

Server SDK (PHP)

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

Client SDK

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

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

Credit Card Tokenization (Native iOS & Android):
JavaScript and UI are offered for the use of mobile native applications. For more information about this API flow, see Mobile SDK Flow. iOS SDK is available at https://github.com/SafeChargeInternational/safecharge-ios. Android SDK is available at:https://github.com/SafeChargeInternational/safecharge_sdk_android .



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

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

API Flows

3D Secure Payment Flow

In order to implement this type of payment, a certain flow of method calls from the merchant must be followed. Below are the two available options:


getSessionToken
Mandatory
dynamic3D
Mandatory
Merchant redirect to card issuer page
Card issuer redirect back to merchant page
Optional
In case a valid acsUrl returned in dynamic3D method response.
payment3D
Optional.
In case threeDFlow=1 returned by dynamic3D method response.
OR

getSessionToken
Mandatory
openOrder
Mandatory
updateOrder
Optional
getOrderDetails
Optional
dynamic3D
Mandatory
Merchant redirect to card issuer page
Card issuer redirect back to merchant page
Optional
In case a valid acsUrl returned in dynamic3D method response.
payment3D
Optional.
In case threeDFlow=1 returned by dynamic3D method response.



Paymentusing3dsecureflow

Card Tokenization Payment (Web) Flow

In order to implement this type of payment, a certain flow of method calls from the merchant must be followed.


The merchant initializes a session between its client to its server.
This is the merchant’s responsibility.
getSessionToken
Mandatory
cardTokenization
Mandatory
(using client SDK for card tokenization, the merchant calls it from its client side using SafeCharge’s provided JavaScript: safecharge.js.)
The merchant passes the provided card token from its client side to its server side.
This is the merchant’s responsibility.
createUser
Optional
If user does not exist yet, need to create it in order to later use it in addUPOCreditCardByTempToken.
addUPOCreditCardByTempToken
Optional
paymentCC
Mandatory



Cardtokenizationpaymentwebflow

Card Tokenization Payment (Mobile) Flow

In order to implement this type of payment, a certain flow of method calls from the merchant must be followed.


The merchant initializes a session between its client to its server.
This is the merchant’s responsibility.
getSessionToken
Mandatory
cardTokenization
Mandatory (using cardTokenization method)
The merchant passes the provided card token from its client side to its server side.
This is the merchant’s responsibility.
createUser
Optional
If user does not exist yet, need to create it in order to later use it in addUPOCreditCardByTempToken.
addUPOCreditCardByTempToken
Optional
paymentCC
Mandatory



Cardtokenizationpaymentmobileflow

Card Tokenization Payment (Mobile SDK) Flow

In order to implement this type of payment, a certain flow of method calls from the merchant must be followed.


The merchant initializes a session between its client to its server.
This is the merchant’s responsibility.
getSessionToken
Mandatory
cardTokenization
Mandatory (using Mobile SDK for card tokenization)
The merchant passes the provided card token from its client side to its server side.
This is the merchant’s responsibility.
createUser
Optional
If user does not exist yet, need to create it in order to later use it in addUPOCreditCardByTempToken.
addUPOCreditCardByTempToken
Optional
paymentCC
Mandatory



Cardtokenizationpaymentmobilesdkflow

Credit Card Payment Flow

In order to implement this type of payment, a certain flow of method calls from the merchant must be followed. Below are the two available options:


getSessionToken
Mandatory
paymentCC
Mandatory
OR

getSessionToken
Mandatory
openOrder
Mandatory
updateOrder
Optional
getOrderDetails
Optional
paymentCC
Mandatory



Paymentusingcreditcardflow

Alternative Payment Method (APM) Payment Flow

In order to implement this type of payment, a certain flow of method calls from the merchant must be followed. Below are the two available options:


getSessionToken
Mandatory
paymentAPM
Mandatory
OR

getSessionToken
Mandatory
getMerchantPaymentMethods
Metedata service to render payment page on merchant side with available payment methods.
openOrder
Mandatory
updateOrder
Optional
getOrderDetails
Optional
paymentAPM
Mandatory



Paymentusingapmflow

Data Integrity (using checksum)

All API methods include a data integrity mechanism, which ensures that the data sent is identical to the data received.

This is implemented using a parameter known as checksum, which is built from the parameters sent along with the addition of the Merchant Secret Key provided by SafeCharge.

The checksum is encrypted according to a predefined encryption method and agreed upon by the sender and receiver.



How To Work With Checksum

The checksum is a hash of parameters specific for each request and is used by SafeCharge for data integrity and also in order to authenticate that the request was actually sent by the merchant. The checksum authenticates the merchant’s request as they attach their secret key provided by SafeCharge.

In the request, concatenate the following parameters in the exact order listed.

Some methods checksums consist of all of the method’s input parameters, in the order listed, along with the Merchant Secret Key.

Other methods checksums consist of few of the method’s input parameters, in the order listed, along with the Merchant Secret Key.

The checksum must be a single string, without spaces, with the values of the parameters, except for the checksum itself.

SHA256 encryption must be used on the result string of the concatenation. To prevent errors that may occur while transferring requests, create and include a SHA256 (hash algorithm set per account) checksum into the request. The checksum is unique to each transaction as it is calculated according to specific details for each transaction.

To generate checksums for each transaction, a SHA256 calculator must be integrated into the merchant’s web application to allow the automatic calculation of the checksum when creating requests.

Use encoding passed to SafeCharge from the merchant’s site to create the SHA256 encryption. The default encoding is UTF-8, unless the encoding input parameter specifies otherwise.

SafeCharge decodes the checksum and compares the received parameters to the decoded checksum received and the Merchant Secret Key.

Once a response is received, the checksum should be decoded and compared to the result with the parameters received and the Merchant Secret Key.

Example for calculating a checksum:
The merchant is given the following:
merchantId: 123
merchantSiteId: 456
clientRequestId: 789
amount: 100
currency: USD
timeStamp: 20160520132234
secret key: AJHFH9349JASFJHADJ9834


After concatenating the above values, they appear as the following string: 123456789100USD20160520132234AJHFH9349JASFJHADJ9834

The calculated checksum after encryption is: eae7a36aedef4b901ca2019d86d2b816562f10c4bf24fc6142402aacd6fd9d3d

Notifications (using DMN)

Handling Direct Merchant Notifications (DMN’s)

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

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

Integrating DMN’s

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

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

The SafeCharge server calls back by using the HTTPS GET/HTTPS POST request to this URL. The request includes all relevant data for the HTTPS GET/HTTPS POST parameters.

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

SafeCharge sends DMNs from the following IP addresses:

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

Live: SafeCharge has several IP addresses for live DMN servers. A listener should be prepared to receive messages from the following IP addresses, in the event that one server is down: 194.247.166.0–194.247.167.255 / 195.28.166.0–195.28.166.255 / 87.120.10.0 - 87.120.10.255

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

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

Receiving DMN’s

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

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

APM’s and DMN’s

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

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

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

Authenticating a DMN Response Checksum

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

The HTTPS parameter containing the DMN checksum is named advanceResponseChecksum.

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

To Authenticate a DMN Response Checksum:

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

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

Example Of DMN Response Checksum:

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

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

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

The calculated checksum is: 8b7033116c2868405c8efbf23bf0c112f10fccce81ec241dea583a0b26950d3e

DMN Parameters

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

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

Errors

Status and Error Indications in Responses

The payment process consists of three stages:

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

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

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

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

API Response Codes

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



Gateway Response Codes

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

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



Gateway Filter Error Codes

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

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

Gateway Decline Reasons

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

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

Testing

Testing Overview

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

Test Card Numbers

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

Valid Test Cards

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



Invalid Test Cards

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

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

Test APM Credentials

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

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

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

Supported Payment Methods

APM Unique SafeCharge Names

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



APM Account Identifiers

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



APM Unique SafeCharge Names (Payin)

Credit Cardcc_cardALLAED, ARS, AUD, AZN, BGN, BHD, BND, BRL, BYN, BYR, CAD, CHF, CLP, CNH, CNY, COP, CRC, CZK, DKK, DZD, EEK, EGP, EUR, GBP, GEL, HKD, HRK, HUF, IDR, INR, IQD, ISK, JOD, KGS, KRW, KWD, KZT, LBP, LTL, LVL, MAD, MDL, MXN, MYR, NIS, NOK, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, SKK, THB, TND, TRY, TWD, UAH, USD, UYU, VEF, VND, YEN, YER, ZAR
Netellerapmgw_NetellerAL, DZ, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CX, CC, CO, KM, CG, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UY, UZ, VU, VE, VN, VG, WF, EH, YE, ZM, ZW, AF, ME, RS, GG, IM, JE, PSAUD, BGN, BRL, CAD, DKK, EUR, GBP, HUF, INR, JPY, LTL, LVL, MXN, NOK, PLN, RON, RUB, SEK, USD, ZAR
PayPalapmgw_expresscheckoutAL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, AX, GG, IM, JE, GSAUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RUB, SEK, SGD, TWD, USD, NIS
Skrillapmgw_MoneyBookersAL, DZ, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, RS, AX, GG, IM, JE, GS, PSAED, AUD, BGN, CAD, CHF, CZK, DKK, EEK, EUR, GBP, HKD, HUF, INR, JPY, NOK, NZD, PLN, RON, SEK, SGD, THB, TRY, USD, ZAR, NIS
PaySafeCardapmgw_PaySafeCardAD, AU, AT, BE, BG, CA, HR, CY, CZ, DK, FI, FR, DE, GI, HU, IE, IT, LV, LI, LT, LU, MT, MX, NL, NZ, NO, PE, PL, PT, RO, SK, SI, ES, SE, CH, GB, UYAUD, CAD, CHF, DKK, EUR, GBP, HRK, MXN, NOK, NZD, RON, SEK, USD
2C2P Paymentsapmgw_2C2P_APMsID, MY, MM, PH, SG, THIDR, MYR, PHP, SGD, THB
Abaqoosapmgw_ABAQOOSHUAUD, CAD, DKK, EUR, GBP, HKD, HUF, NOK, SEK, USD
Alipayapmgw_AlipayCNAUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, NOK, SEK, SGD, USD
AstroPayapmgw_AstroPayAR, BO, BR, CL, CO, CR, MX, PE, VEUSD
Local Payment Optionsapmgw_Astropay_TEFAR, BR, CL, CO, MX, PE, UYARS, BRL, CLP, COP, MXN, PEN, USD, UYU
Bitpayapmgw_BitpayAL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, RS, AX, GG, IM, JE, GS, PSEUR, GBP, USD
Bokuapmgw_BokuAR, AU, AT, BH, BE, BR, BG, CA, CL, CN, CO, HR, CY, CZ, DK, DO, EC, EG, EE, FI, FR, DE, GR, GT, HN, HK, HU, IN, ID, IE, IL, IT, JO, KR, LV, LB, LT, MY, MX, NL, NZ, NI, NO, OM, PE, PH, PL, PT, QA, RO, RU, SA, SG, SK, SI, ZA, ES, SE, CH, SY, TW, TH, TR, UA, AE, GB, US, VE, VN, YE, PSAED, ARS, AUD, BGN, BHD, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, HRK, HUF, IDR, INR, JOD, KRW, LBP, LTL, LVL, MXN, MYR, NOK, NZD, OMR, PEN, PHP, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, THB, TRY, TWD, UAH, USD, VEF, VND, ZAR, NIS
Boleto bancarioapmgw_BOLETOBRBRL, USD
CASHlibapmgw_CASHlib_BE, FR, DE, GR, IT, LU, NL, PL, ES, TR, GBCHF, EUR, GBP, MYR, PLN
Citadelapmgw_CitadelAL, AU, AT, BE, BG, CA, CY, CZ, DK, EE, FI, FR, DE, GR, HK, HU, IS, IE, IT, JP, LV, LT, MY, MX, NL, NZ, PL, PT, RO, SG, ZA, ES, SE, GB, AFAUD, BGN, CAD, CZK, DKK, EUR, GBP, HKD, HUF, JPY, MXN, NZD, PLN, RON, SEK, SGD, USD, ZAR
EasyEFTapmgw_EasyEFTZAZAR
ecoPayzapmgw_ecoPayzAD, AI, AQ, AG, AR, AW, AU, AT, BS, BH, BD, BB, BE, BZ, BM, BO, BA, BV, BR, IO, BG, CA, CV, KY, CL, CN, CX, CC, CO, KM, CG, CK, CR, HR, CY, CZ, DK, DM, DO, TL, EC, EG, SV, EE, FK, FO, FJ, FI, FR, GF, PF, TF, GE, DE, GI, GR, GL, GD, GP, GU, GY, HM, VA, HN, HK, HU, IS, IN, IE, IL, IT, JM, JP, JO, KR, KW, LV, LI, LT, LU, MO, MK, MY, MV, MT, MH, MQ, MR, MU, YT, MX, MD, MC, MN, MS, NA, NP, NL, AN, NC, NZ, NI, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PN, PL, PT, PR, QA, RE, RO, RU, SH, KN, LC, PM, VC, WS, SM, ST, SA, SC, SG, SK, SI, SB, ZA, ES, LK, SR, SJ, SE, CH, TW, TH, TO, TT, TR, TM, TC, TV, UA, AE, GB, US, UM, UY, UZ, VE, VG, VI, WF, ME, AX, GG, IM, JE, GSAED, ARS, AUD, BGN, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EUR, GBP, HKD, HUF, ISK, JPY, LTL, LVL, MDL, MXN, MYR, NOK, NZD, PEN, PLN, RON, RSD, RUB, SEK, SGD, THB, TRY, UAH, USD, UYU, VEF, ZAR, NIS
Epay.bgapmgw_Epay_bgBGBGN, EUR, USD
EpayLinkapmgw_EpayLinkCNCNY, USD
EPSapmgw_EPSATEUR
Eutellerapmgw_EutellerFIAUD, CAD, DKK, EUR, GBP, HKD, NOK, SEK, USD
Fast Bank Transferapmgw_Fast_Bank_TransferAL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, RS, AX, BQ, GG, IM, JE, GS, PSARS, AUD, AZN, BGN, BHD, BND, BYR, CAD, CHF, CLP, COP, CRC, CZK, DKK, DZD, EEK, EGP, EUR, GBP, GEL, HKD, HRK, HUF, INR, IQD, ISK, JOD, KGS, KRW, KWD, KZT, LBP, LTL, LVL, MAD, MDL, MXN, NOK, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, THB, TND, UAH, USD, UYU, VEF, VND, YER, ZAR
Express Bank Transferapmgw_Faster_Bank_TransferGBGBP
Giropayapmgw_GiropayDEEUR
Halcashapmgw_HALCASHESEUR
HiPayapmgw_HiPayBE, BR, FR, DE, NL, PT, ES, GBAUD, BRL, CAD, CHF, EUR, GBP, SEK, USD
iDealapmgw_iDealNLAUD, CAD, DKK, EUR, GBP, HKD, NOK, SEK, USD
iDebitapmgw_iDebitAU, AT, BE, CA, FI, FR, DE, HK, HU, IT, JP, LV, NL, NZ, PL, PT, SK, ZA, SE, GBAUD, CAD, EUR, GBP, USD
InstaDebitapmgw_InstaDebitCACAD, USD
Lobanetapmgw_LobanetBR, CL, MX, PE, UYBRL, CLP, MXN, PEN, UYU
Bancontactapmgw_MISTERCASHBEEUR
Monetaapmgw_Moneta__Direct_Integration_RUEUR, GBP, RUB, USD
Monetaapmgw_MonetaRUEUR, GBP, USD
MULTIBANCOapmgw_MULTIBANCOPTEUR
Neosurfapmgw_NeosurfBE, FR, IT, ESEUR
NeoSurf(Direct-Integration)apmgw_NeoSurf_Direct_Integration_AU, AT, BE, BJ, BF, BI, CM, CA, CF, TD, CG, CD, CI, CY, GQ, FR, GA, GM, GH, GN, GW, IE, IT, KE, LU, MW, ML, MR, MA, MZ, NL, NE, NG, PL, PT, RO, RW, ST, SN, SL, ES, CH, TZ, TG, UG, GB, ZM, ZWCAD, EUR, GBP, RON
NeoSurf_CA(Direct-Integration)apmgw_NeoSurf_CA_Direct_Integration_CACAD
NeoSurf_UK(Direct-Integration)apmgw_NeoSurf_UK_Direct_Integration_GBGBP
OnShopapmgw_OnShopITEUR
Oxxoapmgw_OxxoMXMXN, USD
Przelewy24apmgw_P24PLEUR, PLN
Pay.comapmgw_Pay_ComAL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, AX, GG, IM, JE, GS, PSAUD, CAD, CHF, EUR, GBP, USD
PayUapmgw_PayUPLAUD, BGN, CHF, CZK, DKK, EUR, GBP, HUF, ISK, LTL, LVL, NZD, PHP, PLN, RON, SEK, SGD, ZAR
Pingitapmgw_PingitGBGBP
PlusPayapmgw_PlusPayFIAUD, BGN, CHF, CZK, DKK, EUR, GBP, HUF, ISK, LTL, LVL, NZD, PHP, PLN, RON, SEK, SGD, ZAR
POLIapmgw_POLIAUAUD, CAD, DKK, EUR, GBP, HKD, NOK, SEK, USD
POLIapmgw_POLINZNZAUD, CAD, DKK, EUR, GBP, HKD, NOK, NZD, SEK, USD
Przelewy24apmgw_PRZELEWYPLAUD, CAD, DKK, EUR, GBP, HKD, NOK, PLN, SEK, USD
Zimplerapmgw_PugglepayFI, SEEUR, SEK, USD
Qiwiapmgw_QIWIAM, AZ, BY, EE, GE, IN, IL, JP, KZ, KR, KG, LV, LT, MD, PA, RU, TJ, TH, TR, UA, GB, US, UZ, VNEUR, RUB, USD
Sepaapmgw_SepaAU, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IS, IE, IT, LV, LI, LT, LU, MT, MC, NL, NO, PL, PT, RO, SM, SK, SI, ES, SE, CH, GBEUR
Sofortuberweisungapmgw_SofortAT, BE, FR, DE, IT, NL, PL, SK, ES, CH, GBEUR, GBP
Sporopayapmgw_SporopaySKEUR
STPmexapmgw_STPmexMXMXN
Ticket Premiumapmgw_Ticket_PremiumBE, FR, ITEUR, GBP, USD
TicketSurfapmgw_TicketSurfFREUR
Todito Cashapmgw_Todito_CashMXMXN
Trustlyapmgw_TrustlyDK, EE, FI, PL, ES, SE, AFDKK, EUR, PLN, SEK
Trustlyapmgw_Trustly_DIAT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IS, IE, IT, LV, LI, LT, LU, MT, NL, NO, PL, PT, RO, SK, SI, ES, SE, CH, GBAED, ARS, AUD, AZN, BGN, BHD, BND, BRL, BYR, CAD, CHF, CNY, CRC, CZK, DKK, DZD, EEK, EGP, EUR, GBP, GEL, HKD, HRK, HUF, IDR, INR, IQD, ISK, JOD, JPY, KGS, KRW, KWD, KZT, LBP, LTL, LVL, MAD, MDL, MYR, NOK, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, THB, TRY, TWD, UAH, USD, VEF, VND, YER, ZAR, NIS
TrustPayapmgw_TrustpayBG, CZ, EE, HU, LV, LT, PL, RO, SKBGN, CHF, CZK, EUR, HUF, LTL, LVL, PLN, RON
UnionPayapmgw_UnionPayAL, DZ, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BR, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CO, KM, CG, CD, CR, CI, HR, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HN, HK, HU, IS, IN, ID, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, NA, NP, NL, NC, NZ, NI, NE, NU, OM, PK, PW, PA, PG, PY, PE, PH, PL, PT, PR, QA, RE, RO, RU, RW, SH, PM, SM, ST, SA, SN, SC, SL, SG, SK, SI, ZA, ES, LK, SR, SZ, SE, CH, TW, TJ, TZ, TH, TG, TO, TT, TN, TR, TM, TV, UG, UA, AE, GB, UY, UZ, VU, VE, VN, WF, EH, ZM, ZW, ME, GG, IM, JECNY
Use My Servicesapmgw_UseMyServicesDZ, AU, AT, BH, BE, BA, BR, BG, CM, CA, CO, CR, HR, CZ, EG, EE, FR, DE, GH, HU, IN, IQ, IT, JO, KW, LV, LB, LY, LT, MX, MA, NL, NG, OM, PA, PE, PH, PL, QA, RO, SA, SK, SI, ZA, ES, SE, CH, TN, TR, AE, GB, US, YE, RS, PSEUR, GBP
Webanqapmgw_WeBanqJP, PHUSD
WebMoneyapmgw_WebMoneyAM, AZ, BY, GE, KZ, KG, LV, LT, MD, RU, TJ, TM, UZ, VNEUR, RUB, USD
WebMoneyapmgw_Webmoney_Direct_Integration_AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, AX, GG, IM, JE, GS, PSEUR, RUB, UAH, USD
WebMoneyapmgw_Webmoney_SMS_Invoice_AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, RS, AX, GG, IM, JE, GS, PSEUR, RUB, UAH, USD
WeChatapmgw_WeChatCNAUD, CAD, CNY, EUR, GBP, JPY, KRW, NZD, THB, USD
Yandex.Moneyapmgw_YANDEXMONEYAM, AZ, BY, GE, KZ, KG, MD, RU, TJ, TM, UA, UZRUB, USD
Zimpler_FIapmgw_Zimpler_FIFIEUR
Zimpler_SEapmgw_Zimpler_SESESEK
Zimpler-PPROapmgw_Zimpler_PPROFI, SEEUR, SEK
VISA Checkoutvisa_checkoutAR, AU, BR, CA, CL, CN, CO, FR, HK, IN, IE, KW, MY, MX, NZ, PE, PL, QA, SA, SG, ZA, ES, UA, AE, GB, USAED, ARS, AUD, BRL, CAD, CLP, CNY, COP, EUR, GBP, HKD, INR, KWD, MXN, MYR, NZD, PEN, PLN, QAR, SAR, SGD, UAH, USD, ZAR
Apple Payppp_ApplePayGBAED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, RMB, COP, CRC, CUP, CVE, CYP, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SPL, SRD, STD, SVC, SYP, SZL, THB, TJS, TMM, TND, TOP, TRY, TTD, TVD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZWD, NIS, YEN, SSP
WeChat_QuickPayapmgw_WeChat_QuickPayCNAUD, CAD, EUR, GBP, JPY, KRW, NZD, THB, USD
IDSapmgw_IDSCACAD, USD
Todito Cash(Direct-Integration)apmgw_Todito_Cash_Direct_Integration_MXMXN, USD
AliPay-DIapmgw_AliPay_DICNAUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD
E-Pro Visaapmgw_E_Pro_VisaAL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, RS, AX, BQ, CW, GG, IM, JE, GS, PSAED, ARS, AUD, AZN, BGN, BHD, BND, BRL, BYR, CAD, CHF, CLP, CNY, COP, CRC, CZK, DKK, DZD, EEK, EGP, EUR, GBP, GEL, HKD, HRK, HUF, IDR, INR, IQD, ISK, JOD, JPY, KGS, KRW, KWD, KZT, LBP, LTL, LVL, MAD, MDL, MXN, MYR, NOK, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, THB, TND, TRY, TWD, UAH, USD, UYU, VEF, VND, YER, ZAR, NIS, BYN
NAME NAME IN SAFECHARGE SUPPORTED COUNTRIES SUPPORTED CURRENCIES



APM Unique SafeCharge Names (Payout)

Credit Cardcc_cardALLAED, ARS, AUD, AZN, BGN, BHD, BND, BRL, BYN, BYR, CAD, CHF, CLP, CNH, CNY, COP, CRC, CZK, DKK, DZD, EEK, EGP, EUR, GBP, GEL, HKD, HRK, HUF, IDR, INR, IQD, ISK, JOD, KGS, KRW, KWD, KZT, LBP, LTL, LVL, MAD, MDL, MXN, MYR, NIS, NOK, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, SKK, THB, TND, TRY, TWD, UAH, USD, UYU, VEF, VND, YEN, YER, ZAR
PayPalapmgw_expresscheckoutAL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, AX, GG, IM, JE, GSAUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RUB, SEK, SGD, TWD, USD, NIS
Skrillapmgw_MoneyBookersAL, DZ, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, RS, AX, GG, IM, JE, GS, PSAED, AUD, BGN, CAD, CHF, CZK, DKK, EEK, EUR, GBP, HKD, HUF, INR, JPY, NOK, NZD, PLN, RON, SEK, SGD, THB, TRY, USD, ZAR, NIS
Netellerapmgw_NetellerAL, DZ, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CX, CC, CO, KM, CG, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, NO, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UY, UZ, VU, VE, VN, VG, WF, EH, YE, ZM, ZW, AF, ME, RS, GG, IM, JE, PSAUD, BGN, BRL, CAD, DKK, EUR, GBP, HUF, INR, JPY, LTL, LVL, MXN, NOK, PLN, RON, RUB, SEK, USD, ZAR
SEPA Payoutsapmgw_SEPA_PayoutsAT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IS, IE, IT, LV, LI, LT, LU, MT, MC, NL, NO, PL, PT, RO, SM, SK, SI, ES, SE, CH, GBEUR
Fast Bank Transferapmgw_Fast_Bank_TransferAL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, OM, PK, PW, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AF, ME, RS, AX, BQ, GG, IM, JE, GS, PSARS, AUD, AZN, BGN, BHD, BND, BYR, CAD, CHF, CLP, COP, CRC, CZK, DKK, DZD, EEK, EGP, EUR, GBP, GEL, HKD, HRK, HUF, INR, IQD, ISK, JOD, KGS, KRW, KWD, KZT, LBP, LTL, LVL, MAD, MDL, MXN, NOK, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, THB, TND, UAH, USD, UYU, VEF, VND, YER, ZAR
VISA Checkoutvisa_checkoutAR, AU, BR, CA, CL, CN, CO, FR, HK, IN, IE, KW, MY, MX, NZ, PE, PL, QA, SA, SG, ZA, ES, UA, AE, GB, USAED, ARS, AUD, BRL, CAD, CLP, CNY, COP, EUR, GBP, HKD, INR, KWD, MXN, MYR, NZD, PEN, PLN, QAR, SAR, SGD, UAH, USD, ZAR
Trustlyapmgw_Trustly_DIAT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IS, IE, IT, LV, LI, LT, LU, MT, NL, NO, PL, PT, RO, SK, SI, ES, SE, CH, GBAED, ARS, AUD, AZN, BGN, BHD, BND, BRL, BYR, CAD, CHF, CNY, CRC, CZK, DKK, DZD, EEK, EGP, EUR, GBP, GEL, HKD, HRK, HUF, IDR, INR, IQD, ISK, JOD, JPY, KGS, KRW, KWD, KZT, LBP, LTL, LVL, MAD, MDL, MYR, NOK, NZD, OMR, PEN, PHP, PKR, PLN, QAR, RON, RSD, RUB, SAR, SEK, SGD, THB, TRY, TWD, UAH, USD, VEF, VND, YER, ZAR, NIS
NAME NAME IN SAFECHARGE SUPPORTED COUNTRIES SUPPORTED CURRENCIES

APM Account Identifiers (Payin)



APM Account Identifiers (Payout)



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

Documentation History

March 1, 2017
Initial API documentations published online.
June 1, 2017
Addition of test cards.
August 1, 2017
Addition of the withdrawal functionality.

Authentication

Authentication Management

getSessionToken

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





Input Parameters

Definition

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

Output Parameters

Example Response

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

Orders

Orders Management



openOrder

Initiation of the order in the system, which returns the order identifier. Note that this order may be updated afterwards, up until the point the transaction is sent to the gateway.



Input Parameters

Definition

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

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

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
deviceDetails
Class
No
deviceType,
deviceName,
deviceOS,
browser,
ipAddres

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
userDetails
Class
No
firstName,
lastName,
address,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county

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

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
billingAddress
Class
No
firstName,
lastName,
address,
cell
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county

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

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

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

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

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in the merchant’s system.
clientUniqueId
String
ID of the transaction in the merchant’s system.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
merchantDetails
Class
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
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.

updateOrder

This enables modifications of previously opened/created order details. Note that this order may be updated afterwards, up until the point the transaction is sent to the gateway.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/updateOrder.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
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "currency": "USD",
    "amount": "10",
    "amountDetails": {
        "totalShipping": "0",
        "totalHandling": "0",
        "totalDiscount": "0",
        "totalTax": "0"
    },
    "items": [{
        "name": "name",
        "price": "10",
        "quantity": "1"
    }],
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "",
        "deviceOS": "",
        "browser": "",
        "ipAddress": ""
    },
    "userDetails": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "shippingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "cell": "",
        "phone": "972502457558",
        "address": "some street",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "sippingCounty":""
    },
    "billingAddress": {
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "cell": "",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "country": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "addendums": {
        "localPayment": {
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        }
    },
    "timeStamp": "20170118191751",
    "checksum": "6b53666fc048a825be63cbb820da467b"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
Yes
Session identifier returned by the getSessionToken.
orderId
String
Yes
The order ID provided by SafeCharge.
This parameter is provided only in cases where this method is called after an Orders Management method.
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
clientUniqueId
String
Yes
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientRequestId
String
Yes
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
currency
String
No
The three character ISO currency code.
amount
Double
No
The transaction amount.
amountDetails
Class
See Description
totalShipping,
totalHandling,
totalDiscount,
totalTax

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

The items’ and amountDetails prices should be summed up in the amount parameter and sent separately.
All prices must be in the same currency.
deviceDetails
Class
No
deviceType,
deviceName,
deviceOS,
browser,
ipAddres

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
userDetails
Class
No
firstName,
lastName,
address,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county

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

If you have only one set of this information to send in request (name/address/email etc.), it is required to send it using billingAddress parameter.
billingAddress
Class
No
firstName,
lastName,
address,
cell,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county

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

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

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

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

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033", 
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
clientUniqueId
String
ID of the transaction in the merchant’s system.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
merchantDetails
Class
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
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.

getOrderDetails

Enables receiving specific details of an existing order/s.
Note that order details can be viewed at any point in time.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getOrderDetails.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
Yes
Session identifier returned by the getSessionToken.
orderId
String
Yes
The order ID provided by SafeCharge.
This parameter is provided only in cases where this method is called after an Orders Management method.
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
Yes
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
timeStamp
String
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId": "39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "currency": "USD",
    "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"
    },
    "addendums": {
        "localPayment": {
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        }
    },
    "transactionCreationDate": "20170118191845",
    "orderCreationDate": "20170117181313",
    "orderStatus": "CLOSED",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "transactionId": "1000030724",
    "errCode": "0",
    "reason": "",
    "gwErrorCode": "0",
    "gwErrorReason": "",
    "gwExtendedErrorCode": "0",
    "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
currency
String
The three character ISO currency code.
amount
Double
The transaction amount.
amountDetails
Class
totalShipping,
totalHandling,
totalDiscount,
totalTax
items
Class
name,
price,
quantity
deviceDetails
Class
deviceType,
deviceName,
deviceOS,
browser,
ipAddress

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).
userDetails
Class
firstName,
lastName,
address,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county
shippingAddress
Class
firstName,
lastName,
address,
cell,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
shippingCounty
billingAddress
Class
firstName,
lastName,
address,
cell,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county
dynamicDescriptor
Class
merchantName,
merchantPhone

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
addendums
Class
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

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

Please note that the possible values for the debitType parameter are:
'1’ - Singular payment.
'2’ - Instalments.
'3’ - Special debit.
transactionCreationDate
String
The date that the transaction was created.
orderCreationDate
String
The date that the order was created.
orderStatus
String
OPENED – Order is open and can be modified.
CLOSED – Order was paid, and can no longer be modified.
IN_PROGRESS – Order is being paid, and can no longer be modified.
FAILED – The order failed and can no longer be modified.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
The gateway transaction status.
Possible values: APPROVED, DECLINED, 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.)
gwErrorCode
String
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
String
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.

Payments

Credit Card 3D Secure

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

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

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

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

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

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



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

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

dynamic3D

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



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/dynamic3D.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "isDynamic3D": "1",
    "dynamic3DMode":"ON",
    "isRebilling":"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"
    },
    "addendums": {
        "localPayment":{
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        }
    },
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "externalMpi": {
        "isExternalMpi":"0",
        "eci":"",
        "cavv":"",
        "xid":""
    },
    "storedCredentials": {
        "storedCredentialMode":""
    },
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
Yes
Session identifier returned by the getSessionToken.
orderId
String
No
The order ID provided by SafeCharge.
This parameter is provided only in cases where this method is called after an Orders Management method.
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
No
ID of the user in the merchant’s system.

If userPaymentOption sent in the request, then it is mandatory to send userTokenId in the request as well.
clientUniqueId
String
Yes
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
Yes
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
isDynamic3D
String
Yes
Always send isDynamic3D = 1.
dynamic3DMode
String
Yes
See Description
In case the merchant wants to force the transaction to go to 3D, send dynamic3DMode = ON.
In case the merchant wants to force the transaction to go to NON-3D, send dynamic3DMode = OFF.
In case the merchant would like to let SafeCharge’s rule system decide whether the transaction will go to 3D or not, do not send this parameter at all.
isRebilling
Integer
No
This indicates whether this is a regular transaction or a recurring/re-billing transaction.
Possible values:
0 - this is a regular transaction.
1 - this is a recurring/re-billing transaction.
Re-billing can only be performed using a UPO ID, and NOT using card data or a card token.

Note that: in case isRebilling=1 sent then must also send isDynamic3D=1 and dynamic3DMode=OFF.
currency
String
Yes
The three character ISO currency code.
amount
Double
Yes
The transaction amount.
amountDetails
Class
Yes
See Description
totalShipping,
totalHandling,
totalDiscount,
totalTax

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

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

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

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

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

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

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

Note that, country parameter is always mandatory.

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

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
If you work in a Sale mode then you must provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
cardData
Class
No
This may be one of two options:
cardNumber,
cardHolderName,
expirationMonth,
expirationYear,
CVV
-OR-
ccTempToken,
CVV,
cardHolderName

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

CVV can be mandatory or non-mandatory per configuration.

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

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

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

CVV can be mandatory or non-mandatory per configuration.
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

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

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

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

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

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

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

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

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

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, will be tokenized and stored for future transactions.
1 - Previously tokenized and stored card data was used to perform the transaction.
This parameter is only applicable to merchants that store tokenized card data and is mandatory when cardData->cardNumber parameter is populated and sent. Merchants that do not store card data, or that are using SafeCharge’s tokenization feature , should not send this parameter.
timeStamp
String
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "threeDFlow": "0",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "", 
    "gwErrorCode": "0",
    "gwErrorReason": "",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "eci": "",
    "threeDReason": "",
    "paRequest": "",
    "acsUrl": "www.issuer3Dsite.com",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    } 
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in the merchant’s system.
clientUniqueId
String
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
threeDFlow
String
If the value sent in isDynamic3D input parameter equals 1 (i.e. 3DSecure was configured to be managed by SafeCharge’s Rules Engine) then this parameter indicates whether the performed transaction was auth3D (1), or whether the performed transaction was auth/sale(0). For the merchant required actions once the response is received, see Possible Scenarios Table.
status
String
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,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
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.)
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side. When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.
userPaymentOptionId
String
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
The transaction ID of the transaction in the event that an external service is used.
transactionId
String
The gateway transaction ID.
authCode
String
Authorization code of the transaction.
eci
String
This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed.

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

Note that, in this method eci will be returned in response only in case its value is 1 or 6 or 7.
threeDReason
String
If the attempt failed this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
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_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

Parameters arriving from a third-party payment provider that also generate card tokens (currently relevant only to CreditGuard as third party payment provider which generate card tokens).



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



payment3D

This final stage performs the actual payment transaction.



Input Parameters

Definition

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

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

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

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

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

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

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

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

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

Note that, country parameter is always mandatory.

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

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
If you work in a Sale mode then you must provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

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

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

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
cardData
Class
No
This may be one of two options:
cardNumber,
cardHolderName,
expirationMonth,
expirationYear,
CVV
-OR-
ccTempToken,
CVV,
cardHolderName

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

CVV can be mandatory or non-mandatory per configuration.

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

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

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

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

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

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, will be tokenized and stored for future transactions.
1 - Previously tokenized and stored card data was used to perform the transaction.
This parameter is only applicable to merchants that store tokenized card data and is mandatory when cardData->cardNumber parameter is populated and sent. Merchants that do not store card data, or that are using SafeCharge’s tokenization feature , should not send this parameter.
timeStamp
String
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "", 
    "gwErrorCode": "0",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "eci": "",
    "threeDReason": "",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    },
    "partialApprovalDetails":{
        "isPartialApproval": "",
        "amountInfo":{
            "requestedAmount": "",
            "requestedCurrency": "",
            "processedAmount": "",
            "processedCurrency": ""
        }
    } 
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in the merchant’s system.
clientUniqueId
String
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status
String
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,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
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.)
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side. When a transaction is successful, this field is 0.
When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.
userPaymentOptionId
String
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
The transaction ID of the transaction in the event that an external service is used.
transactionId
String
The gateway transaction ID.
authCode
String
Authorization code of the transaction.
eci
String
This is returned from banks and indicates whether the attempted transaction passed as full 3D or failed.

The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D program when the cardholder provides payment information to the merchant. Possible ECI data values are: ECI = 5(VISA), 2(MC): the cardholder was successfully authenticated; ECI = 6(VISA), 1(MC): the issuer or cardholder does not participate in a 3D Secure program; ECI = 7: payment authentication was not performed.
threeDReason
String
If the attempt failed this parameter is returned by the banks to indicate the reason why the transaction was not passed as full 3D.
externalToken
Class
externalToken_blockedCard,
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

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

These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.

Card Tokenization

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

High-level PCI certified merchants can work with this API fully server to server, as well as perform credit card payments be sending the card data itself in the API call request, either dynamic3D, payment3D methods (recommended) or using paymentCC method.

Card tokenization is intended for low-level PCI certified merchants implementing card tokenization.

For security and PCI reasons, please note that low-level PCI certified merchants that cannot enter card data on their side and use a native mobile application are not required to use the credit card tokenization client SDK. However, they are able to call the cardTokenization method directly.

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

For more information about this API flow, see Card Tokenization Payment (Web) Flow, and Card Tokenization Payment (Mobile) Flow.


Client SDK for Card Tokenization



Instructions for Low-Level PCI Merchants that use an Online Website

safecharge.js is SafeCharge’s JavaScript library for securely sending sensitive information to SafeCharge directly from the customer’s browser.
safecharge.js makes it easy to collect credit card sensitive data without having the information come in contact with the merchant server.
Currently, it allows collecting card data to perform card tokenization for performing payments using a card token instead of using card data.

Step 1: Include safecharge.js in your code.
For using safecharge.js, always begin by including the library. Add this script tag to your page to get started with safecharge.js:

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


Step 2: Create an object to contain all required data.
For this example, this object is called payload and contains the required data.

It’s structure is:

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "merchantSiteId":"1811",
  "environment":"test",
  "sessionToken":"3b2259be-192a-4ca9-832d-01d6a8a26577",
  "billingAddress":{
        "city":"Berlin",
        "country":"DE",
        "zip":"10021",
        "email":"janedoe@mail.com",
        "firstName":"Jane",
        "lastName":"Doe",
        "state":""
  },
  "cardData":{
        "cardNumber":"4111111111111111",
        "cardHolderName":"John Doe",
        "expirationMonth":"01",
        "expirationYear":"2020",
        "CVV":"123"
   }
}

 


Step 3: Create a result handler
For this example, this handler is called safechargeResultHandler and handles the result. It is a function existing on the same page, which utilizes the result, handles error or returns the card token upon success.
It receive’s the result in this structure upon success:

COPIED
1
2
3
4
5
6
7
8
9
{
  "ccTempToken":"9a58ab98-3f4e-40c6-ad5b-25ee85f3778e",
  "sessionToken":"4861ec7e-0514-4af1-9a41-aabdfb99d268",
  "internalRequestId":62913,
  "status":"SUCCESS",
  "errCode":"0",
  "reason":"",
  "version":"1.0"
}



It receives the result in this structure in the event of an error:

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "error":{
    "type":"card",
    "code":1065,
    "message":"InvalidToken"
  },
  "sessionToken":"",
  "internalRequestId":63013,
  "status":"ERROR",
  "errCode":1065,
  "reason":"Invalid token",
  "version":"1.0"
}

 



Step 4: Create a JavaScript form to collect the card data from the consumer.
There are no restrictions regarding the form design, but it should include the fields below for credit cards. It may be placed in any suitable location according to the merchant site user journey (field values are for example only).


Checkoutform



Step 5: Populate the payload fields with relevant values using the client side data from the above JavaScript form fields (card data fields), from the website/code (all other fields except for the session token field, which will be retrieved using getSessionToken server to server call and then passed from merchant server to merchant client), etc.

Step 6: Populate the payload object with a session token using the method in safecharge.js (session token field, which will be retrieved using getSessionToken server to server call and then passed from merchant server to merchant client). 'Payload and safechargeResultHandler’ will be its parameters. In addition, this command will also retrieve the card token and return the response with all relevant data in the structure described above.

 



cardTokenization Method






Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/cardTokenization.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
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "userTokenId": "487106",
    "cardData": {
        "cardNumber": "4111111111111111",
        "cardHolderName": "some name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV": "122"
    },
    "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":""
    }
}
PARAMETER TYPE MANDATORY DESCRIPTION
sessionToken
String
Yes
Session identifier returned by the getSessionToken.
userTokenId
String
No
ID of the user in the merchant’s system.
cardData
Class
Yes
cardNumber,
cardHolderName,
expirationMonth,
expirationYear,
CVV

CVV can be mandatory or non-mandatory per configuration.

If CVV not required need to send it with NULL value or not provide CVV parameter at all in the request.
billingAddress
Class
Yes
See Description
firstName,
lastName,
address,
cell,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county

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

Note that, country parameter is always mandatory.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1.0",
    "ccTempToken": "65432", 
    "isVerified":"TRUE"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
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.
ccTempToken
String
Credit card token.
isVerified
String
This indicates whether this card was validated at the bank as an existing valid card or only registered on the payments provider side.
Possible values:
TRUE - card verified at the bank.
FALSE - card not verified at the bank and only registered on the payments provider side.

Credit Card

paymentCC

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



Input Parameters

Definition

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

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

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

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

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

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

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

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

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

Note that, country parameter is always mandatory.

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

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
If you work in a Sale mode then you must provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

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

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

nationalId parameter is required to be sent while processing by local banks in certain countries, for example: Israel, Latin America (LATAM).For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
cardData
Class
No
This may be one of two options:
cardNumber,
cardHolderName,
expirationMonth,
expirationYear,
CVV
-OR-
ccTempToken,
CVV,
cardHolderName

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

CVV can be mandatory or non-mandatory per configuration.

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

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

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

CVV can be mandatory or non-mandatory per configuration.
urlDetails
Class
No
notificationUrl

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

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

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

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

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, will be tokenized and stored for future transactions.
1 - Previously tokenized and stored card data was used to perform the transaction.
This parameter is only applicable to merchants that store tokenized card data and is mandatory when cardData->cardNumber parameter is populated and sent. Merchants that do not store card data, or that are using SafeCharge’s tokenization feature , should not send this parameter.
timeStamp
String
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "", 
    "gwErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "externalToken":{
        "externalToken_blockedCard":"",
        "externalToken_cardAcquirerId":"",
        "externalToken_cardAcquirerName":"",
        "externalToken_cardBin":"",
        "externalToken_cardBrandId":"",
        "externalToken_cardBrandName":"",
        "externalToken_cardExpiration":"",
        "externalToken_cardLength":"",
        "externalToken_cardMask":"",
        "externalToken_cardName":"",
        "externalToken_cardTypeId":"",
        "externalToken_cardTypeName":"",
        "externalToken_clubName":"",
        "externalToken_creditCompanyId":"",
        "externalToken_creditCompanyName":"",
        "externalToken_extendedCardType":"",
        "externalToken_Indication":"",
        "externalToken_tokenValue":"",
        "externalToken_tokenProvider":""
    }, 
    "partialApprovalDetails":{
        "isPartialApproval": "",
        "amountInfo":{
            "requestedAmount": "",
            "requestedCurrency": "",
            "processedAmount": "",
            "processedCurrency": ""
        }
    }
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in the merchant’s system.
clientUniqueId
String
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status
String
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,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
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.)
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0.
When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.
userPaymentOptionId
String
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
The transaction ID of the transaction in the event that an external service is used.
transactionId
String
The gateway transaction ID.
authCode
String
Authorization code of the transaction.
externalToken
Class
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

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

These parameters are returned only in case “partial approval” feature was in use, per the relevant input parameter sent value.

Alternative Payment Method

This API enables the uniform and standardized processing of transactions for many APMs, which enable consumers to purchases goods and services, either for convenience or due to a consumer located in a country where card-based payment methods are not the leading means of completing purchases and/or not available.

APMs are beneficial to merchants by enabling them to conduct transactions with consumers throughout the world by providing them with multiple payment options.

Each APM requires unique information about consumers and their transactions to process their payments. To simplify the process, the merchant sends requests to this API, which then passes the relevant information in the required format to each APM.

getMerchantPaymentMethods

Allows the merchant view the names, IDs and other information regarding the enabled payment methods and APMs, which may be filtered based on country, currency and language. It will be used by the merchant mostly in order to display the available payment methods in its payment page.
This method is also used to get the required parameters that are needed to prepare for the paymentAPM method.



Input Parameters

Definition

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
{
    "sessionToken": "",
    "merchantId": "",
    "merchantSiteId": "",
    "clientRequestId": "",
    "internalRequestId": "",
    "paymentMethods": [
      {
        "paymentMethod": "cc_card",
        "paymentMethodDisplayName": [
          {
            "language": "en",
            "message": "Credit Card"
          }
        ],
        "isDirect": "true",
        "countries": [
          "US",
          "DE"
        ],
        "currencies": [
          "USD"
        ],
        "logoURL": "",
        "fields": [
          {
            "name": "ccCardNumber",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Card Number"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Number"
              }
            ]
          },
          {
            "name": "ccExpMonth",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Expiration Month"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Expiration Month"
              }
            ]
          },
          {
            "name": "ccExpYear",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Expiration Year"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Card Expiration Year"
              }
            ]
          },
          {
            "name": "ccNameOnCard",
            "regex": "",
            "type": "text",
            "validationmessage": [
              {
                "language": "en",
                "message": "Invalid Name on Card"
              }
            ],
            "caption": [
              {
                "language": "en",
                "message": "Cardholder name as it appears on your credit card"
              }
            ]
          }
        ]
      }
    ],
    "type":"DEPOSIT",
    "status": "",
    "errCode": "",
    "reason": "",
    "version": ""
}
Parameter Type Description
sessionToken
String
Session identifier returned by getSessionToken.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
clientRequestId
String
ID of the API request in merchant system.
internalRequestID
String
SafeCharge Internal unique request id (used for reconciliation purposes, etc.).
paymentMethods
Class
paymentMethod,
paymentMethodDisplayName {language, message},
isDirect,
countries,
currencies,
logoURL,
fields: name, regex, type, validationMessage {language, message}, caption {language, message}
type
String
The type of the payment methods to be returned. Possible values: DEPOSIT, WITHDRAWAL. If no value sent, then default value will be DEPOSIT.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS, ERROR.
errCode
String
If an error occurred on the request side then an error code will be returned in this parameter.
reason
String
If an error occurred on the request side then an error reason will be returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
version
Integer
The current version of your request. Current version is 1.

paymentAPM

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



Input Parameters

Definition

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

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

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

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

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

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

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

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

Note that, the email parameter is mandatory for most APM’s.

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

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
addendums
Class
No
This block contains industry specific addendum. The addendum fields that appear are based on the specific addendum type.

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

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

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

This is mandatory if the userPaymentOption (below) is not sent.
userAccountDetails
Map
No
SafeCharge’s account identifiers of the payment methods. For more information, see APM Account Identifiers.

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

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

This is mandatory if the user desires to pay with an existing UPO and paymentMethod, userAccountDetails (above) were not sent.
urlDetails
Class
No
successUrl,
failureUrl,
pendingUrl,
notificationUrl

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

Sub method parameter allow to work with a specific payment method in few different flows. For example in case of PayPal, it allow to work in PayPal regular mode or in PayPal quick registration mode. subMethod field possible values for PayPal:
1 - PayPal quick registration.
0 - (default value) - otherwise.

subMethodFiels1 and subMethodField2 can be used in order to send additional values required for the sub method.
timeStamp
String
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientUniqueId": "12345",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "errCode": "0",
    "reason": "", 
    "paymentMethodErrorCode": "0",
    "paymentMethodErrorReason": "",
    "gwErrorCode": "0",
    "gwErrorReason": "",
    "gwExtendedErrorCode": "0",
    "version": "1.0",
    "userPaymentOptionId": "12442",
    "externalTransactionId": "2345346589",
    "transactionId": "1000030724",
    "authCode": "08AF6E",
    "redirectURL": "www.apmurl.com"
}
PARAMETER TYPE DESCRIPTION
sessionToken
String
Session identifier returned by getSessionToken.
orderId
String
The order ID provided by SafeCharge.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in the merchant’s system.
clientUniqueId
String
ID of the transaction in the merchant’s system.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR, PENDING.
merchantDetails
Class
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
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.)
paymentMethodErrorCode
Integer
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.
userPaymentOptionId
Long
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
externalTransactionId
String
A unique ID generated by SafeCharge that represents the APM transaction.
transactionId
String
The gateway transaction ID.
authCode
String
Authorization code of the transaction.
redirectURL
String
The URL used by the merchant to redirect consumers to the payment method for authentication and authorization of the payment. This is returned only if the APM payment is conducted using redirect APM flow.

Apple Pay

Apple Pay Certificates

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

Apple Pay Certification

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


Creating a Payment Processing Certificate

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


The use of Keychain Access tool is not mandatory. Any tool that can generate the private key (with the required size and type) and the certificate signing request file, may be used. In that case, the private key and the public key signed by Apple must be merged together and imported to a key store of type “.p12” and must be sent to SafeCharge.

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

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

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

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

Apple Pay Server to Server JS Button Solution

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

Minimum Requirements

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

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

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



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

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


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

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


4. In return the JavaScript that will be attached to the Apple Pay button and will handle your transaction.

Apple Pay Hosted Payment Page Redirect Solution

This solution is relevant for a merchant which is integrated to SafeCharge hosted payment page while redirection to it. SafeCharge hosted payment page will include Apply Pay as an offered payment method in the gallery.
For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.

Apple Pay Hosted Payment Page iFrame Solution using iOS SDK

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

Apple Pay Hosted Payment Page iFrame Solution

This solution is relevant for a merchant which is integrated to SafeCharge hosted payment page while presenting it as an an iFrame in it’s own page.
As SafeCharge payment page is an iFrame in this case, then SafeCharge unable to know if Apple Pay is available on the device being used at the time. Therefore SafeCharge have provided a JS code on CDN, the merchant can use it in order to share if Apply Pay is available on the device.

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


HTML example:

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

Re-bill

Re-bill is performed by sending isRebilling parameter as input to dynamic3D or paymentCC.
Re-bill can only be performed using a user payment option (UPO) ID, and not with card data or card token.
The re-bill transaction is based on a previous successful transaction performed using the same UPO ID.
This allows the merchant to manage the subscription on its side and send only re-bill transactions.

Subscription

This allows the merchant to manage the subscription on SafeCharge’s side.

createSubscription

This method is used for creating a subscription for consumers that wish to conduct future recurring transactions based on previous successful transactions.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/createSubscription.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
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientRequestId": "12345",
    "subscriptionPlanId": "12345",
    "dynamicDescriptor": {
        "merchantName": "merchantName",
        "merchantPhone": "merchantPhone"
    },
    "userDetails": {
        "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":""
    },
    "deviceDetails": {
        "deviceType": "DESKTOP",
        "deviceName": "deviceName",
        "deviceOS": "deviceOS",
        "browser": "browser",
        "ipAddress": "ipAddress"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "urlDetails": {
        "notificationUrl": ""
    },
    "cardData": { 
        "cardNumber": "4111111111111111",
        "cardHolderName": "some name",
        "expirationMonth": "01",
        "expirationYear": "2020",
        "CVV": "122",
        "ccTempToken": ""
    },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503",
        "CVV":"234"
    },
    "billingAddress": {
        "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":""
    },
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
Yes
The ID of the user in merchant system.

If userPaymentOption sent in the request, then it is mandatory to send userTokenId in the request as well.
clientRequestId
String
Yes
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
subscriptionPlanId
String
Yes
ID of the subscription plan.
dynamicDescriptor
Class
No
merchantName,
merchantPhone
userDetails
Class
No
firstName,
lastName,
address,
phone,
zip,
city,
country (two-lett ISO country code),
state(two-letter ISO state code),
email,
county

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.
deviceDetails
Class
Yes
See Description
deviceType,
deviceName,
deviceOS,
browser,
ipAddress

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

ipAddress parameter can be defined as mandatory or non mandatory per need by SafeCharge integration team.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
urlDetails
Class
No
notificationUrl

Each parameter is limited for up to 1000 characters.
cardData
Class
No
This may be one of two options:
cardNumber,
cardHolderName,
expirationMonth,
expirationYear,
CVV
-OR-
ccTempToken,
CVV,
cardHolderName

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

CVV can be mandatory or non-mandatory per configuration.

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

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

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

CVV can be mandatory or non-mandatory per configuration.
billingAddress
Class
No
firstName,
lastName,
address,
cell,
phone,
zip,
city,
country(two-letter ISO country code),
state(two-letter ISO state code),
email,
county
timeStamp
String
Yes
The local time when the method call is performed in the format:
YYYYMMDDHHmmss
checksum
Hexadecimal string
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, userTokenId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },  
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "", 
    "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
subscriptionId
String
The ID of the user’s active subscription in SafeCharge’s system.
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
merchantDetails
Class
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
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.

cancelSubscription

This method is used for canceling existing subscriptions.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/cancelSubscription.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientRequestId": "12345",
    "subscriptionId": "12345",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
Yes
The ID of the user in merchant system.
clientRequestId
String
Yes
See Description
The ID of the API request in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
subscriptionId
String
Yes
The ID of the user’s active subscription in SafeCharge’s system.
timeStamp
String
Yes
The local time when the method call is performed in the format:
YYYYMMDDHHmmss
checksum
Hexadecimal string
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, subscriptionId, userTokenId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "", 
    "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
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.

getSubscriptionsList

This method is used for receiving a list of all existing subscriptions.
The results can be filtered by the input parameters.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getSubscriptionsList.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "12345",
    "userTokenId": "487106",
    "subscriptionStatus": "ACTIVE",
    "firstResult": "",
    "maxResults": "100",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
Yes
See Description
The ID of the API request in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
userTokenId
String
Yes
The ID of the user in merchant system.
subscriptionStatus
String
No
Allows filtering base on the subscription status. Possible values are: INITIALIZING, ACTIVE, INACTIVE, CANCELED.
firstResult
Integer
No
Based on the search result set of records, the system displays a subset of records. The firstResult is a record number from which the subset starts.
If there is no firstResult, the default value will be '0’.
maxResults
Integer
No
Based on the search result set of records, the system displays a subset of records. maxResult is a number of records of the subset that has to be displayed.
If there is no maxResult, the default value is set for 1000 records. If maxResult is set to 0, 1000 records are returned.
timeStamp
String
Yes
The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum
Hexadecimal string
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, userTokenId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "12345",
    "internalRequestId": "12345",
    "totalCount": "100",
    "subscriptionsList": [{
        "subscriptionId": "12345",
        "subscriptionStatus": "ACTIVE",
        "subscriptionCreationDate": "",
        "subscriptionPlanId": "12345",
        "userTokenId": "487106",
        "billingAddress": {
            "firstName": "some first name",
            "lastName": "some last name",
            "address": "some street",
            "phone": "972502457558",
            "zip": "",
            "city": "some city",
            "countryCode": "GB",
            "state": "",
            "email": "someemail@somedomain.com",
            "locale":"",
            "birthdate":"",
            "county":""
        },
        "userPaymentOption": {
            "userPaymentOptionId": "741",
            "paymentMethodName":"cc_card",
            "upoName":"(1111)",
            "upoStatus": "enabled",
            "upoRegistrationDate": "",
            "expiryDate": ""
        },
        "upoData": {
            "cardType": "",
            "ccCardNumber": "4****1111",
            "nameOnCard": "John Smith",
            "expMonth": "12",
            "expYear": "24",
            "brand": "Visa",
            "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=",
            "bin": "411111",
            "last4Digits": "1111",
            "ccToken":""
        }
    }],
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "", 
    "version": "1.0"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
totalCount
String
This parameter returns the total number of records returned.
subscriptionsList
Class
subscriptionId,
subscriptionStatus,
subscriptionCreationDate,
subscriptionPlanId,
userTokenId,

billingAddress:
firstName,
lastName,
address,
phone,
zip,
city,
countryCode(two-letter ISO country code),
state(two-letter ISO state code),
email,
locale,
birthdate,
county

userPaymentOption:
userPaymentOptionId,
paymentMethodName,
upoName,
upoStatus,
upoRegistrationDate,
expiryDate

upoData:
cardType,
ccCardNumber,
ccExpMonth,
ccExpYear,
ccNameOnCard,
ccToken,
brand,
uniqueCC,
bin,
last4Digits
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.

getSubscriptionPlans

This method is used for returning the available subscriptions plans for the merchant.
Creating and updating subscription plans is possible using CPanel, SafeCharge’s back-office tool. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com



Input Parameters

Definition

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "internalRequestId": "866",
    "subscriptionPlans": [{
        "subscriptionPlanId": "12345",
        "productName": "Any Product",
        "currency": "GBP",
        "initialAmount": "100",
        "rebillAmount": "50",
        "startUnit": "MONTH",
        "startUnitValue": "1",
        "recurrungUnit": "MONTH",
        "recurringUnitValue": "1",
        "endUnit": "MONTH",
        "endUnitValue": "3"
    }],
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "", 
    "version": "1.0"    
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
clientRequestId
String
The ID of the API request in merchant system.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
subscriptionPlans
Class
subscriptionPlanId,
productName,
currency,
initialAmount,
rebillAmount,
startUnit,
startUnitValue,
recurrungUnit,
recurringUnitValue,
endUnit,
endUnitValue

The 'unit’ can be: day, month, or year.
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.

Settle

settleTransaction

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



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/settleTransaction.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "100",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "8495798459",
    "authCode": "8378749", 
    "descriptorMerchantName": "Name", 
    "descriptorMerchantPhone": "+4412378", 
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": ""
    },
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
Yes
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientUniqueId
String
Yes
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
amount
Decimal
Yes
The transaction amount.
currency
String
Yes
The three character ISO currency code.
It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId
String
Yes
The ID of the original auth transaction.
authCode
String
Yes
The authorization code of the related auth transaction, to be compared to the original one.
descriptorMerchantName
String
No
Allows the merchant to define a dynamic descriptor for the merchant’s name, which will appear in the payment statement.
If you work in an auth-Settle mode then you must provide a value for this field in order for it to appear in the payment statement.

For dynamic descriptor, special configuration required. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com.
descriptorMerchantPhone
String
No
Allows the merchant to define a dynamic descriptor for the merchant’s phone number, which will appear in the payment statement.
If you work in an auth-Settle mode then you must to provide a value for this field in order for it to appear in the payment statement.

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

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "merchantId": "8263015379487437770",
   "merchantSiteId": "39",
   "internalRequestId": "45",
   "clientRequestId": "100",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "authCode": "8378749",
   "errCode": "0",
   "reason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
internalRequestId
String
ID of the API request in merchant system.
clientRequestId
String
The client’s request ID as defined by the merchant for record-keeping.
transactionId
String
The transaction ID of the settle transaction for future actions.
externalTransactionId
String
The transaction ID of the transaction in the event that an external service is used.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
authCode
String
Authorization code of the transaction.
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.)
paymentMethodErrorCode
Integer
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.

Refund

refundTransaction

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



Input Parameters

Definition

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

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "merchantId": 8263015379487437770,
   "merchantSiteId": "39",
   "internalRequestId": 45,
   "clientRequestId": "100",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "authCode": "8378749",
   "errCode": "0",
   "errReason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
The client’s request ID as defined by the merchant for record-keeping.
transactionId
String
The transaction ID of the refund transaction for future actions.
externalTransactionId
String
The transaction ID of the transaction in the event that an external service is used.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
authCode
String
Authorization code of the transaction.
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.)
paymentMethodErrorCode
Integer
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.

Void

voidTransaction

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



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/voidTransaction.do
Example Request
COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "100",
    "clientUniqueId": "12345",
    "amount": "9.0",
    "currency": "EUR",
    "relatedTransactionId": "8495798459",
    "authCode": "8378749", 
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
clientRequestId
String
Yes
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientUniqueId
String
Yes
See Description
ID of the transaction in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
Appears in DMN as merchant_unique_id parameter.
amount
Decimal
Yes
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
Yes
The three character ISO currency code.
It is required to send the same currency as the one sent before for the related transaction.
relatedTransactionId
String
Yes
The ID of the original auth transaction.
authCode
String
Yes
The authorization code of the related settle transaction, to be compared to the original one.
comment
String
No
Enables the addition of a free text comment to the request.
urlDetails
Class
No
notificationUrl

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{ 
   "merchantId": 8263015379487437770,
   "merchantSiteId": "39",
   "internalRequestId": 45,
   "clientRequestId": "100",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "authCode": "8378749",
   "errCode": "0",
   "errReason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
ID of the API request in merchant system.
transactionId
String
The transaction ID of the void transaction for future actions.
externalTransactionId
String
The transaction ID of the transaction in the event that an external service is used.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
transactionStatus
String
The gateway transaction status.
Possible values: APPROVED, DECLINED, ERROR.
authCode
String
Authorization code of the transaction.
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.)
paymentMethodErrorCode
Integer
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.

Payout

payout

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





Input Parameters

Definition

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

This allows the merchant to define a dynamic descriptor for its name and phone number, which will appear in the payment statement.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
userPaymentOption
Class
Yes
userPaymentOptionId,
CVV

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

CVV can be mandatory or non-mandatory per configuration.
comment
String
No
Enables the addition of a free text comment to the request.
urlDetails
Class
No
notificationUrl

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
   "merchantId": "8263015379487437770",
   "merchantSiteId": "39",
   "userTokenId": "487106",
   "clientUniqueId": "12345",
   "clientRequestId": "1484759782197",
   "internalRequestId": "866",
   "transactionId": "8498764859",
   "externalTransactionId": "",
   "status": "SUCCESS",
   "transactionStatus": "APPROVED",
   "merchantDetails": {
    "customField1": "",
    "customField2": "",
    "customField3": "",
    "customField4": "",
    "customField5": "",
    "customField6": "",
    "customField7": "",
    "customField8": "",
    "customField9": "",
    "customField10": "",
    "customField11": "",
    "customField12": "",
    "customField13": "",
    "customField14": "",
    "customField15": ""
   },
   "userPaymentOptionId": "12442",
   "errCode": "0",
   "reason": "",
   "paymentMethodErrorCode": "0",
   "paymentMethodErrorReason": "",
   "gwErrorCode": "0",
   "gwErrorReason": "",
   "gwExtendedErrorCode": "0",
   "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
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.
Appears in DMN as merchant_unique_id parameter.
clientRequestId
String
ID of the API request in the merchant’s system.
internalRequestId
String
ID of the API request in merchant system.
transactionId
String
The gateway transaction ID.
externalTransactionId
String
The transaction ID of the transaction in the event that an external service is used.
status
String
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,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
userPaymentOptionId
String
On the first time a consumer uses a payment method, SafeCharge assigns a unique ID to it and return it. The next time the consumer uses a payment method that SafeCharge has previously assigned an ID to, the ID is returned as the value of this parameter.
errCode
String
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.)
paymentMethodErrorCode
Integer
If an error occurred on the APM side, an error code is returned in this parameter.
paymentMethodErrorReason
String
If an error occurred on the APM side, an error reason is returned in this parameter.
gwErrorCode
Integer
If an error occurred in the gateway, then an error code is returned in this parameter.
gwErrorReason
String
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
Error code if error occurred on the bank’s side.
When a transaction is successful, this field is 0. When a transaction is not successful, the parameter is the code of the generic error.
version
Integer
The current version of the request. The current version is 1.

KYC

KYC

Know your customer (KYC) is the process of a business identifying and verifying the identity of its clients as part of due diligence requirements. The objective of KYC guidelines is to prevent financial institutions from being used, intentionally or unintentionally, by criminal elements for money laundering activities.
SafeCharge’s anti-money laundering (AML) and electronic KYC (eKYC) solutions enable businesses to quickly and easily identify high-risk applicants and manage them appropriately. Our electronic identity checks help organizations meet their KYC and AML obligations when new accounts are created and when existing consumers need to be checked.
This method can be used for initiating a real time electronic identity check/Pep and Sanctions (politically exposed persons and financial sanctions) checks via multiple leading providers.

Preliminary KYC Verification Requirements
Prior to initializing KYC verification, be sure to invoke the createUser method for generating a userTokenID parameter since this is a mandatory field for any KYC check.

Interpreting KYC Results
The KYC transaction results for can be interpreted by a combination of the transaction result (technical) and the KYC result (business).
• eKYC verification results are derived from the provider’s response regarding the number of matches among the name, address and date of birth and other data sources.
• Document verification results are derived from the list of issues detected in the uploaded proof-of-identity images.
Please note that a proof of residence is always returned with “Review” as the KYC result since this type of documentation cannot be verified by nature. For a list of possible issues, see Issue Types.

Transaction Results
Approved – The transaction was finalized as successful following a provider asynchronous notification.
Pending – The transaction was initialized successfully but is still pending on an asynchronous notification by the provider. Once a notification is sent a correction is updated in the system.
Declined – The transaction was finalized as unsuccessful following a provider asynchronous notification.
Error – The transaction could not be completed due to technical errors.

KYC Result
Approve – It is recommended to allow the customer to progress and update the end-user’s KYC status accordingly.
Error – The verification could not be accomplished due to technical errors.
Review – It is recommended to manually review the details and make a decision regarding the end-user’s KYC status.
Reject – It is recommended to update the end-user’s KYC status accordingly.
None – Verification could not be performed at the provider side. It is recommended to revise the request parameters.

eKYC

eKYC stands for electronic KYC, which enables performing the entire KYC process online.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/eKYC.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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "userId": "259",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "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":""
    },
    "ekycUserDetails": {
        "userName": "someUserName",
        "languageCode": "eng",
        "dateOfBirth": "1985-01-01",
        "title": "Mr.",
        "gender": "male",
        "building": "123",
        "postcode": "71937",
        "mobileCountryCode": "01",
        "mobileNumber": "8675309",
        "identification": "12345",
        "identificationType": "sometype"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "urlDetails": {
        "notificationUrl": ""
    },
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
Yes
ID of the user in merchant system.
userId
String
Yes
Name of the user in merchant system.
clientUniqueId
String
Yes
See Description
ID of the transaction in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientRequestId
String
Yes
See Description
ID of the API request in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
deviceDetails
Class
No
deviceType
deviceName
deviceOS
browser
ipAddres

The supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, and UNKNOWN (If a device type cannot be recognized).
userDetails
Class
Yes
See Description
firstName (mandatory),
lastName (mandatory),
address (mandatory),
phone (optional),
zip (mandatory),
city (optional),
country (mandatory, two-letter ISO country code),
state (optional, two-letter ISO state code),
email (mandatory),
county (optional)
ekycUserDetails
Class
Yes
See Description
userName,
languageCode,
dateOfBirth (mandatory, in YYYY-MM-DD format),
title,
gender,
building (should be populated with house number or building name),
postcode,
mobileCountryCode,
mobileNumber,
identification,
identificationType

The possible values for identificationType are: PassportNumber, NationalId, DrivingLicense.
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
urlDetails
Class
No
notificationUrl

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "internalRequestId": "12345",
    "status": "SUCCESS",
    "orderId":"39272",
    "transactionId": "1000030724",
    "transactionStatus": "APPROVED",
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "kycResult": "APPORVED",
    "kycServiceDetails": [{
        "serviceDescription": "",
        "subPoviderDescription": "",
        "resultDescription": "",
        "referenceId": "",
        "rawProviderData":
        {
        }
    }],
    "kycErrorCode": "",
    "kycErrorReason": "",
    "errCode": "",
    "reason": ""
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in merchant system.
clientUniqueId
String
ID of the transaction in merchant system.
clientRequestId
String
ID of the API request in merchant system.
internalRequestId
String
The SafeCharge Internal unique request ID, used for reconciliation purposes, etc).
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS, ERROR.
orderId
String
The order ID provided by SafeCharge.
transactionId
String
The gateway transaction ID.
transactionStatus
String
The gateway transaction status.
This parameter indicates the successful processing of the transaction, and has no implication on the consumer’s KYC analysis.
merchantDetails
Class
No
kycResult
String
The result of the consumer’s KYC analysis.
kycServiceDetails
Class
serviceDescription,
subPoviderDescription,
resultDescription,
referenceId,
rawProviderData

rawProviderData fields structure is different for each eKYC provider.
kycErrorCode
String
The KYC related error code.
kycErrorReason
String
The KYC related error description.
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 then an error reason will be returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
version
String
The current version of the request. The current version is 1. 



getDocumentUploadUrl

As part of the KYC process, customers are required to send personal documents in order to verify their identity.
This method return a URL which enables the uploading of these documents easily to help complete the KYC process quickly and securely.
The URL can be opened either via redirect or via iFrame, which directs the user to an upload wizard where he/she is prompted to upload the required documents according to the merchant’s policy. Once the request is sent, SafeCharge sends the merchant a DMN as its response.
The feature supports both Desktop and Mobile browsers.
SafeCharge detects and displays the relevant Proof Of ID documents based on the provider’s coverage for the end user’s country.


Documents Retrieval
Transaction related documents can be retrieved and reviewed on demand via the CPanel on the 'KYC Transactions Report Details’ screen. Further information on this can be found in the CPanel user guide.





Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getDocumentUploadUrl.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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "userId": "259",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "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":""
    },
    "kycUserDetails": {
        "userName": "someUserName",
        "dateOfBirth": "1985-01-01",
        "title": "Mr.",
        "gender": "male",
        "building": "123",
        "postcode": "71937",
        "mobileCountryCode": "01",
        "mobileNumber": "8675309"
    },
    "merchantDetails": {
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "customField6": "",
        "customField7": "",
        "customField8": "",
        "customField9": "",
        "customField10": "",
        "customField11": "",
        "customField12": "",
        "customField13": "",
        "customField14": "",
        "customField15": ""
    },
    "urlDetails": {
        "sucessUrl": "",
        "failureUrl": ""
    },
    "merchantLocale": "",
    "themeId": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
Yes
ID of the user in merchant system.
userId
String
Yes
Name of the user in merchant system.
clientUniqueId
String
Yes
See Description
ID of the transaction in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
clientRequestId
String
Yes
See Description
ID of the API request in merchant system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
userDetails
Class
Yes
See Description
firstName (optional),
lastName (optional),
address (optional),
phone (optional),
zip (optional),
city (optional),
country (optional, two-letter ISO country code),
state (optional, two-letter ISO state code),
email (mandatory),
county (optional)
kycUserDetails
Class
Yes
See Description
userName,
dateOfBirth (in YYYY-MM-DD format),
title,
gender,
building (should be populated with house number or building name),
postcode,
mobileCountryCode,
mobileNumber
merchantDetails
Class
No
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
urlDetails
Class
No
successUrl,
failureUrl

Each parameter is limited for up to 1000 characters.
merchantLocale
String
No
The default language. The current default value is English (for example: for English (US) the value will be en_US).
themeId
String
No
This parameter is configured per merchant site but if sent as input it will override the configuration and the themeId chosen will be presented.
timeStamp
String
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, clientRequestId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "url":"",
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "clientUniqueId": "12345",
    "clientRequestId": "100",
    "internalRequestId": "12345",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version":"1.0"
}
PARAMETER TYPE DESCRIPTION
url
String
The document upload page url including parameters.
For example: https://secure.SafeCharge.com/ppp/documentupload.do?merchant_id=427583496191624621&merchant_site_id=142033&…
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
userTokenId
String
ID of the user in merchant system.
clientUniqueId
String
ID of the transaction in merchant system.
clientRequestId
String
ID of the API request in merchant system.
internalRequestId
String
The SafeCharge Internal unique request ID, used for reconciliation purposes, etc).
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS, 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 then an error reason will be returned in this parameter. (E.g. failure in checksum validation, timeout from processing engine, etc.)
version
Sting
The current version of the request. The current version is 1. 


Issue Types (For document upload only)
The following table lists the possible issues that may arise from the document upload process. Where applicable, the appropriate issue code(s) will be returned in the DMN.

ISSUE TYPE ID DESCRIPTION
1
The ID document is expired.
2
The image quality is not sufficient. Please submit a new image.
3
The ID has two sides. Please submit images of both front and back.
4
Unable to determine ID type.
5
Comparison of printed data with MRZ (machine-readable zone) – unexpected result.
6
The ID type is not accepted for this transaction.
7
The age requirement is not met.
8
The image file type is not supported.
9
The image file size is not supported.
10
Document integrity issue – unexpected result.
11
ePassport photo – unexpected result.
12
Liveness checks – undetermined.
13
Unable to determine the ID’s expiration date.
14
UK DL No. – unexpected result.
15
Unable to validate DL No.
16
ePassport data – unexpected result.
17
DL (US) data – unexpected result.
18
Unable to confirm consistency of ID data across Face Data, MRZ (machine-readable zone) and/or Barcode.
19
ID data – unexpected result.
20
Composite check-digit – unexpected result.
21
Geolocation data not available.
22
MRZ (machine-readable zone) data – unexpected result
23
eChip authentication – unexpected authentication result.
24
eChip data – unexpected data result.
25
The document’s face data is unavailable for comparison.

DMN Response Parameters

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

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
Yes
ID of the user in the merchant’s system.
type
String
Yes
The type of KYC verfication.
Possible values are:
Document verification or eKYC.
clientUniqueId
String
Yes
ID of the transaction in the merchant’s system.
clientRequestId
String
Yes
ID of the API request in the merchant’s system.
orderId
String
No
The order ID provided by SafeCharge.
internalRequestId
String
Yes
The SafeCharge Internal unique request ID, used for reconciliation purposes, etc).
status
String
Yes
The cashier status of merchant request.
Possible statuses:
SUCCESS,
ERROR
transactionId
String
Yes
The gateway transaction ID.
providerReferenceId
String
Yes
The transaction ID as received from the KYC provider.
transactionStatus
String
Yes
The gateway transaction status.
Possible values:
APPROVED,
DECLINED,
ERROR
merchantDetails
Class
Yes
customField1,
customField2,
customField3,
customField4,
customField5,
customField6,
customField7,
customField8,
customField9,
customField10,
customField11,
customField12,
customField13,
customField14,
customField15
KYCResult
String
Yes
The description of the KYC result.
Possible values are:
APPROVED,
DECLINED,
REVIEW,
NONE
ageCheck
String
No
The result of the age verification.
redirectUrl
String
No
The URL used by the merchant to redirect consumers to the payment method for authentication and authorization of the payment.
This is required for document upload.
KYCServiceDetails
Class
No
These details are relevant only to eKYC.
service,
subProvider,
result,
referenceId,
rawProviderData

rawProviderData is an object with string data elements, e.g. raw data, which vary among providers.
kycErrorCode
String
No
The KYC related error code.
kycErrorReason
String
No
The KYC related error description.
errCode
String
No
Error code if error occurred at the cashier side.
reason
String
No
Error reason if error occurred at the cashier side (e.g.: failure in checksum validation, timeout from processing engine, etc.).
version
Sting
No
The version of your request. The current version is 1. 
userInfo
Class
No
The users personal information.
userName,
languageCode,
countryCode,
firstName,
lastName,
address,
city,
state,
zip,
email,
phone,
dateOfBirth,
title,
userId,
userTokenId,
gender,
buildingName,
postcode,
mobileCountryCode,
mobileNumber,
identification,
identificationType
transactionIssues
Class
No
The issues that arose from the transaction.
description,
decision
documents
Class
No
The document details.
id,
providerId,
type,
category,
KYCResult(mandatory),
status,
documentData (This is a class and consists of forenames, surname, fullName, dateOfBirth, gender, nationality, placeOfBirth, documentDescription, documentNumber, dateOfIssue, dateOfExpiry, issuingCountry, addressLine1, addressLine2, addressLine3, addressLine4, addressCity, addressState, addressPostcode, addressCountry, issuer)
documentIssues
Class
No
Issues that have arisen in the document upload.
description,
decision

Users

Users Management

create User

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



Input Parameters

Definition

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "45",
    "clientRequestId": "100", 
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1",
    "userId": "259"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
ID of the API request in the merchant’s system.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode
Integer
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
String
The current version of the request. The current version is 1.
userId
String
Unique identifier of the user in SafeCharge.

updateUser

This method updates a specific user’s details.



Input Parameters

Definition

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "47",
    "clientRequestId": "101",
    "status": "SUCCESS",
    "errCode": "0",
    "reason": "",
    "version": "1",
    "userId": "259"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
internalRequestId
Long
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
ID of the API request in the merchant’s system.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode
Integer
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
String
The current version of the request. The current version is 1.
userId
String
Unique identifier of the user in SafeCharge.

getUserDetails

This method returns the details of a specific existing user according to their User Token ID sent in the createUser call.



Input Parameters

Definition

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

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "merchantSiteId": "39",
    "merchantsiteId":"",
    "internalRequestId": "49",
    "clientRequestId":"",
    "userDetails":{
        "firstName": "John",
        "lastName": "Smith", 
        "address": "some street", 
        "phone": "", 
        "zip": "", 
        "city": "London",
        "countryCode": "GB",
        "state": "", 
        "email": "john.smith@test.com", 
        "locale": "", 
        "birthdate": "", 
        "userTokenId": "testUserToken",
        "userId": "259",
        "county":""
    },
    "status": " SUCCESS ", 
    "errCode": "0",
    "reason": "",
    "version": "1"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
ID of the API request in the merchant’s system.
userDetails
Class
firstName,
lastName,
address,
phone,
zip,
city,
countryCode,
state,
email,
locale,
birthdate,
userTokenId,
userId,
county
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode
Integer
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
String
The current version of the request. The current version is 1.

User Payment Options (UPO’s)

UPO’s Management

addUPOCreditCard

This method adds a credit card UPO for a specific user according to their User Token ID. Once a credit card UPO is added to the user’s list of UPOs, the credit card is displayed in the payment page.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCard.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
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId":"testUserToken",
    "clientRequestId": "235", 
    "ccCardNumber": "5101080963349948",
    "ccExpMonth": "01",
    "ccExpYear": "2020", 
    "ccNameOnCard": "test name",
    "billingAddress":{
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "timeStamp": "20150915151435",
    "checksum": "2e9084f71d45487a417c0efbb9bdd58a"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId
String
Yes
Merchant ID provided by SafeCharge.
merchantSiteId
String
Yes
Merchant Site ID provided by SafeCharge.
userTokenId
String
Yes
ID of the user in the merchant’s system.
clientRequestId
String
Yes
See Description
ID of the API request in the merchant’s system. This value must be unique.
This must be sent in order to perform future actions, such as, reconciliation, identifying the transaction in the event of any issues, etc.
ccCardNumber
String
Yes
A valid credit card number.
ccExpMonth
String
Yes
Two digit value representing the expiration month.
ccExpYear
String
Yes
Two or four digit value representing the expiration year. When the value is two digits, the year is assumed to be 2000 + ccExpYear. The ccExpMonth and ccExpYear must be a future date. The year may not exceed 10 years in to the future.
ccNameOnCard
String
Yes
The name of the credit card owner as it appears on the card.
billingAddress
Class
No
firstName,
lastName,
address,
phone,
zip,
city,
countryCode(two-letter ISO country code),
state(two-letter ISO state code),
email,
county
timeStamp
String
Yes
The local time of the method call is performed in the format: YYYYMMDDHHmmss
checksum
String
Yes
UTF-8 encoded SHA256 hashed values of the request parameters, which are concatenated in the following order: merchantId, merchantSiteId, userTokenId, clientRequestId, ccCardNumber, ccExpMonth, ccExpYear, ccNameOnCard, billingAddress, timeStamp, merchantSecretKey.

Output Parameters

Example Response

COPIED
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "52",
    "clientRequestId": "235", 
    "status": " SUCCESS ", 
    "errCode": "0",
    "reason": "",
    "version": "1",
    "userPaymentOptionId": "741", 
    "cardType": "",
    "ccToken": "",
    "brand": "Visa",
    "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=",
    "bin": "411111",
    "last4Digits": "1111"
}
PARAMETER TYPE DESCRIPTION
merchantId
String
Merchant ID provided by SafeCharge.
merchantSiteId
String
Merchant Site ID provided by SafeCharge.
internalRequestId
String
SafeCharge’s internal unique request ID, used for reconciliation purpose, etc.
clientRequestId
String
ID of the API request in the merchant’s system.
status
String
The status of merchant’s API request/call. Possible statuses: SUCCESS or ERROR.
errCode
Integer
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
String
The current version of the request. The current version is 1.
userPaymentOptionId
String
Each 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. When a new payment method is used, the value of this parameter is left empty.
cardType
String
Value describing if the card used is a credit card or debit card.
ccToken
String
A hashed value of the credit card number.
brand
String
The brand of the credit card, i.e. Visa, Master_Card, etc.
uniqueCC
String
A unique identifying code for the credit card.
bin
String
The credit card’s bin number.
last4Digits
String
The last four digits of the credit card number.

addUPOCreditCardByToken

This method adds a credit card token for a specific user according to the User Token ID. Tokens are strings of random digits, letters, and symbols characters that represent a single credit card number. When submitting consumer’s full credit card number, SafeCharge provides a token in the response that represents the consumer’s credit card. The next time the consumer completes a transaction, the merchant sends SafeCharge the token instead of the consumer’s credit card information. The token value represents the consumer’s credit card number.



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCardByToken.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
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033", 
    "userTokenId": "487106",
    "clientRequestId": "110",
    "ccExpMonth": "12",
    "ccExpYear": "24", 
    "ccNameOnCard": "John Smith", 
    "ccToken":"ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0ATwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA==",
    "brand": "Visa",
    "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=", 
    "bin": "411111",
    "last4Digits": "1111",
    "billingAddress":{
        "firstName": "some first name",
        "lastName": "some last name",
        "address": "some street",
        "phone": "972502457558",
        "zip": "",
        "city": "some city",
        "countryCode": "GB",
        "state": "",
        "email": "someemail@somedomain.com",
        "county":""
    },
    "lastDepositUse":"", 
    "lastDepositSuccess":"", 
    "lastWithdrawalUse":"", 
    "lastWithdrawalSuccess":"", 
    "registrationDate":"", 
    "expiryDate":"",
    "timeStamp": "20150915161438",
    "checksum": "f84c4e7e7d5aa1e83cd785100746bafc"
}